Conectando a Klaviyo com o Snowflake

Para os fins deste artigo, usamos o termo "tabela", mas as visualizações, as visualizações materializadas e as tabelas são todos objetos Snowflake válidos que podem ser importados. Desde que a Klaviyo execute SELECT col1 FROM table_name no objeto, você pode usar o que preferir.

As palavras-chave "DEVE", "NÃO DEVE", "OBRIGATÓRIO", "DEVERÁ", "NÃO DEVERÁ", "DEVERIA", "NÃO DEVERIA", "RECOMENDADO", "PODE" e "OPCIONAL" neste documento devem ser interpretadas conforme descrito na RFC 2119.

Configuração do administrador do floco de neve

Esta seção descreve as etapas que você deve seguir no seu ambiente Snowflake para permitir que a Klaviyo importe seus dados.

1. Gere uma chave privada executando o seguinte comando no seu terminal local:

openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt

1. Gere uma chave pública que faça referência à chave privada executando o seguinte comando no seu terminal:

openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

1. Copie o rsa_key.pub e cole-o no script abaixo para substituir o valor placeholder ‘GENERATE_PUBLIC_KEY’ por user_rsa_public_key. O script abaixo funcionará para usuários de Mac, ou você pode abrir rsa_key.pub em um IDE e copiar o conteúdo completo do arquivo, se preferir.

# Mac terminal command to write the key to your terminal and copy it to the clipboard
cat rsa_key.pub | tee /dev/tty | pbcopy

1. Execute o script a seguir no seu ambiente Snowflake para criar um usuário de serviço para a Klaviyo usar. É preciso ter privilégios de securityadmin e sysadmin para concluir a configuração abaixo. Para revisar quais funções você tem, execute SHOW GRANTS TO USER <your_username> <seu_nome_usuário> e verifique se ambas estão listadas. Entre em contato com um administrador do sistema se precisar ajustar sua função.
   1. Você deve se sentir livre para atualizar qualquer uma das variáveis definidas no início do script.
   2. Em resumo, você:
      1. Escolha um warehouse existente ou crie um novo
      2. Escolha um banco de dados existente ou crie um novo para manter os novos esquemas
      3. Crie dois novos esquemas KLAVIYO_TMP e KLAVIYO_IMPORT_FROM_DWH
      4. Criar uma nova lista de políticas de rede e IPs da Klaviyo
      5. Criar um usuário e uma função para a Klaviyo
   3. Esse script é idempotente (pode ser executado com segurança várias vezes), mas não substituirá objetos existentes por nomes conflitantes.

BEGIN;

-- create variables for user / password / role / warehouse / database. 
-- Change these to whatever you prefer.
SET role_name = 'KLAVIYO_DATA_TRANSFER_ROLE'; -- all letters must be uppercase, ex. 'KLAVIYO_DATA_TRANSFER_ROLE'
SET user_name = 'KLAVIYO_DATA_TRANSFER_USER'; -- all letters must be uppercase, ex. 'KLAVIYO_DATA_TRANSFER_USER'
SET warehouse_name = 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'; -- all letters must be uppercase, ex. 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'
SET database_name = 'KLAVIYO_DATABASE'; -- all letters must be uppercase, ex. 'KLAVIYO_DATABASE'. If this database doesn't exist, a new one will be created.
SET network_policy = 'KLAVIYO_DATA_TRANSFER_NETWORK_POLICY'; -- all letters must be uppercase, ex. 'KLAVIYO_NETWORK_POLICY'
SET network_rule = 'KLAVIYO_DATA_TRANSFER_NETWORK_RULE'; -- all letters must be uppercase, ex. 'KLAVIYO_NETWORK_RULE'
/* replace GENERATE_PUBLIC_KEY below with generated public key */

