Conectando o Klaviyo e o Snowflake

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

As palavras-chave "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" e "OPTIONAL" neste documento devem ser interpretadas conforme descrito na RFC 2119.

Configuração do Snowflake Administrador

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

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

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

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

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

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

# Comando do terminal do Mac para gravar a chave no terminal e copiá-la para a área de transferência
cat rsa_key.pub | tee /dev/tty | pbcopy

4. Execute o script a seguir em seu ambiente Snowflake para criar um usuário de serviço a ser usado pelo Klaviyo. Você deve ter privilégios de securityadmin e sysadmin para concluir a configuração abaixo. Para revisar as funções que você tem, execute SHOW GRANTS TO USER <your_username> e verifique se você tem as duas funções listadas. Entre em contato com um administrador do sistema se você precisar ajustar sua função.
   1. Você deve ficar à vontade para atualizar qualquer uma das variáveis definidas no início do script.
   2. Em resumo, você terá:
      1. Escolha um depósito existente ou crie um novo
      2. Escolha um banco de dados existente ou crie um novo para armazenar os novos esquemas
      3. Crie dois novos esquemas: KLAVIYO_TMP e KLAVIYO_IMPORT_FROM_DWH
      4. Crie uma nova política de rede e permita a lista de IPs do Klaviyo
      5. Criar um usuário e uma função para o Klaviyo
   3. Esse script é idempotente (pode ser executado várias vezes com segurança), mas não sobrescreverá objetos existentes com nomes conflitantes. 

BEGIN;

-- criar variáveis para usuário / senha / função / depósito / banco de dados. 
-- Altere-os para o que você preferir.
SET role_name = 'KLAVIYO_DATA_TRANSFER_ROLE'; -- todas as letras devem estar em caixa alta, por exemplo. 'KLAVIYO_DATA_TRANSFER_ROLE'
SET user_name = 'KLAVIYO_DATA_TRANSFER_USER'; -- todas as letras devem estar em caixa alta, por exemplo. 'KLAVIYO_DATA_TRANSFER_USER'
SET warehouse_name = 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'; -- todas as letras devem ser maiúsculas, por exemplo. 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'
SET database_name = 'KLAVIYO_DATABASE'; -- todas as letras devem estar em caixa alta, por exemplo. 'KLAVIYO_DATABASE'. Se esse banco de dados não existir, será criado um novo.
SET network_policy = 'KLAVIYO_DATA_TRANSFER_NETWORK_POLICY'; -- todas as letras devem estar em caixa alta, por exemplo. 'KLAVIYO_NETWORK_POLICY'
SET network_rule = 'KLAVIYO_DATA_TRANSFER_NETWORK_RULE'; -- todas as letras devem ser maiúsculas, por exemplo. 'KLAVIYO_NETWORK_RULE'
/* substitua GENERATE_PUBLIC_KEY abaixo pela chave pública gerada */

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


-- altere a função para sysadmin para as etapas do depósito / banco de dados
USE ROLE sysadmin;

-- crie um depósito para o serviço de transferência de dados
CREATE WAREHOUSE IF NOT EXISTS IDENTIFIER($warehouse_name)
 warehouse_size = xsmall
 warehouse_type = standard
 auto_suspend = 60
 auto_resume = true
 initially_suspended = true;

-- criar banco de dados para o serviço de transferência de dados
CREATE DATABASE IF NOT EXISTS IDENTIFIER($database_name);

-- criar esquemas para o serviço de transferência de dados
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_tmp);
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_import);

-- alterar função para securityadmin para etapas de usuário/função
USE ROLE securityadmin;

-- criar rede  regra e política para banco de dados
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 intervalos de ip, para o esquema KLAVIYO_IMPORT_FROM_DWH 
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);


-- criar função para o serviço de transferência de dados
CREATE ROLE IF NOT EXISTS IDENTIFIER($role_name);
GRANT ROLE IDENTIFIER($role_name) TO ROLE sysadmin;

-- criar um usuário para o serviço de transferência de dados
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;

-- conceder acesso de função de serviço ao depósito
GRANT USAGE
 ON WAREHOUSE IDENTIFIER($warehouse_name)
 TO  ROLE IDENTIFIER($role_name);

-- conceder acesso de serviço ao banco de dados
GRANT monitoramento, USAGE
 ON DATABASE IDENTIFIER($database_name)
 TO ROLE IDENTIFIER($role_name);

-- Conceder privilégios para KLAVIYO_TMP 
GRANT USAGE ON SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name);
GRANT monitoramento, 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);

-- Concede privilégios para 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 Snowflake

Acima, você criou dois novos esquemas. 

