コンテンツにスキップ

クエリビルダー

クエリビルダーは、SnowflakeのBrazeデータを使用してレポートを生成します。クエリビルダーには、すぐに使い始められるビルド済みのSQLクエリテンプレートが付属しています。また、独自のカスタムSQLクエリを記述して、さらに多くのインサイトを引き出すこともできます。

前提条件

クエリビルダーを使用するには、ワークスペースレベルで以下の権限が必要です。

権限 許可される操作
「ダッシュボードレポートの表示」 ダッシュボードでクエリビルダーを開く
「PIIの表示」 顧客データを含む可能性があるクエリビルダーのデータにアクセスする
「ダッシュボードレポートの編集」 クエリビルダーのレポートを作成、編集、実行する

利用可能なデータテーブル

クエリビルダーは、SQLセグメントエクステンションやSnowflakeデータ共有と同じSnowflake SQLテーブルを使用します。利用可能なテーブルとその列の完全なリストについては、SQLテーブルリファレンスを参照してください。

ユーザープロファイル属性ビュー

クエリビルダーとSQLセグメントエクステンションには、定期的なスナップショットやデフォルト属性の履歴など、ほとんどのユーザープロファイル属性ビューが含まれています。

カスタム属性の次の2つのビューは、Snowflakeデータ共有からのみ利用できます。

  • USER_CUSTOM_ATTRIBUTES_HISTORY_VIEW_SHARED
  • USER_LATEST_STATE_CUSTOM_ATTRIBUTE_VIEW_SHARED

これらのビューはワークスペース規模でのクエリに時間がかかり、タイムアウトすることが多いため、Brazeはクエリビルダーとセグメントエクステンションから除外しています。クエリビルダーでカスタム属性のスナップショットを取得するには、USER_CUSTOM_ATTRIBUTES_VIEW_SHAREDを使用してください。過去のカスタム属性データやほぼリアルタイムのカスタム属性データが必要な場合は、代わりにSnowflakeデータ共有を通じて除外されたビューをクエリしてください。

クエリビルダーでのレポートの実行

クエリビルダーのレポートを実行するには、以下の手順に従ってください。

  1. 分析 > クエリビルダーに移動します。
  2. SQLクエリを作成を選択します。クエリ作成のヒントやサポートが必要な場合は、クエリテンプレートを選択し、リストからテンプレートを選びます。それ以外の場合は、SQLエディターを選択してエディターに直接進みます。
  3. レポートには、現在の日時を含む名前が自動的に付けられます。名前にカーソルを合わせて を選択し、SQLクエリにわかりやすい名前を付けます。
  4. エディターでSQLクエリを記述するか、Operatorに質問を選択してOperatorでSQLを生成します。独自のSQLを記述する場合は、要件とリソースについてカスタムSQLクエリの記述を参照してください。
  5. クエリを実行を選択します。
  6. クエリを保存します。
  7. レポートのCSVをダウンロードするには、エクスポートを選択します。

テンプレートクエリ「過去30日間のチャネルエンゲージメントと収益」の結果を表示しているクエリビルダー。

レポートを実行するたびに、クエリビルダーはSnowflakeで現在利用可能なデータをクエリします。新しいデータが届くと、同じ日のうちでも実行ごとに結果が変わる場合があります。取り込みと処理の遅延により、最近のイベントが表示されるまでに時間がかかることがあります。

クエリテンプレート

レポートを最初に作成する際に、SQLクエリを作成 > クエリテンプレートを選択すると、クエリテンプレートにアクセスできます。

利用可能なテンプレートの一覧については、クエリテンプレートを参照してください。

データの時間枠

クエリは過去60日間のデータを返します。CurrentsまたはSnowflakeデータ共有を使用している場合は、Snowflakeでデータが保持される期間である最大2年分のデータをクエリできる場合があります。データ保持期間の延長について詳しくは、カスタマーサクセスマネージャーにお問い合わせください。

クエリビルダーのタイムゾーン

