Migrar sua tabela de exportação de perfil do Snowflake para uma tabela híbrida

O que você vai aprender

Saiba como converter a tabela KLAVIYO_PROFILE, na qual a exportação do data warehouse da Klaviyo grava no Snowflake, de uma tabela padrão para uma tabela híbrida do Snowflake, com os comandos exatos para executar em cada etapa.

A sincronização de exportação da Klaviyo grava em KLAVIYO_PROFILE com um MERGE (upsert) a cada execução periódica. Tabelas híbridas são um tipo de tabela do Snowflake criado para leituras e gravações pontuais com baixa latência, baseadas em índice; por isso, a conversão reduz o tempo e o custo dessas operações de MERGE — isso vale independentemente de como você lê a tabela depois, então vale a pena fazer mesmo que você só execute varreduras analíticas grandes e agregações mais adiante. Se você também usa a KLAVIYO_PROFILE para atender a consultas individuais de perfis em um aplicativo, uma API ou uma UI, uma tabela híbrida também retorna essas consultas mais rapidamente.

Antes de começar

Faça as quatro verificações abaixo antes de mudar qualquer coisa.

1. Confirme se sua conta oferece suporte a tabelas híbridas

Substitua KLAVIYO_DATABASE e KLAVIYO_DATA_TRANSFER_WAREHOUSE pelos nomes que você definiu no script de configuração do Snowflake. O script cria a tabela de perfis a partir de uma variável $profile_table, então substitua pelo valor que você atribuiu a ela sempre que este artigo se referir a KLAVIYO_PROFILE.

USE ROLE SYSADMIN;
USE WAREHOUSE KLAVIYO_DATA_TRANSFER_WAREHOUSE;
USE DATABASE KLAVIYO_DATABASE;
USE SCHEMA PUBLIC;

CREATE OR REPLACE HYBRID TABLE HYBRID_SMOKE_TEST (ID VARCHAR(32) PRIMARY KEY);
DROP TABLE HYBRID_SMOKE_TEST;

Se alguma das instruções falhar, as tabelas híbridas não estão ativadas para sua conta ou região e você deve parar aqui.

2. Dimensione sua tabela de perfis

SELECT
    ROW_COUNT,
    BYTES / POWER(1024, 3) AS SIZE_GB
FROM KLAVIYO_DATABASE.INFORMATION_SCHEMA.TABLES
WHERE TABLE_SCHEMA = 'PUBLIC'
  AND TABLE_NAME = 'KLAVIYO_PROFILE';

As tabelas híbridas usam o armazenamento primário baseado em linhas, portanto, em geral, os mesmos dados ocupam mais espaço do que em uma tabela padrão em colunas. Considere o valor SIZE_GB como um mínimo, não como uma estimativa, e deixe uma margem abaixo da cota de 2 TB por banco de dados.

3. Verifique se há IDs duplicados ou nulos

O script de configuração do Klaviyo já declara a chave primária (ID) na tabela padrão, mas o Snowflake não aplica chaves primárias em tabelas padrão. Já as tabelas híbridas aplicam essas chaves, então IDs duplicados ou nulos que eram tolerados antes agora vão bloquear o carregamento. As duas consultas devem retornar 0.

SELECT COUNT(*) AS DUPLICATE_IDS
FROM (
    SELECT ID
    FROM KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE
    GROUP BY ID
    HAVING COUNT(*) > 1
);

SELECT COUNT(*) AS NULL_IDS
FROM KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE
WHERE ID IS NULL;

Se qualquer um deles retornar um valor diferente de zero, resolva o problema de qualidade de dados na tabela padrão antes de continuar. Caso contrário, o carregamento da etapa 2 falhará.

4. Verifique as dependências downstream

As tabelas híbridas não oferecem suporte a chaves de clustering, compartilhamento de dados, tabelas dinâmicas, Fail-safe, visualizações materializadas, Query Acceleration Service, replicação, Search Optimization Service, Snowpipe, Snowpipe Streaming, streams ou UNDROP. O Time Travel é compatível, com limitações.

