Como exportar dados do Klaviyo para o Databricks

O que você vai aprender

Aprenda a configurar o Databricks como um destino de sincronização de saída, para que a Klaviyo grave continuamente seus dados de perfil, evento e métrica em tabelas Delta no seu próprio workspace do Databricks. Depois de conectar, sua equipe de dados pode combinar os dados da Klaviyo com o restante do seu lakehouse para análise, modelagem e relatórios.

Quer trazer dados para o Klaviyo do Databricks? Consulte Como conectar o Klaviyo e o Databricks.

Antes de começar

Certifique-se de ter o seguinte:

• Um espaço de trabalho da Databricks com o Unity Catalog ativado. Workspaces somente do Hive metastore não são compatíveis. Se você usa o Hive metastore, considere a federação do Hive metastore.
• Um data warehouse SQL compatível com VARIANT colunas e tabelas temporárias com escopo de sessão para que a Klaviyo possa gravar dados. Recomendamos usar data warehouses SQL sem servidor; os data warehouses Classic e Pro podem levar vários minutos para iniciar, o que pode atrasar as sincronizações.
• Permissão para criar esquemas, tabelas e concessões no catálogo que você vai usar (ou ajuda de um administrador do Databricks).
• Permissão para gerenciar integrações no Klaviyo.
• Endereços IP de saída da Klaviyo na lista de permissões, se o seu workspace restringe o tráfego de entrada com listas de acesso por IP:
  • 184.72.183.187/32
  • 52.206.71.52/32
  • 3.227.146.32/32
  • 44.198.39.11/32
  • 35.172.58.121/32
  • 3.228.37.244/32
  • 54.88.219.8/32
  • 3.214.211.176/32

Etapa 1: Crie um esquema para dados da Klaviyo

No Databricks, os schemas ficam dentro de um catálogo. Crie um schema dedicado para armazenar as tabelas nas quais a Klaviyo grava. Os exemplos de SQL ao longo deste artigo usam main como catálogo e KLAVIYO_EXPORT como schema. Se você usar nomes diferentes, substitua-os em todos os exemplos de SQL e insira os mesmos nomes na Klaviyo durante a etapa 5.

USE CATALOG main;  -- or your organization's designated catalog
CREATE SCHEMA IF NOT EXISTS KLAVIYO_EXPORT;

Etapa 2: criar as tabelas de destino

Execute o script a seguir no esquema que você criou na Etapa 1. O Klaviyo grava em 3 tabelas:

• klaviyo_profile: Uma linha por perfil, incluindo campos padrão, localização e propriedades personalizadas.
• klaviyo_event: Uma linha por evento (por exemplo, Pedido feito ou E-mail aberto), vinculada a um perfil e a uma métrica.
• klaviyo_metric: Uma linha por métrica, usada para pesquisar o nome da métrica e a integração de origem de cada evento.

As propriedades do perfil personalizadas e as propriedades de eventos são armazenadas em colunas VARIANT, para que você possa consultar JSON aninhado diretamente sem gerenciar centenas de colunas individuais.

USE SCHEMA main.KLAVIYO_EXPORT;

