SQL-Variablen im Abfrage-Builder

Erfahren Sie, wie Sie SQL-Variablen im Abfrage-Builder verwenden, um Ihre Abfragen wiederzuverwenden und das Hartcodieren von Daten in Ihrem Code zu vermeiden.

Warum SQL-Variablen verwenden?

Die Vorteile der Verwendung von SQL-Variablen umfassen:

• Zeitersparnis durch das Erstellen einer Campaign-Variable, die Sie beim Erstellen Ihres Berichts aus einer Liste auswählen können, anstatt Campaign-IDs einzufügen.
• Werte austauschen, indem Sie Variablen hinzufügen, mit denen Sie den Bericht für leicht abweichende Anwendungsfälle in der Zukunft wiederverwenden können (z. B. ein anderes angepasstes Event).
• Reduzierung von Nutzer:innenfehlern beim Bearbeiten Ihres SQL, indem der Bearbeitungsaufwand für jeden Bericht verringert wird. Teammitglieder, die sich mit SQL besser auskennen, können Berichte erstellen, die weniger technisch versierte Teammitglieder dann verwenden können.

Variablen verwenden

1. Schritt: Variable hinzufügen

Um eine Variable zu Ihrer Abfrage hinzuzufügen, verwenden Sie die folgende Syntax:

1
{{variable_type.${custom_label}}}

Ersetzen Sie Folgendes:

Im folgenden Beispiel wird die Gesamtzahl der Nutzer:innen zwischen dem ersten und letzten Tag eines Monats für eine Campaign abgefragt. Jeder Variable wird im nächsten Schritt ein Wert zugewiesen.

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. Schritt: Wert zuweisen

Standardmäßig wird der Tab Variablen im Abfrage-Builder nicht angezeigt. Er erscheint erst, nachdem Sie Ihre erste Variable zur Abfrage hinzugefügt haben. Dort können Sie ihr einen Wert zuweisen. Die spezifischen Werte, die Sie auswählen können, hängen vom Typ der jeweiligen Variable ab.

Im folgenden Beispiel wird die Campaign „Summer Feature Launch“ als Wert zugewiesen, zusammen mit dem ersten und letzten Tag des Juni 2025.

Allgemeine Variablentypen

Zahl

number kann in Kombination mit anderen Nicht-String-Variablen verwendet werden. Akzeptiert jede positive oder negative Zahl, einschließlich Dezimalzahlen, wie z. B. 5.5.

• verwendung

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

String

Zum Ändern sich wiederholender String-Werte zwischen Berichtsausführungen. Verwenden Sie diese Variable, um das Hartcodieren eines Werts an mehreren Stellen in Ihrem SQL zu vermeiden.

• verwendung

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

Liste

Zur Auswahl aus einer Liste von Optionen.

• einzelauswahl
• mehrfachauswahl

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"}]'}}

Optionsfeld (Radio Button)

Zum Anzeigen von Optionen als Optionsfelder anstelle eines Auswahl-Dropdowns im Tab Variablen. Dies kann nicht eigenständig verwendet werden—es muss in Kombination mit einer Liste verwendet werden.

• verwendung

1
is_radio_button: 'true'

Mehrfachauswahl

Legt fest, ob das Auswahl-Dropdown eine Einzel- oder Mehrfachauswahl ermöglicht. Dies kann nicht eigenständig verwendet werden—es muss in Kombination mit einer Liste verwendet werden.

• verwendung

1
is_multi_select: 'true'

Optionen

Zum Bereitstellen der Liste auswählbarer Optionen in Form eines Labels und eines Werts. Das Label wird angezeigt und der Wert ist das, wodurch die Variable ersetzt wird, wenn die Option ausgewählt wird. Dies kann nicht eigenständig verwendet werden—es muss in Kombination mit einer Liste verwendet werden.

• verwendung

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

Braze-spezifische Variablentypen

Datumsbereich

Zum Anzeigen eines Kalenders zur Datumsauswahl. Ersetzen Sie start_date und end_date durch einen Unix-Zeitstempel in Sekunden für ein bestimmtes Datum in UTC, z. B. 1696517353. Optional können Sie nur ein start_date oder end_date festlegen, um nur ein einzelnes Datum im Kalender anzuzeigen. Wenn die Labels Ihres start_date und end_date nicht übereinstimmen, werden sie als zwei separate Daten behandelt, anstatt als Datumsbereich.

• verwendung

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

Sie können den Datumsbereich auf eine der folgenden Optionen festlegen. Wenn sowohl start_date als auch end_date verwendet werden und dasselbe Label haben, werden alle Optionen angezeigt. Andernfalls wird nur die angegebene Option angezeigt, wenn nur eine verwendet wird.