SELECT
    REFERENCING_DATABASE,
    REFERENCING_SCHEMA,
    REFERENCING_OBJECT_NAME,
    REFERENCING_OBJECT_DOMAIN
FROM SNOWFLAKE.ACCOUNT_USAGE.OBJECT_DEPENDENCIES
WHERE REFERENCED_OBJECT_NAME = 'KLAVIYO_PROFILE';

Se algo que depende de um recurso não compatível estiver mais adiante no processo, recrie-o antes de migrar.

Etapa 1: pause a sincronização de exportação

No Klaviyo, navegue até Advanced Klaviyo Data Platform > Data management > Syncing, clique no seu destino do Snowflake, abra a guia Periodic e selecione Pausar.

Aguarde até que qualquer sincronização em andamento mostre o status Concluído ou Pausado antes de continuar. Migrar enquanto uma sincronização está gravando na tabela pode fazer com que linhas sejam perdidas.

Etapa 2: crie a tabela híbrida e carregue-a

CREATE HYBRID TABLE ... AS SELECT exige que você declare explicitamente todo o esquema de colunas; ele não pode ser inferido a partir do SELECT. Use os mesmos nomes de colunas e tipos de dados da tabela existente para que a sincronização do Klaviyo continue gravando nela sem alterações.

USE ROLE SYSADMIN;
USE WAREHOUSE KLAVIYO_DATA_TRANSFER_WAREHOUSE;
USE DATABASE KLAVIYO_DATABASE;
USE SCHEMA PUBLIC;

CREATE OR REPLACE HYBRID TABLE KLAVIYO_PROFILE_HYBRID (
    ID VARCHAR(32) NOT NULL,
    EXTERNAL_ID VARCHAR(255),
    EMAIL VARCHAR(255),
    PHONE_NUMBER VARCHAR(255),
    FIRST_NAME VARCHAR(255),
    LAST_NAME VARCHAR(255),
    TITLE VARCHAR(255),
    ORGANIZATION VARCHAR(255),
    PROPERTIES OBJECT,
    IMAGE VARCHAR(255),
    CREATED TIMESTAMP_NTZ(9),
    UPDATED TIMESTAMP_NTZ(9),
    LOCATION_ADDRESS1 VARCHAR(255),
    LOCATION_ADDRESS2 VARCHAR(255),
    LOCATION_CITY VARCHAR(255),
    LOCATION_COUNTRY VARCHAR(255),
    LOCATION_LATITUDE VARCHAR(255),
    LOCATION_LONGITUDE VARCHAR(255),
    LOCATION_REGION VARCHAR(255),
    LOCATION_ZIP VARCHAR(255),
    PRIMARY KEY (ID)
)
AS
SELECT
    ID,
    EXTERNAL_ID,
    EMAIL,
    PHONE_NUMBER,
    FIRST_NAME,
    LAST_NAME,
    TITLE,
    ORGANIZATION,
    PROPERTIES,
    IMAGE,
    CREATED,
    UPDATED,
    LOCATION_ADDRESS1,
    LOCATION_ADDRESS2,
    LOCATION_CITY,
    LOCATION_COUNTRY,
    LOCATION_LATITUDE,
    LOCATION_LONGITUDE,
    LOCATION_REGION,
    LOCATION_ZIP
FROM KLAVIYO_PROFILE;

Carregar uma tabela muito grande em lotes

Se um único CTAS for grande demais para ser executado com tranquilidade, crie a tabela híbrida vazia e carregue-a em intervalos de datas. INSERT INTO ... SELECT também usa o caminho otimizado de carregamento em massa.

