Variáveis SQL do Criador de consultas

Saiba como usar variáveis SQL no Criador de consultas para reutilizar suas consultas e evitar codificar dados diretamente no seu código.

Por que usar variáveis SQL?

Os benefícios de usar variáveis SQL incluem:

• Economizar tempo criando uma variável de Campaign para selecionar a partir de uma lista ao criar seu relatório, em vez de colar IDs de Campaign.
• Trocar valores adicionando variáveis que permitem reutilizar o relatório para casos de uso ligeiramente diferentes no futuro (como um evento personalizado diferente).
• Reduzir erros do usuário ao editar seu SQL, diminuindo a quantidade de edição necessária para cada relatório. Colegas mais familiarizados com SQL podem criar relatórios que colegas menos técnicos podem usar.

Usando variáveis

Etapa 1: Adicionar uma variável

Para adicionar uma variável à sua consulta, use a seguinte sintaxe:

1
{{variable_type.${custom_label}}}

Substitua o seguinte:

No exemplo a seguir, o número total de usuários entre o primeiro e o último dia de um mês é consultado para uma Campaign. Cada variável receberá um valor na próxima etapa.

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

Etapa 2: Atribuir um valor

Por padrão, a guia Variables não é exibida no Criador de consultas. Ela só aparece após adicionar sua primeira variável à consulta. Lá, você poderá atribuir um valor a ela. Os valores específicos que você pode escolher dependerão do tipo daquela variável.

No exemplo a seguir, a Campaign “Summer Feature Launch” é atribuída como valor, junto com o primeiro e o último dia de junho de 2025.

Tipos de variáveis gerais

Number

number pode ser usado em combinação com outras variáveis que não sejam string. Aceita qualquer número positivo ou negativo, incluindo números decimais, como 5.5.

• uso

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

String

Para alterar valores de string repetitivos entre execuções de relatório. Use esta variável para evitar codificar um valor várias vezes no seu SQL.

• uso

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

List

Para selecionar a partir de uma lista de opções.

• escolher uma
• escolher múltiplas

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

Botão de rádio

Para exibir opções como botões de rádio em vez de um menu suspenso na guia Variables. Não pode ser usado sozinho—deve ser usado em combinação com uma lista.

• uso

1
is_radio_button: 'true'

Seleção múltipla

Para definir se o menu suspenso permite seleção única ou múltipla. Não pode ser usado sozinho—deve ser usado em combinação com uma lista.

• uso

1
is_multi_select: 'true'

Opções

Para fornecer a lista de opções selecionáveis na forma de rótulo e valor. O rótulo é o que é exibido e o valor é o que substitui a variável quando a opção é selecionada. Não pode ser usado sozinho—deve ser usado em combinação com uma lista.

• uso

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

Tipos de variáveis específicos da Braze

Intervalo de datas

Para exibir um calendário para selecionar datas. Substitua start_date e end_date por um timestamp Unix em segundos para uma data especificada em UTC, como 1696517353. Opcionalmente, você pode definir apenas um start_date ou end_date para exibir apenas uma única data no calendário. Se os rótulos do seu start_date e end_date não coincidirem, eles serão tratados como duas datas separadas, em vez de um intervalo de datas.

• uso

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

Você pode definir o intervalo de datas para qualquer uma das seguintes opções. Se tanto start_date quanto end_date forem usados e compartilharem o mesmo rótulo, todas as opções serão exibidas. Caso contrário, se apenas um for usado, somente a opção especificada será exibida.

Seu Liquid será usado para exibir um calendário dentro do intervalo de datas fornecido:

Campaigns

• uma campaign
• múltiplas campaigns
• variantes de campaign

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

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

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

Canvas

• um canvas
• múltiplos canvas
• variantes de canvas
• uma etapa do canvas
• múltiplas etapas do canvas

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

Produtos

products é usado para selecionar um ou mais produtos do dashboard da Braze.

• uso
• exemplo

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

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

Eventos personalizados

Selecione um ou mais eventos personalizados ou propriedades de eventos personalizados a partir de uma lista.

• evento
• propriedades

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

Espaço de trabalho

workspace é usado para selecionar um único espaço de trabalho do dashboard da Braze.

• uso

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

Catálogos

Selecione um ou mais catálogos ou campos de catálogo a partir de uma lista.

• catálogos
• campos de catálogo

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

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

Segments

Para selecionar Segments que tenham o rastreamento de análise de dados ativado. Defina como o ID de análise de dados do Segment, que corresponde aos IDs armazenados na coluna user_segment_membership_ids nas tabelas onde essa coluna está disponível.

• uso

1
{{segments.${analytics_segments}}}

Tags

Para selecionar tags para Campaigns e Canvas. Defina para Campaigns e Canvas com IDs BSON separados por vírgulas e entre aspas simples que estejam associados às tags selecionadas.

• uso

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

Metadados de variáveis

Metadados podem ser anexados a uma variável para alterar seu comportamento, adicionando os metadados com um caractere de pipe ( | ) após o rótulo da variável. A ordem dos metadados não importa e você pode adicionar qualquer quantidade deles. Além disso, todos os tipos de metadados podem ser usados para qualquer variável, exceto metadados especiais que são específicos de certas variáveis (isso será indicado nesses casos). O uso de todos os metadados é opcional e serve para alterar o comportamento padrão da variável.

• uso

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

Booleano

Para saber se o valor de uma variável está preenchido. Isso é útil para variáveis opcionais onde você deseja encurtar uma condição se o valor de uma variável não estiver preenchido. Pode ser definido como true ou false dependendo do valor da outra variável.

• uso

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

type e name referem-se à variável referenciada. Por exemplo, para encurtar a seguinte variável opcional: {{campaigns.${messaging}}:

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

Visível

Para definir se as variáveis são visíveis. Todas as variáveis são visíveis por padrão na guia Variables, onde você pode inserir valores.

Existem várias variáveis especiais cujo valor depende de outra variável, como se outra variável tem um valor. Essas variáveis especiais são marcadas como não visíveis para que não apareçam na guia Variables.

• uso

1
visible: 'false'

Obrigatória

Para definir se as variáveis são obrigatórias por padrão. Um valor vazio para uma variável geralmente leva a uma consulta incorreta.

• uso

1
required: 'false'

Ordem

Para selecionar a posição da variável na guia Variables.

• uso

1
order: '1'

Incluir aspas

• aspas simples
• aspas duplas

1
include_quotes: 'true'

1
include_double_quotes: 'true'

Placeholder

Para especificar o texto de placeholder exibido no campo de entrada da variável.

• uso

1
placeholder: 'enter some value'

Descrição

Para especificar o texto de descrição exibido abaixo do campo de entrada da variável.

• uso

1
description: 'some description'

Valor padrão

Para especificar o valor padrão da variável quando nenhum valor é especificado.

• uso

1
default_value: '5'

Ocultar rótulo

Para ocultar o rótulo da variável.

• uso

1
hide_label: 'true'