Ihr Liquid wird verwendet, um einen Kalender innerhalb des angegebenen Datumsbereichs anzuzeigen:

Campaigns

• eine campaign
• mehrere campaigns
• kampagnenvarianten

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

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

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

Wichtig

Alle Campaign- und Canvas-Variablen müssen dieselben Bezeichner verwenden, um Zustände innerhalb einer einzelnen Gruppe zu synchronisieren.

Canvases

• ein canvas
• mehrere canvases
• canvas-varianten
• ein canvas-schritt
• mehrere canvas-schritte

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

Wichtig

Alle Campaign- und Canvas-Variablen müssen dieselben Bezeichner verwenden, um Zustände innerhalb einer einzelnen Gruppe zu synchronisieren.

Produkte

products wird verwendet, um ein oder mehrere Produkte aus dem Braze-Dashboard auszuwählen.

• verwendung
• beispiel

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

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

Angepasste Events

Wählen Sie ein oder mehrere angepasste Events oder Event-Eigenschaften angepasster Events aus einer Liste aus.

• event
• eigenschaften

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

workspace wird verwendet, um einen einzelnen Workspace aus dem Braze-Dashboard auszuwählen.

• verwendung

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

Kataloge

Wählen Sie einen oder mehrere Kataloge oder Katalogfelder aus einer Liste aus.

• kataloge
• katalogfelder

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

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

Segments

Zur Auswahl von Segmenten, bei denen Analytics-Tracking aktiviert ist. Wird auf die Segment-Analytics-ID gesetzt, die den in der Spalte user_segment_membership_ids gespeicherten IDs in den Tabellen entspricht, in denen diese Spalte verfügbar ist.

• verwendung

1
{{segments.${analytics_segments}}}

Tags

Zur Auswahl von Tags für Campaigns und Canvases. Wird auf Campaigns und Canvases mit einfach zitierten, kommagetrennten BSON-IDs gesetzt, die mit den ausgewählten Tags verknüpft sind.

• verwendung

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

Variablen-Metadaten

Metadaten können an eine Variable angehängt werden, um ihr Verhalten zu ändern, indem die Metadaten mit einem Pipe-Zeichen ( | ) nach dem Variablen-Label angehängt werden. Die Reihenfolge der Metadaten spielt keine Rolle und Sie können beliebig viele anhängen. Außerdem können alle Arten von Metadaten für jede Variable verwendet werden, mit Ausnahme spezieller Metadaten, die für bestimmte Variablen spezifisch sind (dies wird in diesen Fällen angegeben). Die Verwendung aller Metadaten ist optional und dient dazu, das Standardverhalten der Variable zu ändern.

• verwendung

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

Boolescher Wert

Um festzustellen, ob der Wert einer Variable ausgefüllt ist. Dies ist nützlich für optionale Variablen, bei denen Sie eine Bedingung kurzschließen möchten, wenn der Wert einer Variable nicht ausgefüllt ist. Kann je nach Wert der anderen Variable auf true oder false gesetzt werden.

• verwendung

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

type und name beziehen sich auf die referenzierte Variable. Um beispielsweise die folgende optionale Variable kurzzuschließen: {{campaigns.${messaging}}:

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

Sichtbar

Legt fest, ob Variablen sichtbar sind. Alle Variablen sind standardmäßig im Tab Variablen sichtbar, wo Sie Werte eingeben können.

Es gibt mehrere spezielle Variablen, deren Wert von einer anderen Variable abhängt, z. B. ob eine andere Variable einen Wert hat. Diese speziellen Variablen sind als nicht sichtbar markiert, damit sie nicht im Tab Variablen angezeigt werden.

• verwendung

1
visible: 'false'

Erforderlich

Legt fest, ob Variablen standardmäßig erforderlich sind. Ein leerer Wert für eine Variable führt in der Regel zu einer fehlerhaften Abfrage.

• verwendung

1
required: 'false'

Reihenfolge

Zur Auswahl der Position der Variable im Tab Variablen.

• verwendung

1
order: '1'

Anführungszeichen einschließen

• einfache anführungszeichen
• doppelte anführungszeichen

1
include_quotes: 'true'

1
include_double_quotes: 'true'

Platzhalter

Zum Festlegen des Platzhaltertexts, der im Eingabefeld der Variable angezeigt wird.

• verwendung

1
placeholder: 'enter some value'

Beschreibung

Zum Festlegen des Beschreibungstexts, der unter dem Eingabefeld der Variable angezeigt wird.

• verwendung

1
description: 'some description'

Standardwert

Zum Festlegen des Standardwerts für die Variable, wenn kein Wert angegeben wird.

• verwendung

1
default_value: '5'

Label ausblenden

Zum Ausblenden des Labels der Variable.

• verwendung

1
hide_label: 'true'