Snowflakeデータベースをクエリする際のデフォルトのタイムゾーンはUTCです。そのため、メールチャネルエンゲージメントページ（会社のタイムゾーンに従います）とクエリビルダーの結果との間で、データに差異が生じる場合があります。

クエリ結果のタイムゾーンを変換するには、以下のSQLをクエリに追加し、会社のタイムゾーンに合わせてカスタマイズしてください。




SELECT
DATE_TRUNC(
'day',
CONVERT_TIMEZONE('UTC','Australia/Sydney', TO_TIMESTAMP(TIME))
) AS send_date_sydney,
COUNT(ID) AS emails_sent
USERS_MESSAGES_EMAIL_SEND_SHARED
WHERE
-- Apply the date range in Sydney time as well
CONVERT_TIMEZONE('UTC','Australia/Sydney', TO_TIMESTAMP(TIME)) >= '2025-03-25 00:00:00'
AND CONVERT_TIMEZONE('UTC','Australia/Sydney', TO_TIMESTAMP(TIME)) < '2025-03-29 00:00:00'
AND APP_GROUP_ID = 'your app group ID'
GROUP BY
send_date_sydney
ORDER BY
send_date_sydney;

クエリ履歴

クエリビルダーのクエリ履歴セクションには、以前に実行したクエリが表示され、作業の追跡や再利用に役立ちます。クエリ履歴は7日間保持され、7日より古いクエリは自動的に削除されます。

より長い期間にわたってクエリの使用状況を監査する必要がある場合や、7日を超えて記録を保持する必要がある場合は、期限が切れる前に重要なクエリ結果をエクスポートまたは保存することをおすすめします。

クエリビルダーと他のレポートソースの比較

クエリビルダーの結果は、異なるデータソースと処理方法を使用しているため、他のレポートツールの結果と異なる場合があります。

たとえば、クエリビルダーのソフトバウンス数は、SendGrid配信到達性レポートよりも多くなる場合があります。クエリビルダーは、重複排除を行わずにすべてのソフトバウンスの発生をカウントします。ユーザーが最終的に配信されるまでに（または長時間の再試行後に）複数回ソフトバウンスした場合、各ソフトバウンスの試行がカウントされます。SendGrid配信到達性は独自のデータとロジックを使用しており、Brazeはそれらを確認できないため、2つのレポート間でカウントが一致しない場合があります。

さまざまなレポートソースでソフトバウンスがどのように追跡されるかについて詳しくは、メール分析用語集のソフトバウンスを参照してください。

Operatorを使用したSQLの生成

クエリビルダーのサイドパネルでAsk Operatorを選択し、必要なデータを説明します。Operatorは利用可能なBrazeデータテーブルに対してSQLを作成します。レポートを実行する前に、SQLを確認して結果をプレビューできます。クエリビルダーでOperatorを使用するには、「ダッシュボードレポートの編集」権限が必要です。

生成されたSQLは、自分で作成するクエリと同じSQL作成ルールに従う必要があります。詳しくは、Operatorでできることを参照してください。Operatorによるデータの取り扱いについては、Operatorのデータプライバシーとセキュリティを参照してください。

カスタムSQLクエリの記述

Snowflake構文を使用してSQLクエリを記述します。クエリ可能なテーブルとカラムの完全なリストについては、テーブルリファレンスを参照してください。

クエリビルダー内でテーブルの詳細を表示するには:

  1. クエリビルダーページから、Referenceパネルを開き、Available Data Tablesを選択して、利用可能なデータテーブルとその名前を表示します。
  2. See Detailsを選択して、テーブルの説明やデータタイプなどのテーブルカラムに関する情報を表示します。
  3. SQLにテーブル名を挿入するには、 Copy table name to SQL editorを選択します。

Brazeが提供するビルド済みクエリを使用するには、クエリビルダーでレポートを最初に作成するときにQuery Templateを選択します。

クエリを特定の期間に制限すると、結果をより速く生成できます。以下は、過去1時間の購入数と生成された収益を取得するクエリの例です。




