クエリビルダーの SQL 変数

クエリビルダーで SQL 変数を使用する方法を説明します。これにより、クエリを再利用でき、コードにデータをハードコーディングせずに済みます。

SQL 変数を使用する理由

SQL 変数を使用する利点を以下に示します。

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

変数の使用

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

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

1
{{variable_type.${custom_label}}}

次のように置き換えます。

次の例では、あるキャンペーンについて、月の初日から最終日までのユーザー数の合計を照会している。次のステップで各変数に値が割り当てられます。

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:値を割り当てる

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

以下の例では、2025年6月の月初日と月末日の値とともに、「Summer Feature Launch」キャンペーンが値として割り当てられます。

一般的な変数タイプ

数値

number は、他の文字列以外の変数と組み合わせて使用できます。5.5 のような小数を含む、あらゆる正負の数を受け入れます。

• 使用法

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

string

繰り返される文字列値をレポート実行の合間に変更する場合に使用します。この変数を使用すると、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'

options

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

• 使用法

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 が使用されます。

キャンペーン

• 1つのキャンペーン
• 複数のキャンペーン
• キャンペーンバリアント

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つのキャンバス
• 複数のキャンバス
• キャンバスバリアント
• 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 = '{{custom_events.${Purchased Game}}}';

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

ワークスペース

workspace は、Braze ダッシュボードから1つのワークスペースを選択するために使用されます。

• 使用法

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

カタログ

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

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

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

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

セグメント

Analytics Trackingが有効になっているSegmentを選択します。これをセグメントの分析 ID に設定します。これは、user_segment_membership_ids 列を含むテーブルでその列に格納されている ID に対応します。

• 使用法

1
{{segments.${analytics_segments}}}

タグ

キャンペーンやキャンバスのタグを選択する場合に使用します。選択したタグに関連付けられている BSON ID を持つキャンペーンまたはキャンバスに設定します。BSON ID は一重引用符で囲み、コンマで区切ります。

• 使用法

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'}})

可視

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

他の変数に値があるかどうかなど、値が他の変数に依存する特殊変数がいくつかあります。これらの特殊変数は、Variablesタブに表示されないように、非表示としてマークされます。

• 使用法

1
visible: 'false'

required

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

• 使用法

1
required: 'false'

order

[変数] タブでの変数の位置を選択する場合に使用します。

• 使用法

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'