Variáveis do Construtor de Consultas SQL

Aprenda a usar variáveis SQL no Construtor de Consultas, para que você possa reutilizar suas consultas e evitar codificar dados diretamente em seu código.

Por que usar variáveis SQL?

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

• Economize tempo criando uma variável de campanha para selecionar em uma lista ao criar seu relatório, em vez de colar os IDs de campanha.
• Troque os valores adicionando variáveis que lhe permitam reutilizar o relatório para casos de uso ligeiramente diferentes no futuro (como um evento personalizado diferente).
• Reduza o erro do usuário ao editar seu SQL, reduzindo a quantidade de edição necessária para cada relatório. Os colegas de equipe que se sentem mais à vontade com o SQL podem criar relatórios que podem ser usados por colegas de equipe menos técnicos.

Uso de 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 campanha. Cada variável será atribuída a 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 aba Variáveis não é exibida no Construtor 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 dessa variável específica.

No exemplo a seguir, a campanha “Lançamento de Recursos de Verão” é atribuída como um valor, junto com os primeiros e últimos dias de junho de 2025.

Tipos de variáveis gerais

Número

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

• usage

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

String

Para alterar os valores repetitivos da string entre as execuções do relatório. Use essa variável para evitar a codificação de um valor várias vezes em seu SQL.

• usage

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

Lista

Para selecionar em uma lista de opções.

• choose one
• choose multiple

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 mostrar opções como botões de rádio em vez de um menu suspenso de seleção na guia Variables (Variáveis ). Isso não pode ser usado sozinho—deve ser usado em combinação com uma lista.

• usage

1
is_radio_button: 'true'

Seleção múltipla

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

• usage

1
is_multi_select: 'true'

Opções

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

• usage

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

Tipos de variáveis específicos do Braze

Período

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.

• usage

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 ambos start_date e 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, então apenas a opção especificada será exibida.

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

Campanhas

• one campaign
• multiple campaigns
• campaign variants

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

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

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

Canvas

• one canvas
• multiple canvases
• canvas variants
• one canvas step
• multiple canvas steps

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 painel do Braze.

• usage
• example

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 de uma lista.

• event
• properties

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 painel do Braze.

• usage

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

Catálogos

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

• catalogs
• catalog fields

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

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

Segmentos

Para selecionar segmentos que tenham a análise de dados ativada. Defina isso para o ID de análise de segmento, que corresponde aos IDs armazenados na coluna user_segment_membership_ids nas tabelas onde essa coluna está disponível.

• usage

1
{{segments.${analytics_segments}}}

Tags

Para selecionar tags para campanhas e telas. Defina para Campanhas e Canvases com IDs BSON separados por vírgulas entre aspas simples que estão associados às tags selecionadas.

• usage

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

Metadados variáveis

• usage

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 interromper 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.

• usage

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 interromper o 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 saber se as variáveis estão visíveis. Todas as variáveis são visíveis por padrão na guia Variables (Variáveis ), onde você pode inserir valores.

Há diversas variáveis especiais cujo valor depende de outra variável, como, por exemplo, se outra variável tem um valor. Essas variáveis especiais são marcadas como não visíveis para que não sejam exibidas na guia Variáveis.

• usage

1
visible: 'false'

Obrigatória

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

• usage

1
required: 'false'

Pedido

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

• usage

1
order: '1'

Incluir aspas

• single quotes
• double quotes

1
include_quotes: 'true'

1
include_double_quotes: 'true'

Espaço reservado

Para especificar o texto de espaço reservado mostrado no campo de entrada da variável.

• usage

1
placeholder: 'enter some value'

Descrição

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

• usage

1
description: 'some description'

Valor padrão

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

• usage

1
default_value: '5'

Ocultar rótulo

Para ocultar o rótulo da variável.

• usage

1
hide_label: 'true'