SELECT COUNT(*) as Purchases, SUM(price) as Revenue
FROM USERS_BEHAVIORS_PURCHASE_SHARED
WHERE to_date(to_timestamp_ntz(time)) >= DATEADD('hour', -1, date_trunc('day',CURRENT_DATE()));

このクエリは、過去1か月間のメール送信数を取得します:




SELECT COUNT(*) as Sends
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
WHERE to_date(to_timestamp_ntz(time)) >= DATEADD('month', -1, date_trunc('day',CURRENT_DATE()));

CANVAS_ID、CANVAS_VARIATION_API_ID、またはCAMPAIGN_IDをクエリすると、関連する名前カラムが結果テーブルに自動的に含まれます。SELECTクエリ自体にそれらを含める必要はありません。

ID名 関連する名前カラム
CANVAS_ID キャンバス名
CANVAS_VARIATION_API_ID キャンバスバリアント名
CAMPAIGN_ID キャンペーン名

このクエリは、3つのIDすべてとそれに関連する名前カラムを最大100行で取得します:




SELECT CANVAS_ID, CANVAS_VARIATION_API_ID, CAMPAIGN_ID
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
LIMIT 100

キャンペーンバリアント名を自動入力する

キャンペーンバリアント名を自動入力するには、次の例のようにクエリにカラム名MESSAGE_VARIATION_API_IDを含めます:




SELECT CANVAS_ID, CANVAS_VARIATION_API_ID, CAMPAIGN_ID, MESSAGE_VARIATION_API_ID
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
LIMIT 100

トラブルシューティング

クエリは以下のいずれかの理由で失敗する場合があります:

  • SQLクエリの構文エラー
  • 処理タイムアウト（6分後）
    • 実行に6分以上かかるレポートはタイムアウトします。
    • レポートがタイムアウトした場合は、データをクエリする期間を制限するか、より具体的なデータセットをクエリしてみてください。

変数の使用

変数を使用すると、SQLで定義済みの変数タイプを使用して、値を手動でコピーすることなく参照できます。たとえば、キャンペーンのIDをSQLエディターに手動でコピーする代わりに、{{campaign.${My campaign}}}を使用して、変数タブのドロップダウンからキャンペーンを直接選択できます。

変数を作成すると、クエリビルダーレポートの変数タブに表示されます。SQL変数を使用するメリットには以下があります。

  • レポート作成時にキャンペーンIDを貼り付ける代わりに、リストから選択できるキャンペーン変数を作成することで時間を節約できます。
  • 変数を追加して値を入れ替えることで、将来わずかに異なるユースケース（異なるカスタムイベントなど）にレポートを再利用できます。
  • 各レポートに必要な編集量を減らすことで、SQL編集時のユーザーエラーを軽減できます。SQLに慣れているチームメンバーがレポートを作成し、技術的な知識が少ないチームメンバーがそのレポートを利用できます。

ガイドライン

変数は次のLiquid構文に従う必要があります。{{ type.${name}}}。ここで、typeは受け入れられるタイプのいずれかである必要があり、nameは任意の名前を指定できます。これらの変数のラベルは、デフォルトで変数名になります。

デフォルトでは、すべての変数が必須です（変数の値を選択しないとレポートは実行されません）。ただし日付範囲は例外で、値が指定されていない場合はデフォルトで過去30日間になります。

変数タイプ

以下の変数タイプが受け入れられます。

数値

  • 置換値: 指定された値（5.5など）
  • 使用例: some_number_column < {{number.${some name}}}

日付範囲

start_dateとend_dateの両方を使用する場合、日付範囲として使用できるように、両者に同じ名前を付ける必要があります。

値の例

日付範囲タイプには、相対、開始日、終了日、日付範囲があります。

start_dateとend_dateの両方が同じ名前で使用されている場合、4つのタイプすべてが表示されます。片方のみを使用している場合は、関連するタイプのみが表示されます。

