クエリビルダーのSQL変数

クエリビルダーでSQL変数を使用する方法を学び、クエリを再利用してコード内にデータをハードコーディングすることを避けましょう。

SQL変数を使用する理由

SQL変数を使用するメリットには以下があります。

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

変数の使用

ステップ 1: 変数を追加する

クエリに変数を追加するには、以下の構文を使用します。

1
{{variable_type.${custom_label}}}

以下を置き換えてください。

以下の例では、ある月の初日から最終日までのユーザー総数をCampaignに対してクエリしています。各変数には次のステップで値が割り当てられます。

1
2
3
4
5
SELECT COUNT(*) AS total_users
FROM USERS_CAMPAIGNS_REVENUE_SHARED
WHERE campaign_id = '{{campaign.${Campaign}}}'
  AND TIME > '{{start_date.${Month First Day}}}'
  AND TIME < '{{end_date.${Month Last Day}}}';

ステップ 2: 値を割り当てる

デフォルトでは、クエリビルダーに変数タブは表示されません。クエリに最初の変数を追加した後にのみ表示されます。そこで値を割り当てることができます。選択できる具体的な値は、その変数のタイプによって異なります。

以下の例では、「Summer Feature Launch」Campaignが値として割り当てられ、2025年6月の初日と最終日も設定されています。

汎用変数タイプ

数値

numberは他の非文字列変数と組み合わせて使用できます。5.5のような小数を含む、正または負の任意の数値を受け付けます。

• 使用方法

1
some_number_column < {{number.${custom_label}}}

文字列

レポート実行間で繰り返される文字列値を変更するために使用します。SQL内で値を複数回ハードコーディングすることを避けるためにこの変数を使用してください。

• 使用方法

1
'{{string.${add a string here.}}}'

リスト

オプションのリストから選択するために使用します。

• 1つ選択
• 複数選択

1
{{options.${metrics} | is_radio_button: 'true' | options: '[{"label": "test", "value": "test_value"}, {"label": "test2", "value": "test_value2"}]'}}

1
{{options.${metrics} | is_multi_select: 'true' | options: '[{"label": "test", "value": "test_value"}, {"label": "test2", "value": "test_value2"}]'}}

ラジオボタン

変数タブでセレクトドロップダウンの代わりにラジオボタンとしてオプションを表示するために使用します。単独では使用できません—リストと組み合わせて使用する必要があります。

• 使用方法

1
is_radio_button: 'true'

複数選択

セレクトドロップダウンで単一選択または複数選択を許可するかどうかを設定します。単独では使用できません—リストと組み合わせて使用する必要があります。

• 使用方法

1
is_multi_select: 'true'

オプション

ラベルと値の形式で選択可能なオプションのリストを提供するために使用します。ラベルは表示されるもので、値はオプションが選択されたときに変数が置き換えられるものです。単独では使用できません—リストと組み合わせて使用する必要があります。

• 使用方法

1
options: '[{"label": "test", "value": "test_value"}, {"label": "test2", "value": "test_value2"}]'

Braze固有の変数タイプ

日付範囲

日付を選択するためのカレンダーを表示するために使用します。start_dateとend_dateをUTCの指定された日付のUnixタイムスタンプ（秒単位）に置き換えてください（例: 1696517353）。オプションで、start_dateまたはend_dateのみを設定して、カレンダーに単一の日付のみを表示することもできます。start_dateとend_dateのラベルが一致しない場合、日付範囲ではなく2つの別々の日付として扱われます。

• 使用方法

1
time > {{start_date.${custom_label}}} AND time < {{end_date.${custom_label}}}

日付範囲は以下のオプションのいずれかに設定できます。start_dateとend_dateの両方が使用され、同じラベルを共有している場合、すべてのオプションが表示されます。それ以外の場合、1つのみが使用されている場合は、指定されたオプションのみが表示されます。

Liquidは指定された日付範囲内にカレンダーを表示するために使用されます。

Campaigns

• 1つのcampaign
• 複数のcampaigns
• campaignバリアント

1
campaign_id = '{{campaign.${custom_label}}}'

1
campaign_id IN ({{campaigns.${custom_label}}})

1
message_variation_api_id IN ({{campaign_variants.${custom_label}}})

Canvases

• 1つのcanvas
• 複数のcanvases
• canvasバリアント
• 1つのキャンバスステップ
• 複数のキャンバスステップ

1
canvas_id = '{{canvas.${custom_label}}}'

1
canvas_id IN ({{canvases.${custom_label}}})

