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.
O Editor SQL da Ingestão de dados na nuvem permite criar sincronizações escrevendo consultas de SQL diretamente no seu data warehouse. Isso elimina a necessidade de 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
O Editor SQL da Ingestão de dados na nuvem está em beta. Fale com o seu gerente de sucesso do cliente ou gerente de conta para obter acesso.
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.
- Apenas consultas de leitura com uma única instrução são suportadas.
A Braze executa apenas consultas de 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 persistidos.
Criar uma nova sincronização com o 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 CDI, pule para a Etapa 3.
Essas etapas usam uma fonte Snowflake como exemplo. O processo de configuração para outras fontes de data warehouse é semelhante e pode ser encontrado na Etapa 2: Criar uma nova fonte no dashboard da Braze da documentação Configurando integrações de data warehouse.
Etapa 1: Configurar sua role, permissões, warehouse e usuário no Snowflake
Antes de criar sua fonte Snowflake no CDI, verifique se o usuário Snowflake que a Braze utiliza tem acesso aos dados que você deseja consultar e um warehouse para executar consultas.
Etapa 1.1: (Opcional) Criar um banco de dados e schema
Se necessário, crie um banco de dados e schema dedicados para seus dados CDI:
1
2
CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
Etapa 1.2: Configurar role e permissões de banco de dados
Conceda acesso às tabelas que você deseja 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;
Você também pode conceder acesso a múltiplas tabelas ou tabelas futuras, dependendo do seu caso de uso. Por exemplo, para conceder acesso a todas as tabelas futuras em 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 à role 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;
O warehouse deve ter a retomada automática ativada. Se não tiver, 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 Snowflake
Crie um usuário para a Braze e atribua a role:
1
2
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: Criar uma nova fonte no dashboard da Braze
Nesta etapa, crie sua fonte Snowflake na Braze e valide a conexão.
Etapa 2.1: Adicionar uma fonte Snowflake
- No dashboard da Braze, acesse Configurações de dados > Ingestão de dados na nuvem > Fontes.
- Selecione Add data source.
- Selecione Snowflake.
Etapa 2.2: Inserir detalhes da conexão
Escolha um nome para sua fonte e insira suas credenciais e configuração do Snowflake.
Para o campo Snowflake Account Locator, insira o identificador de conta do Snowflake, que normalmente segue um formato como xy12345.us-east-1.aws. Isso não é o mesmo que um nome de banco de dados ou nome de warehouse.
Etapa 2.3: Concluir a configuração da chave RSA
Após inserir suas credenciais e configuração, selecione Save credentials 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 mais informações, consulte Autenticação por par de chaves do Snowflake. Se quiser rotacionar as chaves em algum momento, a Braze pode gerar um novo par de chaves e fornecer a nova chave pública.
1
ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';
De volta à Braze, selecione Test connection para verificar o acesso à fonte e, em seguida, crie a fonte.
Etapa 3: Criar uma nova sincronização e escrever sua consulta SQL
- Acesse Configurações de dados > Ingestão de dados na nuvem > Syncs.
- Selecione Create data sync.
- Escolha qualquer sincronização em Data Type.
- Referencie a fonte da 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 schema da sua sincronização.
Você pode usar o Source Explorer para navegar pelas tabelas e views disponíveis para sincronização, ou o gerador de SQL com IA para obter a ajuda do Braze Operator na sua consulta SQL.
Apenas consultas de leitura são suportadas, incluindo cláusulas JOIN. Para mais detalhes, consulte Restrições de SQL.
Etapa 4: Pré-visualizar e validar sua consulta
Selecione Preview and validate para executar sua consulta.
A pré-visualização:
- Exibe os resultados em formato de tabela
- Mostra até 100 linhas
- Mostra até 250 colunas
Para validar com sucesso, sua consulta SQL deve retornar várias colunas obrigatórias:
| Tipo de dados da sincronização | Colunas obrigatórias |
|---|---|
| Atributos | - Um identificador de usuário, sendo um dos seguintes: 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 dos seguintes: external_id, braze_id, alias_name e alias_label, e-mail ou número de telefone.- UPDATED_AT. |
| Canvas Triggers | - Um identificador de usuário, sendo um dos seguintes: 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 dos seguintes: 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 indisponível, o CDI usa UPDATED_AT como substituto. |
| Eventos de compra | - Um identificador de usuário, sendo um dos seguintes: 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 indisponível, o 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. |
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 de validação e Solução de problemas para dicas úteis sobre erros de pré-visualização 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 Next: Notifications e crie sua sincronização.
Uma configuração SQL incorreta pode levar a resultados indesejados, incluindo o consumo excessivo de data points e riscos operacionais mais amplos. Você é responsável por garantir que a lógica da sua consulta esteja correta e deve pré-visualizar cuidadosamente 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 Editor SQL suporta tabelas CDI legadas onde uma coluna PAYLOAD está presente.
Se 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 SQL
Ao editar uma sincronização existente:
- Qualquer alteração no SQL requer revalidação
- Você não pode salvar alterações inválidas
- Alterações válidas entram em vigor após salvar
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.
Sem pré-visualização disponível
Quando você vê “No preview available”, um dos seguintes tipos de erro pode estar causando isso.
| 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 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 adicional além do identificador e UPDATED_AT.
Tempo limite de execução da consulta excedido
Otimize sua consulta ou use um warehouse maior.