-- DO NOT CHANGE
SET schema_name_tmp = $database_name || '.KLAVIYO_TMP';  -- DO NOT CHANGE
SET schema_name_import = $database_name || '.KLAVIYO_IMPORT_FROM_DWH';  -- DO NOT CHANGE
SET full_network_rule_tmp = $schema_name_tmp || '.' || $network_rule; -- DO NOT CHANGE
SET full_network_rule_import = $schema_name_import || '.' || $network_rule; -- DO NOT CHANGE


-- change role to sysadmin for warehouse / database steps
USE ROLE sysadmin;

-- create a warehouse for data transfer service
CREATE WAREHOUSE IF NOT EXISTS IDENTIFIER($warehouse_name)
    warehouse_size = xsmall
    warehouse_type = standard
    auto_suspend = 60
    auto_resume = true
    initially_suspended = true;

-- create database for data transfer service
CREATE DATABASE IF NOT EXISTS IDENTIFIER($database_name);

-- create schemas for data transfer service
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_tmp);
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_import);

-- change role to securityadmin for user / role steps
USE ROLE securityadmin;

-- create network rule and policy for database
GRANT USAGE ON DATABASE IDENTIFIER($database_name) TO ROLE securityadmin;
GRANT USAGE, CREATE NETWORK RULE ON SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE securityadmin;
GRANT USAGE, CREATE NETWORK RULE ON SCHEMA IDENTIFIER($schema_name_import) TO ROLE securityadmin;

-- whitelist klaviyo ip ranges, for KLAVIYO_TMP schema 
CREATE NETWORK RULE IF NOT EXISTS IDENTIFIER($full_network_rule_tmp)
    type = IPV4
    value_list = (
        '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'
        )
    comment = 'Klaviyo IP Ranges as of April 2025';
CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy)
    allowed_network_rule_list = ($full_network_rule_tmp);

-- whitelist klaviyo ip ranges, for KLAVIYO_IMPORT_FROM_DWH schema 
CREATE NETWORK RULE IF NOT EXISTS IDENTIFIER($full_network_rule_import)
    type = IPV4
    value_list = (
        '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'
        )
    comment = 'Klaviyo IP Ranges as of April 2025';
CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy)
allowed_network_rule_list = ($full_network_rule_import);


-- create role for data transfer service
CREATE ROLE IF NOT EXISTS IDENTIFIER($role_name);
GRANT ROLE IDENTIFIER($role_name) TO ROLE sysadmin;

-- create a user for data transfer service
CREATE USER IF NOT EXISTS IDENTIFIER($user_name)
    type = SERVICE
    network_policy = $network_policy
    default_role = $role_name
    default_warehouse = $warehouse_name
    rsa_public_key = 'GENERATE_PUBLIC_KEY';
GRANT ROLE IDENTIFIER($role_name) TO USER IDENTIFIER($user_name);
ALTER USER IDENTIFIER($user_name) SET NETWORK_POLICY = $network_policy;

-- grant service role access to warehouse
GRANT USAGE
    ON WAREHOUSE IDENTIFIER($warehouse_name)
    TO ROLE IDENTIFIER($role_name);

-- grant service access to database
GRANT MONITOR, USAGE
    ON DATABASE IDENTIFIER($database_name)
    TO ROLE IDENTIFIER($role_name);

-- Grant privileges for KLAVIYO_TMP 
GRANT USAGE ON SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name);
GRANT MONITOR, USAGE, CREATE TABLE, CREATE VIEW, CREATE SEQUENCE, CREATE FUNCTION, CREATE PROCEDURE
    ON SCHEMA IDENTIFIER($schema_name_tmp)
    TO ROLE IDENTIFIER($role_name);
GRANT ALL ON FUTURE TABLES IN SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name);

-- Grant privileges for KLAVIYO_IMPORT_FROM_DWH
GRANT USAGE ON SCHEMA IDENTIFIER($schema_name_import) TO ROLE IDENTIFIER($role_name);
GRANT SELECT
    ON FUTURE TABLES
    IN SCHEMA IDENTIFIER($schema_name_import)
    TO ROLE IDENTIFIER($role_name);