• O KLAVIYO_TMP será usado exclusivamente pela Klaviyo. Você NÃO DEVE modificar nenhuma tabela criada nesse esquema. O Klaviyo excluirá essas tabelas quando elas não forem mais necessárias.
• KLAVIYO_IMPORT_FROM_DWH é o local em que você deve loja online suas tabelas finais para importação pelo site Klaviyo. Quando você passar pelo processo de criação da sincronização, todas as tabelas desse esquema serão listadas para você escolher. Portanto, você DEVERIA apenas armazenar on-line as tabelas finais que deseja importar para evitar confusão durante a configuração. 

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

Requisitos de registro de data e hora 

1. As tabelas DEVEM conter um campo de registro de data e hora que indica quando a linha foi criada ou atualizada. Geralmente, isso será inserted_at ou updated_at. Você definirá isso para cada tabela durante o processo de criação da sincronização.
   1. O campo de registro de data e hora DEVE ser monotonicamente crescente (ou seja, deve estar sempre aumentando ou permanecendo o mesmo, nunca diminuindo).
   2. Após a criação da sincronização, você NÃO DEVE definir o valor do carimbo de data/hora de uma linha para um momento no passado, caso contrário o Klaviyo poderá não pegar 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. A Klaviyo RECOMENDA que você defina o campo de registro de data e hora com CURRENT_TIMESTAMP() ou uma função equivalente. 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

... 

2. Seus carimbos de data e hora DEVEM estar em UTC ou incluir informações de fuso horário. Se as informações de fuso horário estiverem ausentes, o Klaviyo assumirá o UTC. Para propriedades personalizadas, esses carimbos de data/hora permanecem no formato de cadeia de caracteres, permitindo que você os interprete no fuso horário de sua preferência.

Estrutura da tabela 

3. As tabelas DEVEM ser tratadas como somente de anexação (também conhecidas como somente de inserção)
   1. Se preferir atualizar as linhas no lugar, você DEVE atualizar o campo timestamp para que o site Klaviyo possa identificar a alteração.
4. As tabelas DEVEM ser ordenadas de acordo com a coluna de registro de data e hora. O Snowflake cuidará do clustering e do particionamento com base na ordem de inserção que você fizer. Isso ajudará a otimizar as consultas de importação do Klaviyo, mantendo baixos os custos de computação no Snowflake

Unicidade e consistência do perfil 

5. Você DEVE garantir que cada Propriedades do perfil seja importada de apenas uma fonte de dados (tabela). O Klaviyo evita que você selecione a mesma propriedade de tabelas diferentes durante a criação da sincronização, simplificando esse requisito.
6. Você DEVERIA usar o(s) mesmo(s) identificador(es) de perfil (e-mail, número de telefone, ID externo etc.) em todas as tabelas de importação para minimizar o risco de criação de perfis duplicados.
   1. Klaviyo criará um novo perfil se o identificador de perfil que você fornecer não corresponder a um perfil existente em Klaviyo.
   2. Exemplo: Tabela1 (Email, fav_color) + Tabela2 (Phone, birthday)
      1. Isso pode criar dois perfis para a mesma pessoa se o perfil não existir no momento. Se houver um perfil, o site Klaviyo tratará internamente da resolução e da atualização do perfil. 
   3. Uma maneira de evitar esse problema é usar apenas uma única tabela de importação para todo o seu perfil. 

Prevenção do loop circular de importação e exportação 

7. Você DEVE gerenciar cuidadosamente os cenários em que os recursos de importação e exportação são usados para evitar loops circulares de importação-exportação. Certifique-se de que seu processo de exportação não alimente os dados de volta em uma tabela que esteja a montante da tabela de importação, pois o Klaviyo não detecta esse cenário no momento.
   1. O Klaviyo ainda não tem lógica para detectar esse cenário.
   2. Isso seria algo parecido com:
      1. Em cada ciclo de sincronização de exportação, o Klaviyo exportará todo o seu perfil
      2. Em seguida, você adiciona todo o perfil exportado à tabela de importação por meio de uma série de transformações.
      3. Em cada ciclo de sincronização de importação, o site Klaviyo lerá todo o perfil em sua tabela de importação, que será eventualmente reexportado
   3. Cenários em que isso provavelmente é seguro 
      1. se você estiver usando apenas a tabela de exportação para restringir as linhas adicionadas à tabela de importação
      2. Se você verificar que a tabela de exportação não adiciona linhas à tabela de importação.
   4. Quais são as consequências de um ciclo circular de importação e exportação?
      1. Isso resultará em custos de computação desnecessários tanto para você quanto para a Klaviyo.