Ingestão de dados na nuvem: Editor SQL

Esta página explica como usar o Editor SQL da Ingestão de dados na nuvem (CDI) da Braze para criar e validar sincronizações com consultas de SQL.

Com o Editor SQL da Ingestão de dados na nuvem, você cria sincronizações escrevendo consultas de SQL diretamente no seu data warehouse. Assim, não é mais preciso criar ou manter uma tabela CDI dedicada, que antes era obrigatória na Etapa 1.1 das Integrações de data warehouse.

Use o Editor SQL quando quiser:

• Sincronizar dados sem modificar tabelas upstream
• Trabalhar com dados brutos no seu warehouse
• Evitar a construção de uma coluna PAYLOAD
• Lidar com casos de uso de dados mais complexos com SQL

Pré-requisitos e limitações

O SQL Editor tem as seguintes limitações:

• Disponível apenas para fontes de data warehouse: Snowflake, Redshift, BigQuery, Databricks e Fabric.
• Somente consultas de instrução única e somente leitura são compatíveis.

Nota

A Braze executa apenas consultas somente leitura nos seus dados e não modifica suas tabelas subjacentes. Objetos temporários podem ser criados durante a execução da consulta, mas não são mantidos.

Criar uma nova sincronização no SQL Editor

Siga estas etapas para criar primeiro uma fonte e, depois, uma sincronização com o SQL Editor. Se você já configurou uma fonte para a CDI, pode pular para a Etapa 3.

Nota

Estas etapas usam uma fonte Snowflake como exemplo. O processo de configuração para outras fontes de data warehouse é parecido. Você encontra os detalhes em Etapa 2: Criar uma nova fonte no dashboard da Braze, na documentação Configurando integrações de data warehouse.

Etapa 1: Configurar a função, as permissões, o warehouse e o usuário no Snowflake

Antes de criar sua fonte Snowflake na CDI, confira se o usuário do Snowflake usado pela Braze tem acesso aos dados que você quer consultar e a um warehouse para executar as consultas.

Etapa 1.1: (Opcional) Criar um banco de dados e um schema

Se necessário, crie um banco de dados e um schema dedicados para seus dados da CDI:

1
2

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;

Etapa 1.2: Configurar a função e as permissões do banco de dados

Conceda acesso às tabelas que você quer sincronizar:

1
2
3
4
5

CREATE ROLE BRAZE_INGESTION_ROLE;

GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.MY_USER_TABLE TO ROLE BRAZE_INGESTION_ROLE;

Dependendo do seu caso de uso, você também pode conceder acesso a várias tabelas ou a tabelas futuras. Por exemplo, para conceder acesso a todas as tabelas futuras de um schema:

1

GRANT SELECT ON FUTURE TABLES IN SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;

Etapa 1.3: Configurar o warehouse e conceder acesso à função da Braze

Crie um warehouse para a Braze executar consultas:

1
2

CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

Nota

O warehouse precisa estar com a opção de retomada automática (auto-resume) ativada. Caso contrário, conceda à Braze privilégios adicionais de OPERATE no warehouse para que a Braze possa ativá-lo quando a consulta for executada.

Etapa 1.4: Criar um usuário no Snowflake

A Braze se autentica no Snowflake usando Workload Identity Federation ou um par de chaves RSA. As credenciais existentes com par de chaves RSA continuam funcionando, e você não precisa migrá-las. Siga um dos métodos. Você vai usar esse usuário ao configurar sua fonte Snowflake na Braze.

• workload identity federation
• par de chaves

1
2

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

Etapa 2: Criar uma nova fonte no dashboard da Braze

Nesta etapa, você cria sua fonte Snowflake na Braze e valida a conexão.

Etapa 2.1: Adicionar uma fonte Snowflake

1. No dashboard da Braze, acesse Configurações de dados > Ingestão de dados na nuvem > Fontes.
2. Selecione Adicionar fonte de dados.
3. Selecione Snowflake.

Etapa 2.2: Inserir os detalhes da conexão

Escolha um nome para sua fonte e insira suas credenciais e configurações do Snowflake.

Nota

No campo Localizador de conta do Snowflake, insira o identificador da conta do Snowflake, que normalmente segue um formato como xy12345.us-east-1.aws. Ele não é o mesmo que o nome de um banco de dados ou de um warehouse.

Etapa 2.3: Concluir a autenticação

Selecione Workload Identity Federation ou Par de chaves de acordo com o usuário criado na Etapa 1.4.

• workload identity federation
• par de chaves

1

ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';

De volta à Braze, selecione Testar conexão para verificar o acesso à fonte e, depois, crie a fonte.

Etapa 3: Criar uma nova sincronização e escrever sua consulta SQL

1. Acesse Configurações de dados > Ingestão de dados na nuvem > Sincronizações.
2. Selecione Criar sincronização de dados.
3. Escolha qualquer sincronização em Tipo de dados.
4. Faça referência à fonte da Etapa 2.
5. Selecione SQL e escreva uma consulta SQL que retorne dados de usuários do seu warehouse. Sua consulta SQL define os dados que são sincronizados com a Braze. O resultado da consulta se torna o schema da sua sincronização.