CREATE TABLE klaviyo_profile (
  id                 STRING NOT NULL,
  external_id        STRING,
  email              STRING,
  phone_number       STRING,
  first_name         STRING,
  last_name          STRING,
  title              STRING,
  organization       STRING,
  properties         VARIANT,
  image              STRING,
  created            TIMESTAMP,
  updated            TIMESTAMP,
  location_address1  STRING,
  location_address2  STRING,
  location_city      STRING,
  location_country   STRING,
  location_latitude  STRING,
  location_longitude STRING,
  location_region    STRING,
  location_zip       STRING,
  PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');

CREATE TABLE klaviyo_event (
  id               STRING NOT NULL,
  metric_id        STRING NOT NULL,
  profile_id       STRING,
  event_properties VARIANT,
  datetime         TIMESTAMP,
  uuid             STRING,
  PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');

CREATE TABLE klaviyo_metric (
  id                   STRING NOT NULL,
  name                 STRING NOT NULL,
  integration_id       STRING,
  integration_name     STRING,
  integration_category STRING,
  created              TIMESTAMP,
  updated              TIMESTAMP,
  PRIMARY KEY (id)
);

Etapa 3: criar um principal de serviço e um token de acesso

A Klaviyo se autentica no Databricks com um token de acesso pessoal (PAT). Recomendamos criar um service principal dedicado, usado apenas para esta integração, em vez da conta de uma pessoa.

1. Crie um principal de serviço (ou um usuário do workspace) para o Klaviyo.
2. Gere um token de acesso pessoal:
   • Principal serviço: Peça para um administrador do workspace criar o token inicial com a CLI do Databricks.
   • Usuário do workspace: Crie um token na IU do Databricks.
3. Armazene o token em um lugar seguro. Você vai colá-lo na Klaviyo na Etapa 5.

Se você já criou uma entidade de serviço para importar do Databricks, pode reutilizá-la. Basta adicionar as permissões de exportação na Etapa 4.

Etapa 4: conceder permissões

Conceda ao principal de serviço do Klaviyo acesso ao catálogo, esquema e warehouse SQL. Substitua klaviyo_service_user pelo ID do aplicativo ou nome de usuário do principal de serviço.

GRANT USE CATALOG ON CATALOG main TO `klaviyo_service_user`;
GRANT USE SCHEMA, SELECT, MODIFY ON SCHEMA main.KLAVIYO_EXPORT TO `klaviyo_service_user`;

Também dê à entidade de serviço a permissão Pode usar no warehouse SQL que você planeja usar. No Databricks, acesse Warehouses SQL, selecione seu warehouse, clique em Permissões e adicione a entidade de serviço.

Verifique sua configuração (opcional)

Usando a mesma identidade e o mesmo token que você vai fornecer à Klaviyo, confirme as tabelas e as permissões:

SHOW TABLES IN main.KLAVIYO_EXPORT;
SHOW GRANTS ON SCHEMA main.KLAVIYO_EXPORT;

Você deve ver todas as 3 tabelas, e o service principal deve estar listado com USE SCHEMA, SELECT e MODIFY.

Etapa 5: conectar o Databricks no Klaviyo

1. Na Klaviyo, vá até Avançado > Gerenciamento de dados > Sincronização.
2. Se você já tiver uma sincronização, clique em Criar sincronização.
3. Selecione Exporte dados para o seu data warehouse.
4. Escolha Databricks e clique em Conectar ao Databricks.
5. Insira os detalhes da conexão:

Clique em Avançar para configurar sua sincronização.

Você também pode encontrar o Databricks no marketplace de apps da Klaviyo acessando Integrações > Explorar apps e pesquisando por Databricks.

Etapa 6: Configure a sincronização de dados

Escolha o que a Klaviyo envia para o Databricks e quando ela sincroniza.

Objetos de dados

Escolha sincronizar perfis, eventos ou ambos. Os dados de métrica são sincronizados junto com os eventos, para que você possa consultar o nome e a origem da métrica de cada evento.

Integrações a serem excluídas

Selecione as integrações cujos eventos você não quer enviar para o Databricks. Isso se aplica apenas aos dados de eventos; não exclui perfis.

Sincronização seletiva

Selecione as métricas cujos eventos você quer sincronizar, como Placed Order. Deixe Sincronização seletiva em branco para sincronizar todos os eventos das integrações que você não excluiu. Esse campo só aparece se você selecionar o objeto de dados Eventos.

Cadência de sincronização

Em A cada, escolha com que frequência sincronizar dados novos e atualizados: a cada 1, 2, 4, 6, 12 ou 24 horas. O padrão é 1 hora. Defina Data de início, Horário de início e Fuso horário para o agendamento.

Dados históricos

Escolha quanto de dados históricos enviar durante a sincronização inicial:

• 30 dias
• 90 dias
• 1 ano
• Todo o período

Etapa 7: Revisar, conectar e monitorar sua sincronização

1. Clique em Próximo para abrir Revisão. Verifique os detalhes da conexão, os dados compartilhados, as integrações excluídas, as métricas selecionadas e o intervalo inicial de sincronização de dados.
2. Clique em Conectar. A Klaviyo testa a conexão e cria a exportação se o teste for bem-sucedido.

Quando a configuração é concluída com sucesso, a Klaviyo exibe uma mensagem de confirmação e leva você de volta para Sincronizando. Sua exportação está ativada, e você pode monitorar o status de sincronização dela lá.

Se o teste de conexão falhar, revise os detalhes do erro. Clique em Editar credenciais para corrigir os detalhes da conexão e, em seguida, clique em Próximo nas configurações de dados para voltar para Revisar e clique em Conectar novamente.

Para monitorar sua sincronização, acesse Avançado > Gerenciamento de dados > Sincronização e clique em Databricks na linha marcada como Exportação. Use estas abas:

• Histórico: O status do preenchimento retroativo inicial.
• Periódico: O status das sincronizações na cadência selecionada, incluindo o frescor dos dados (o quanto suas tabelas do Databricks estão atrasadas em relação à Klaviyo).
• Configurações: veja e edite os detalhes da sua conexão, seleção de dados, cadência de sincronização e intervalo histórico. Clique em Atualizar informações na seção que você alterou para salvar.

Para ver detalhes sobre status de sincronização, pausar e retomar sincronizações e visualizar logs de erro, consulte Entenda a sincronização do data warehouse no Klaviyo.

Consulte seus dados da Klaviyo no Databricks

Veja alguns exemplos para começar.

Contar eventos por nome da métrica nos últimos 7 dias:

SELECT m.name AS metric, COUNT(*) AS events
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE e.datetime >= current_timestamp() - INTERVAL 7 DAYS
GROUP BY m.name
ORDER BY events DESC;

Leia uma propriedade de perfil personalizada na coluna VARIANTE properties:

SELECT id, email, properties:loyalty_tier::STRING AS loyalty_tier
FROM main.KLAVIYO_EXPORT.klaviyo_profile
WHERE properties:loyalty_tier IS NOT NULL;

Obter o valor do pedido a partir de eventos Placed Order:

SELECT e.profile_id, e.datetime, e.event_properties:`$value`::DOUBLE AS order_value
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE m.name = 'Placed Order';

Solução de problemas

Remover uma exportação do Databricks

Remover a exportação interrompe as sincronizações futuras. Os dados já gravados nas suas tabelas do Databricks não são excluídos.

1. Acesse integrações no Klaviyo.
2. Abra o menu ao lado da integração de exportação do Databricks e selecione Remover integração.
3. Clique em Remover integração na caixa de diálogo de confirmação.

Recursos adicionais

• Como conectar a Klaviyo e o Databricks (importação)
• Entenda a sincronização do data warehouse na Klaviyo
• Introdução à Advanced KDP