COMMIT;

Configuração de dados do floco de neve

Acima, você criou dois novos esquemas.

• O KLAVIYO_TMP será usado exclusivamente pela Klaviyo. Você NÃO DEVE modificar nenhuma tabela criada nesse esquema. A Klaviyo excluirá essas tabelas quando elas não forem mais necessárias.
• KLAVIYO_IMPORT_FROM_DWH é onde você deve armazenar suas tabelas finais para a Klaviyo importar. Quando você concluir o processo de criação da sincronização, todas as tabelas nesse esquema serão listadas para você escolher. Portanto, você DEVE armazenar apenas as tabelas finais que deseja importar para evitar confusão durante a configuração.

Todas as tabelas que você planeja importar para a Klaviyo devem atender aos seguintes critérios.

Requisitos de carimbo de data/hora

1. As tabelas DEVEM conter um campo de carimbo de data/hora que indique quando a linha foi criada ou atualizada. Muitas vezes, isso será inserted_at ou updated_at. Isso será definido para cada tabela durante o processo de criação da sincronização.
   1. O campo de carimbo de data/hora DEVE estar aumentando monotonicamente (ou seja, deve estar sempre ficando maior ou permanecendo o mesmo, nunca ficando menor).
   2. Após a criação da sincronização, você NÃO DEVE definir o valor do carimbo de data/hora de uma linha como uma hora no passado ou a Klaviyo pode não escolher essa linha.
   3. O fuso horário desse campo específico não é importante para a Klaviyo, desde que você siga os requisitos acima
   4. Seus carimbos de data/hora DEVEM estar em UTC ou incluir informações de fuso horário. Se as informações de fuso horário estiverem ausentes, a Klaviyo assumirá UTC. Para propriedades personalizadas, esses carimbos de data/hora permanecem no formato de string, permitindo que você os interprete no seu fuso horário preferido.
2. O campo de carimbo de data/hora DEVE refletir quando a linha foi inserida e deve ser agrupada perto da data atual. A Klaviyo sincroniza os dados digitalizando janelas de 1 hora a partir do valor de carimbo de data/hora mais antigo da tabela. Uma única linha com um registro de data e hora no passado (por exemplo, um registro de 2023 quando todos os outros são recentes) faz com que a Klaviyo itere a cada janela de 1 hora a partir dessa data em cada ciclo de sincronização. Essa é uma limitação atual que deve ser resolvida em uma versão futura.
3. Considere a densidade da linha por janela de carimbo de data/hora de 1 hora. Como os dados são carregados em lotes de janelas de carimbo de data/hora de 1 hora, milhões de registros na mesma janela de 1 hora podem resultar em sincronizações lentas ou paralisadas. Embora o limite superior de densidade de linhas dependa da quantidade de dados em cada linha, uma boa regra prática a ser levada em consideração é a janela de carimbo de data/hora de 100.000 linhas por 1 hora.
4. A Klaviyo recomenda que você defina o campo timestamp com CURRENT_TIMESTAMP() ou uma função equivalente sempre que adicionar linhas à tabela da qual sincronizaremos. Várias linhas podem ter o mesmo registro de data e hora. Veja o exemplo abaixo.

INSERT INTO table_name AS 

SELECT ... 

    , CURRENT_TIMESTAMP() AS inserted_at

... 

Estrutura da tabela

1. As tabelas DEVEM ser tratadas como somente anexo (também conhecido como somente inserção)
   1. Se preferir atualizar as linhas em vigor, é PRECISO atualizar o campo de carimbo de data/hora para que a Klaviyo possa identificar a alteração.
2. As tabelas DEVEM ser ordenadas na sua coluna de carimbo de data/hora. O Snowflake lidará com o agrupamento e o particionamento com base no seu pedido de inserção. Isso ajudará a otimizar as consultas de importação da Klaviyo, reduzindo os custos de computação no Snowflake

