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 ao configurar uma tabela de origem.
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 Editor SQL 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 suportadas.
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 Editor SQL
Siga estas etapas para criar primeiro uma fonte e, depois, uma sincronização com o Editor SQL. Se você já configurou uma fonte para a CDI, pode pular para a etapa 3.
Estas etapas usam uma fonte Snowflake como exemplo. O processo de configuração de outras fontes de data warehouse é parecido e está disponível na página de cada fonte em Fontes de ingestão de dados na nuvem.
Etapa 1: Configure a função, as permissões, o warehouse e o usuário do Snowflake
Antes de criar sua fonte Snowflake na CDI, confira se o usuário do Snowflake que a Braze usa tem acesso aos dados que você quer consultar e a um warehouse para executar consultas.
Etapa 1.1: (Opcional) Crie um banco de dados e um esquema
Se necessário, crie um banco de dados e um esquema dedicados para seus dados da CDI:
CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
Etapa 1.2: Configure a função e as permissões do banco de dados
Conceda acesso às tabelas que você quer sincronizar:
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;
Você também pode conceder acesso a várias tabelas ou a tabelas futuras, dependendo do seu caso de uso. Por exemplo, para conceder acesso a todas as tabelas futuras de um esquema:
GRANT SELECT ON FUTURE TABLES IN SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
Etapa 1.3: Configure o warehouse e conceda acesso à função da Braze
Crie um warehouse para a Braze executar consultas:
CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;
O warehouse precisa estar com a opção de retomada automática 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: Crie um usuário do Snowflake
Crie um usuário para a Braze e atribua a função:
CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;
Você usará esse usuário ao configurar sua fonte Snowflake na Braze.
Etapa 2: Crie uma nova fonte no dashboard da Braze
Nesta etapa, você cria sua fonte Snowflake na Braze e valida a conexão.
Etapa 2.1: Adicione uma fonte Snowflake
- No dashboard da Braze, acesse Configurações de dados > Ingestão de dados na nuvem > Fontes.
- Selecione Adicionar fonte de dados.
- Selecione Snowflake.
Etapa 2.2: Insira os detalhes da conexão
Escolha um nome para sua fonte e insira suas credenciais e configurações do Snowflake.
No campo Snowflake Account Locator, 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: Conclua a configuração da chave RSA
Depois de inserir suas credenciais e configurações, selecione Salvar credenciais e gere uma chave RSA. Em seguida, volte ao Snowflake para concluir a configuração. Adicione a chave pública exibida no dashboard ao usuário que você criou para a Braze se conectar ao Snowflake.
Para saber mais, consulte Autenticação por par de chaves do Snowflake. Se quiser fazer a rotação das chaves a qualquer momento, a Braze pode gerar um novo par de chaves e fornecer a nova chave pública.
ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';
De volta à Braze, selecione Testar conexão para verificar o acesso à fonte e, em seguida, crie a fonte.
Etapa 3: Crie uma nova sincronização e escreva sua consulta SQL
- Acesse Configurações de dados > Ingestão de dados na nuvem > Sincronizações.
- Selecione Criar sincronização de dados.
- Escolha qualquer sincronização em Tipo de dados.
- Indique a fonte criada na etapa 2.
- Selecione SQL e escreva uma consulta SQL que retorne dados de usuários do seu warehouse. Sua consulta SQL define os dados que serão sincronizados com a Braze. O resultado da consulta se torna o esquema da sua sincronização.
Você pode usar o Source Explorer para navegar pelas tabelas e visualizações disponíveis para sincronização ou usar o gerador de SQL com IA para contar com a ajuda do Braze Operator na sua consulta SQL.
Somente consultas de leitura são compatíveis, incluindo cláusulas JOIN. Para saber mais, consulte Restrições de SQL.
Etapa 4: Faça a prévia e valide sua consulta
Selecione Prévia e validação para executar sua consulta.
A prévia:
- Exibe os resultados em formato de tabela
- Mostra até 100 linhas
- Mostra até 250 colunas
Para ser validada, sua consulta SQL precisa retornar várias colunas obrigatórias:
| Tipo de dados da sincronização | Colunas obrigatórias |
|---|---|
| Atributos | - Um identificador de usuário, sendo um destes: external_id, braze_id, alias_name e alias_label, e-mail ou número de telefone.- UPDATED_AT.- Pelo menos uma coluna adicional (atributo) para sincronizar. |
| Excluir usuários | - Um identificador de usuário, sendo um destes: external_id, braze_id, alias_name e alias_label, e-mail ou número de telefone.- UPDATED_AT. |
| Gatilhos do Canvas | - Um identificador de usuário, sendo um destes: external_id, braze_id, alias_name e alias_label, e-mail ou número de telefone.- UPDATED_AT. |
| Eventos personalizados | - Um identificador de usuário, sendo um destes: external_id, braze_id, alias_name e alias_label, e-mail ou número de telefone.- UPDATED_AT.- NAME para representar o nome do evento.- TIME para representar o horário do evento. Se não estiver disponível, a CDI usa UPDATED_AT como substituto. |
| Eventos de compra | - Um identificador de usuário, sendo um destes: external_id, braze_id, alias_name e alias_label, e-mail ou número de telefone.- UPDATED_AT.- PRODUCT_ID.- CURRENCY.- PRICE.- TIME para representar o horário do evento de compra. Se não estiver disponível, a CDI usa UPDATED_AT como substituto. |
| Catálogo | - ID para representar o identificador do item do catálogo.- UPDATED_AT.- Pelo menos uma coluna adicional (campo do catálogo) para sincronizar. |
| Contas | - ID para representar o identificador da conta.- NAME para representar o nome da conta.- UPDATED_AT.- Pelo menos uma coluna adicional (campo da conta) para sincronizar. |
As colunas adicionais, além das obrigatórias, são sincronizadas como atributos, propriedades de contexto do Canvas, propriedades de evento, 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: Revise o mapeamento de atributos e crie a sincronização
Quando a validação for concluída com sucesso, continue para Próximo: Notificações e crie sua sincronização.
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 cuidado 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:
SELECTWITH(CTEs)JOIN
Você não pode usar:
INSERT,UPDATEouDELETECREATEouDROP- 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_ATestiver 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 SQL Editor oferece suporte a tabelas legadas de CDI que tenham uma coluna PAYLOAD.
Se a sua consulta incluir:
- Um identificador válido
UPDATED_AT- Uma coluna
PAYLOAD - Colunas adicionais
Então:
- A Braze sincroniza apenas 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 de 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.
| Tipo de erro | Etapas para resolver |
|---|---|
| “No preview available” | Leia o banner de erro para obter dicas. |
| “Unable to connect to the source” | Verifique o nome de usuário configurado, o localizador de conta e a configuração de autenticação por par de chaves RSA. Verifique se o warehouse está em execução. Confirme o acesso à rede. |
| “SQL syntax error” | Verifique a sintaxe do seu SQL. |
| “Object does not exist or not authorized” | Verifique se a role tem acesso SELECT à tabela.Confirme as permissões de banco de dados e schema. Verifique se há erros de digitação no nome da tabela. |
“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.