CREATE OR REPLACE HYBRID TABLE KLAVIYO_PROFILE_HYBRID (
    ID VARCHAR(32) NOT NULL,
    EXTERNAL_ID VARCHAR(255),
    EMAIL VARCHAR(255),
    PHONE_NUMBER VARCHAR(255),
    FIRST_NAME VARCHAR(255),
    LAST_NAME VARCHAR(255),
    TITLE VARCHAR(255),
    ORGANIZATION VARCHAR(255),
    PROPERTIES OBJECT,
    IMAGE VARCHAR(255),
    CREATED TIMESTAMP_NTZ(9),
    UPDATED TIMESTAMP_NTZ(9),
    LOCATION_ADDRESS1 VARCHAR(255),
    LOCATION_ADDRESS2 VARCHAR(255),
    LOCATION_CITY VARCHAR(255),
    LOCATION_COUNTRY VARCHAR(255),
    LOCATION_LATITUDE VARCHAR(255),
    LOCATION_LONGITUDE VARCHAR(255),
    LOCATION_REGION VARCHAR(255),
    LOCATION_ZIP VARCHAR(255),
    PRIMARY KEY (ID)
);

INSERT INTO KLAVIYO_PROFILE_HYBRID
SELECT * FROM KLAVIYO_PROFILE
WHERE UPDATED < '2024-01-01';

INSERT INTO KLAVIYO_PROFILE_HYBRID
SELECT * FROM KLAVIYO_PROFILE
WHERE UPDATED >= '2024-01-01' AND UPDATED < '2025-01-01';

INSERT INTO KLAVIYO_PROFILE_HYBRID
SELECT * FROM KLAVIYO_PROFILE
WHERE UPDATED >= '2025-01-01' OR UPDATED IS NULL;

Ajuste os limites para se adequar aos seus dados e certifique-se de que os intervalos não se sobreponham nem deixem lacunas.

Etapa 3: Adicionar índices secundários

A chave primária no ID é indexada automaticamente. Adicione índices secundários apenas para as colunas nas quais você realmente filtra, porque cada índice consome armazenamento e adiciona custo a cada gravação. Se você busca perfis por EMAIL ou EXTERNAL_ID, indexe essas colunas; se você também filtra ou ordena por recência (por exemplo, ao buscar perfis atualizados desde um determinado horário), indexe UPDATED também.

CREATE INDEX IDX_KLAVIYO_PROFILE_EMAIL
    ON KLAVIYO_PROFILE_HYBRID (EMAIL);

CREATE INDEX IDX_KLAVIYO_PROFILE_EXTERNAL_ID
    ON KLAVIYO_PROFILE_HYBRID (EXTERNAL_ID);

CREATE INDEX IDX_KLAVIYO_PROFILE_UPDATED
    ON KLAVIYO_PROFILE_HYBRID (UPDATED);

Para ver os índices na tabela:

SHOW INDEXES IN TABLE KLAVIYO_PROFILE_HYBRID;

Etapa 4: validar a cópia

A contagem de linhas deve ser a mesma, e a consulta de diferença deve retornar 0.

SELECT
    (SELECT COUNT(*) FROM KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE) AS STANDARD_ROWS,
    (SELECT COUNT(*) FROM KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE_HYBRID) AS HYBRID_ROWS;

SELECT COUNT(*) AS MISSING_IDS
FROM (
    SELECT ID FROM KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE
    MINUS
    SELECT ID FROM KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE_HYBRID
);

Confirme se a nova tabela é realmente híbrida e, em seguida, faça uma verificação pontual de uma leitura de ponto com a mesma consulta na tabela padrão:

SHOW HYBRID TABLES LIKE 'KLAVIYO_PROFILE_HYBRID';

SELECT * FROM KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE_HYBRID
WHERE EMAIL = 'someone@example.com';

Etapa 5: substitua a tabela híbrida no lugar

Renomeie a tabela padrão e tire-a do caminho, em vez de excluí-la, para que você tenha um caminho de reversão.

USE ROLE SYSADMIN;
USE DATABASE KLAVIYO_DATABASE;
USE SCHEMA PUBLIC;

ALTER TABLE KLAVIYO_PROFILE RENAME TO KLAVIYO_PROFILE_STANDARD_BACKUP;
ALTER TABLE KLAVIYO_PROFILE_HYBRID RENAME TO KLAVIYO_PROFILE;