Você pode usar o Source Explorer para procurar as tabelas e visualizações disponíveis para sincronização, ou o gerador de SQL com IA para contar com a ajuda do Braze Operator na sua consulta SQL.

Nota

Apenas consultas somente leitura são aceitas, incluindo cláusulas JOIN. Para mais detalhes, consulte Restrições de SQL.

Etapa 4: Fazer a prévia e validar sua consulta

Selecione Prévia e validação para executar sua consulta.

A prévia:

• Mostra os resultados em formato de tabela
• Mostra até 100 linhas
• Mostra até 250 colunas

Para que a validação seja bem-sucedida, sua consulta SQL precisa retornar várias colunas obrigatórias:

As colunas adicionais, além das obrigatórias, são sincronizadas como atributos, propriedades de contexto do Canvas, propriedades de eventos, campos de catálogo e campos de conta, respectivamente. Consulte Comportamento da validação e Solução de problemas para ver dicas úteis sobre erros de prévia e validação e como corrigi-los.

Etapa 5: Revisar o mapeamento de atributos e criar a sincronização

Quando a validação for bem-sucedida, continue para Próximo: Notificações e crie sua sincronização.

Importante

Uma configuração de SQL incorreta pode gerar resultados indesejados, incluindo o consumo excessivo de pontos de dados e riscos operacionais mais amplos. Você é responsável por garantir que a lógica da sua consulta esteja correta e deve revisar com atenção a prévia de todos os resultados antes de ativar uma sincronização.

Restrições de SQL

Usar apenas consultas SELECT

Apenas consultas de leitura são suportadas.

Você pode usar:

• SELECT
• WITH (CTEs)
• JOIN

Você não pode usar:

• INSERT, UPDATE ou DELETE
• CREATE ou DROP
• Múltiplas instruções separadas por ;

Usar uma única instrução

Sua consulta deve ser uma única instrução executável.

Comportamento de validação

O Editor SQL valida sua consulta antes de permitir que você prossiga.

Erros de SQL

Se sua consulta contiver erros de sintaxe:

• A validação falha
• Nenhuma pré-visualização é exibida
• Seu warehouse retorna uma mensagem de erro

Erros de compilação

Se sua consulta referenciar tabelas, colunas ou objetos inválidos ou não autorizados:

• A validação falha
• Nenhuma pré-visualização é exibida
• Seu warehouse retorna uma mensagem de erro

Erros de conexão

Se a Braze não conseguir se conectar ao seu warehouse:

• A validação falha
• Nenhuma pré-visualização é exibida
• Uma mensagem de erro de conexão é exibida

Tempo limite da consulta

Se sua consulta demorar muito para executar:

• A Braze encerra a consulta
• A validação falha
• Um erro de tempo limite é exibido

Erros de schema da tabela

Se sua consulta compilar, a validação ainda pode falhar se:

• Nenhuma coluna de identificador for encontrada
• UPDATED_AT estiver ausente
• Outras colunas obrigatórias estiverem ausentes

Nesse caso, a pré-visualização ainda é exibida para ajudar você a chegar a uma validação bem-sucedida. Consulte a Etapa 4 na seção anterior para detalhes sobre as colunas obrigatórias para cada tipo de dados de sincronização.

Resultados com zero linhas

Se sua consulta retornar zero linhas:

• A validação é aprovada
• Você ainda pode criar a sincronização
• Nenhum usuário é atualizado até que linhas sejam retornadas

Suporte a PAYLOAD (legado)

O Editor SQL é compatível com tabelas legadas de CDI que têm uma coluna PAYLOAD.

Se a sua consulta incluir:

• Um identificador válido
• UPDATED_AT
• Uma coluna PAYLOAD
• Colunas adicionais

Então:

• A Braze sincroniza somente a coluna PAYLOAD
• A Braze ignora as colunas adicionais

Editar uma sincronização de SQL

Ao editar uma sincronização existente:

• Qualquer alteração no SQL exige uma nova validação
• Não é possível salvar alterações inválidas
• Alterações válidas entram em vigor depois que você salva

Se uma execução da sincronização já estiver em andamento, suas alterações entrarão em vigor na próxima execução.

Solução de problemas

Esta seção inclui erros comuns e orientações sobre como solucioná-los.

“Nenhuma prévia disponível”

Quando você vir “No preview available”, um dos seguintes tipos de erro pode ser a causa.

“Coluna de identidade obrigatória”

Verifique se sua consulta inclui um identificador válido, como external_id.

“Coluna UPDATED_AT ausente”

Adicione uma coluna de timestamp para sincronização incremental.

“Adicione mais colunas… Não há atributos/campos de catálogo/campos de conta para sincronizar”

Adicione pelo menos uma coluna além do identificador e de UPDATED_AT.

“Tempo limite de execução da consulta excedido”

Otimize sua consulta ou use um warehouse maior.