日付範囲タイプ 説明 必要な値
相対 過去X日間を指定します start_dateが必要
開始日 開始日を指定します start_dateが必要
終了日 終了日を指定します end_dateが必要
日付範囲 開始日と終了日の両方を指定します start_dateとend_dateの両方が必要
  • 置換値: start_dateとend_dateを、指定された日付（UTC）の秒単位のUnixタイムスタンプ（1696517353など）に置き換えます。
  • 使用例: 相対、開始日、終了日、日付範囲のすべての変数に対して:
    • time > {{start_date.${some name}}} AND time < {{end_date.${some name}}}
      • 日付範囲が不要な場合は、start_dateまたはend_dateのいずれかを使用できます。

メッセージング

メッセージング変数の状態を1つのグループにまとめたい場合は、すべてのメッセージング変数で同じ識別子を共有する必要があります。

キャンバス（単一）

1つのキャンバスを選択するためのものです。キャンペーンと同じ名前を共有すると、変数タブにキャンバスまたはキャンペーンのいずれかを選択するためのラジオボタンが表示されます。

  • 置換値: キャンバスのBSON ID
  • 使用例: canvas_id = ‘{{canvas.${some name}}}’
キャンバス（複数）

複数のキャンバスを選択するためのものです。キャンペーンと同じ名前を共有すると、変数タブにキャンバスまたはキャンペーンのいずれかを選択するためのラジオボタンが表示されます。

  • 置換値: キャンバスのBSON ID（複数）
  • 使用例: canvas_id IN ({{canvases.${some name}}})
キャンペーン（単一）

1つのキャンペーンを選択するためのものです。キャンバスと同じ名前を共有すると、変数タブにキャンバスまたはキャンペーンのいずれかを選択するためのラジオボタンが表示されます。

  • 置換値: キャンペーンのBSON ID
  • 使用例: campaign_id = ‘{{campaign.${some name}}}’
キャンペーン（複数）

複数のキャンペーンを選択するためのものです。キャンバスと同じ名前を共有すると、変数タブにキャンバスまたはキャンペーンのいずれかを選択するためのラジオボタンが表示されます。

  • 置換値: キャンペーンのBSON ID（複数）
  • 使用例: campaign_id IN ({{campaigns.${some name}}})
キャンペーンバリアント

選択したキャンペーンに属するキャンペーンバリアントを選択するためのものです。キャンペーン（単一）またはキャンペーン（複数）の変数と組み合わせて使用する必要があります。

  • 置換値: キャンペーンバリアントのAPI ID。api-id1, api-id2のようにカンマで区切られた文字列です。
  • 使用例: message_variation_api_id IN ({{campaign_variants.${some name}}})
キャンバスバリアント

選択したキャンバスに属するキャンバスバリアントを選択するためのものです。キャンバス（単一）またはキャンバス（複数）の変数と一緒に使用する必要があります。

  • 置換値: キャンバスバリアントのAPI ID。api-id1, api-id2のようにカンマで区切られた文字列です。
  • 使用例: canvas_variation_api_id IN ({{canvas_variants.${some name}}})
キャンバスステップ（単一）

選択したキャンバスに属するキャンバスステップを選択するためのものです。キャンバス（単一）の変数と一緒に使用する必要があります。

  • 置換値: キャンバスステップのAPI ID
  • 使用例: canvas_step_api_id = ‘{{canvas_step.${some name}}}’
キャンバスステップ（複数）

選択したキャンバスに属するキャンバスステップを選択するためのものです。キャンバス（単一）またはキャンバス（複数）の変数と一緒に使用する必要があります。

  • 置換値: キャンバスステップのAPI ID（複数）
  • 使用例: canvas_step_api_id IN ({{canvas_steps.${some name}}})

Brazeカスタマーエンゲージメントプラットフォームのドキュメント。

リソース
法的情報
会社情報
© 2026 Braze, Inc. All rights reserved.
Braze ステータスの確認
New Stuff!