Unicidade e consistência do perfil

1. É PRECISO garantir que cada propriedade de perfil seja importada de apenas uma fonte de dados (tabela). A Klaviyo impede que a mesma propriedade seja selecionada em tabelas diferentes durante a criação da sincronização, simplificando esse requisito.
2. Você DEVE usar os mesmos identificadores de perfil (e-mail, número de telefone, ID externa etc.) em todas as suas tabelas de importação para minimizar o risco de criação de perfis duplicados.
   1. A Klaviyo criará novos perfis se o identificador de perfil fornecido não corresponder a um perfil existente na Klaviyo.
   2. Exemplo: Tabela1 (E-mail, fav_color) + Tabela2 (Telefone, aniversário)
      1. Isso pode criar 2 perfis para a mesma pessoa se o perfil não existir no momento. Se um perfil existir, a Klaviyo tratará da resolução e das atualizações do perfil internamente. 
   3. Uma maneira de evitar esse problema é usar apenas uma única tabela de importação para todos os seus perfis.

Prevenção de Loop de Importação-Exportação Circular

1. É PRECISO gerenciar cuidadosamente cenários em que os recursos de importação e exportação sejam usados para evitar loops circulares de importação e exportação. Certifique-se de que seu processo de exportação não alimente dados em uma tabela que esteja a montante de sua tabela de importação, pois a Klaviyo não detecta esse cenário no momento.
   1. A Klaviyo ainda não tem lógica para detectar esse cenário.
   2. Isso seria algo como:
      1. Em cada ciclo de sincronização de exportação, a Klaviyo exportará todos os seus perfis
      2. Em seguida, você adiciona todos os seus perfis exportados à sua tabela de importação por meio de algumas séries de transformações.
      3. Em cada ciclo de sincronização de importação, a Klaviyo lerá todos os perfis em sua tabela de importação, que serão reexportados
   3. Cenários em que isso é provavelmente seguro
      1. Se você estiver usando apenas a tabela Exportar para restringir as linhas adicionadas à sua tabela Importar
      2. Se você verificar que a tabela de exportação não adiciona linhas à sua tabela de importação.
   4. Quais são as consequências de um ciclo circular importação-exportação?
      1. Isso resultará em custos de computação desnecessários para você e para a Klaviyo.

Solução de problemas

A sincronização parece bloqueada

Se a sincronização estiver em execução, mas os dados não aparecerem na Klaviyo após várias horas, ou se a sincronização levar um tempo excepcionalmente longo para ser concluída, um valor de registro de data e hora distante no passado é a causa mais provável:

• Verifique sua tabela para todas as linhas com um carimbo de data/hora significativamente mais antigo do que o restante de seus dados (por exemplo, uma linha de 2023 quando todas as outras são da semana passada). Até mesmo uma única linha de outliers força a Klaviyo a iterar por milhares de janelas vazias de 1 hora antes de atingir dados recentes.
• Correção: Atualize ou remova qualquer linha com carimbos de data/hora antigos ou defina-a como um valor recente antes de ativar ou reativar a sincronização. Para backfills, defina todas as linhas históricas com o mesmo carimbo de data/hora recente (por exemplo, o tempo de execução da tarefa atual) para minimizar o número de janelas de 1 hora que a Klaviyo deve verificar. Se tiver mais de ~100.000 linhas, defina seus carimbos de data/hora em lotes de ~100.000 a cada (pelo menos) 61 minutos de intervalo.

Configuração recomendada da chave de agrupamento do Snowflake

Ao agrupar sua tabela Snowflake na coluna de data/hora, as consultas de importação da Klaviyo ignoram micropartições desnecessárias, reduzindo o tempo de sincronização e os custos de computação do Snowflake:

ALTER TABLE your_database.KLAVIYO_IMPORT_FROM_DWH.your_table CLUSTER BY (your_timestamp_column);