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
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 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 persistidos.
Criar uma nova sincronização com o 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 CDI, pode pular 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 em Etapa 2: Criar uma nova fonte no dashboard da Braze na documentação Configurando integrações de data warehouse.
Etapa 1: Configurar sua role, permissões, warehouse e usuário do Snowflake
Antes de criar sua fonte Snowflake no CDI, verifique se o usuário do Snowflake que a Braze utiliza tem acesso aos dados que você deseja consultar e a um warehouse para executar consultas.
Etapa 1.1: (Opcional) Criar um banco de dados e um esquema
Se necessário, crie um banco de dados e um esquema dedicados para seus dados de 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 várias tabelas ou tabelas futuras, dependendo do seu caso de uso. Por exemplo, para conceder acesso a todas as tabelas futuras em um esquema:
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 precisa ter a flag 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: Criar um usuário do 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 Data Settings > Cloud Data Ingestion > Sources.
- Selecione Add data source.
- Selecione Snowflake.
Etapa 2.2: Inserir detalhes de conexão
Escolha um nome para sua fonte e insira suas credenciais e configurações do Snowflake.
Para o campo Snowflake Account Locator, insira seu 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ções, 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 informações adicionais, consulte Autenticação por par de chaves do Snowflake. Se você quiser fazer a rotação de 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 Data Settings > Cloud Data Ingestion > 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 esquema 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 somente leitura são suportadas, incluindo cláusulas JOIN. Para mais detalhes, consulte Restrições de SQL.
Etapa 4: Visualizar e validar sua consulta
Selecione Preview and validate para executar sua consulta.
A prévia:
- 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 entre 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 entre 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 entre 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 entre 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 entre 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é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 Next: Notifications e crie sua sincronização.
Uma configuração SQL imprecisa pode levar a 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 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 SQL Editor oferece suporte a tabelas CDI legadas em que uma coluna PAYLOAD está presente.
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 SQL
Ao editar uma sincronização existente:
- Qualquer alteração no SQL requer revalidação
- Não é possível 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.