1
canvas_variation_api_id IN ({{canvas_variants.${custom_label}}})

1
canvas_step_api_id = '{{canvas_step.${custom_label}}}'

1
canvas_step_api_id IN ({{canvas_steps.${custom_label}}})

製品

productsはBrazeダッシュボードから1つ以上の製品を選択するために使用します。

• 使用方法
• 例

1
({{products.${custom_label}}})

1
2
3
SELECT product_name
FROM FULL_GAME_AND_DLC
WHERE product_id IN ({{products.${Games with DLC}}});

カスタムイベント

リストから1つ以上のカスタムイベントまたはカスタムイベントプロパティを選択します。

• イベント
• プロパティ

1
'{{custom_events.${custom_label}}}'

1
2
3
SELECT event_name
FROM CUSTOM_EVENTS_TABLE
WHERE event_name IN ({{custom_events.${Purchased Game}}});

1
name = '{{custom_event_properties.${property names)}}}'

ワークスペース

workspaceはBrazeダッシュボードから単一のワークスペースを選択するために使用します。

• 使用方法

1
workspace_id = '{{workspace.${app_group_id}}}'

カタログ

リストから1つ以上のカタログまたはカタログフィールドを選択します。

• カタログ
• カタログフィールド

1
catalog_id = '{{catalogs.${catalog}}}'

1
field_name = '{{catalog_fields.${custom_label}}}'

Segments

分析トラッキングが有効になっているSegmentsを選択するために使用します。Segmentの分析IDに設定します。これは、このカラムが利用可能なテーブルのuser_segment_membership_idsカラムに格納されているIDに対応します。

• 使用方法

1
{{segments.${analytics_segments}}}

タグ

CampaignsおよびCanvasesのタグを選択するために使用します。選択されたタグに関連付けられた、シングルクォートでカンマ区切りのBSON IDを持つCampaignsおよびCanvasesに設定されます。

• 使用方法

1
{{tags.${some tags}}}

変数メタデータ

メタデータを変数に付加して動作を変更できます。変数ラベルの後にパイプ（ | ）文字を使用してメタデータを追加します。メタデータの順序は関係なく、任意の数を追加できます。また、すべてのタイプのメタデータは任意の変数に使用できますが、特定の変数に固有の特殊メタデータは除きます（その場合は該当箇所に記載されます）。すべてのメタデータの使用はオプションであり、変数のデフォルト動作を変更するために使用されます。

• 使用方法

1
{{string.${my var}| is_required: 'false' | description: 'My optional string var'}}

ブール値

変数の値が入力されているかどうかを判定するために使用します。これは、変数の値が入力されていない場合に条件をショートサーキットしたいオプション変数に便利です。他の変数の値に応じてtrueまたはfalseに設定できます。

• 使用方法

1
{{string.${type_name_has_no_value} | visible: 'false'}} or {{string.${type_name_has_value} | visible: 'false'}}

typeとnameは参照される変数を指します。例えば、以下のオプション変数をショートサーキットする場合: {{campaigns.${messaging}}:

1
{{string.${campaigns_messaging_has_no_value}  | visible: 'false'}} OR campaign_id IN ({{campaigns.${messaging} | is_required: 'false'}})

表示

変数を表示するかどうかを設定します。すべての変数はデフォルトで変数タブに表示され、そこで値を入力できます。

他の変数に依存する値を持つ特殊な変数がいくつかあります（例: 別の変数に値があるかどうかなど）。これらの特殊変数は非表示としてマークされ、変数タブには表示されません。

• 使用方法

1
visible: 'false'

必須

変数がデフォルトで必須かどうかを設定します。変数の値が空の場合、通常は不正なクエリになります。

• 使用方法

1
required: 'false'

順序

変数タブ内の変数の位置を選択するために使用します。

• 使用方法

1
order: '1'

引用符の付加

• シングルクォート
• ダブルクォート

1
include_quotes: 'true'

1
include_double_quotes: 'true'

プレースホルダー

変数の入力フィールドに表示されるプレースホルダーテキストを指定するために使用します。

• 使用方法

1
placeholder: 'enter some value'

説明

変数の入力フィールドの下に表示される説明テキストを指定するために使用します。

• 使用方法

1
description: 'some description'

デフォルト値

値が指定されていない場合の変数のデフォルト値を指定するために使用します。

• 使用方法

1
default_value: '5'

ラベルを非表示にする

変数のラベルを非表示にするために使用します。

• 使用方法

1
hide_label: 'true'