Etapa 6: conceda novamente privilégios para a função da Klaviyo

Substitua o nome da função que você definiu como role_name no seu script de configuração do Snowflake.

USE ROLE SECURITYADMIN;

GRANT SELECT, INSERT, UPDATE, DELETE
    ON TABLE KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE
    TO ROLE KLAVIYO_DATA_TRANSFER_ROLE;

SHOW GRANTS ON TABLE KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE;

Etapa 7: retome a sincronização e confirme

Na Klaviyo, volte para Advanced Klaviyo Data Platform > Gerenciamento de dados > Sincronização, clique no seu destino do Snowflake, abra a guia Periódico e selecione Retomar.

As sincronizações periódicas são executadas a cada hora. Após a conclusão do próximo ciclo, confirme se o status é Concluído e verifique se os dados estão chegando:

SELECT
    COUNT(*) AS ROW_COUNT,
    MAX(UPDATED) AS LAST_UPDATED
FROM KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE;

Se a sincronização apresentar erro, abra a exportação com falha na guia Periódico para ler o resumo do erro, o código e a mensagem retornada pelo Snowflake. Consulte a seção Ver logs de erro de Entenda a sincronização do data warehouse na Klaviyo.

Reverter

Se a sincronização falhar em relação à tabela híbrida e você precisar reverter, pause a sincronização e troque as tabelas de volta.

USE ROLE SYSADMIN;
USE DATABASE KLAVIYO_DATABASE;
USE SCHEMA PUBLIC;

ALTER TABLE KLAVIYO_PROFILE RENAME TO KLAVIYO_PROFILE_HYBRID;
ALTER TABLE KLAVIYO_PROFILE_STANDARD_BACKUP RENAME TO KLAVIYO_PROFILE;

USE ROLE SECURITYADMIN;
GRANT SELECT, INSERT, UPDATE, DELETE
    ON TABLE KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE
    TO ROLE KLAVIYO_DATA_TRANSFER_ROLE;

Em seguida, retome a sincronização. A próxima sincronização periódica do Klaviyo preenche retroativamente tudo o que foi criado ou atualizado enquanto a tabela foi substituída.

Após a migração

Quando você tiver confiança na nova tabela, exclua o backup para que ele pare de acumular custos de armazenamento.

USE ROLE SYSADMIN;
DROP TABLE KLAVIYO_DATABASE.PUBLIC.KLAVIYO_PROFILE_STANDARD_BACKUP;

Tenha o seguinte em mente de forma contínua:

• Cota de armazenamento: você está limitado a 2 TB de dados de tabela híbrida por banco de dados do Snowflake. Se você exceder esse limite, as gravações em todas as tabelas híbridas desse banco de dados serão bloqueadas até você reduzir o uso para ficar abaixo da cota, o que fará com que a sincronização do Klaviyo falhe.
• Cota de solicitações: aproximadamente 16.000 operações por segundo por banco de dados para uma carga de trabalho equilibrada de 80% de leitura/20% de gravação.
• Sem fail-safe, Time Travel limitado: o UNDROP não é compatível com tabelas híbridas. Mantenha seu próprio processo de backup, se precisar de um.
• Sem cache de resultados: consultas em tabelas híbridas não usam o cache persistente de resultados de consulta do Snowflake.
• Custo: O armazenamento e as solicitações da tabela híbrida são medidos separadamente do armazenamento padrão de tabela e da computação. Revise a documentação de custos da Snowflake antes de migrar uma tabela grande.

Recursos adicionais

• Entenda a sincronização do data warehouse na Klaviyo
• Conectar a Klaviyo e o Snowflake
• Snowflake: Tabelas híbridas
• Snowflake: Criar tabelas híbridas
• Snowflake: Limitações e recursos não compatíveis para tabelas híbridas
• Snowflake: Avaliar custo para tabelas híbridas
• Snowflake: Como converter tabelas padrão do Snowflake em tabelas híbridas