Migration de votre table d’exportation de profils Snowflake vers une table hybride

Objectif de cet article

Découvrez comment convertir la table KLAVIYO_PROFILE vers laquelle l’exportation de l’entrepôt de données de Klaviyo écrit dans Snowflake, d’une table standard en une table hybride Snowflake, avec les commandes exactes à exécuter à chaque étape.

La synchronisation d’exportation de Klaviyo écrit dans KLAVIYO_PROFILE avec un MERGE (upsert) à chaque exécution périodique. Les tables hybrides sont un type de table Snowflake conçu pour des lectures et des écritures ponctuelles à faible latence, basées sur des index. La conversion réduit donc le temps et le coût de ces opérations MERGE — cela vaut quelle que soit la façon dont vous lisez la table par la suite ; cela vaut donc la peine de le faire, même si vous n’exécutez ensuite que de grandes analyses et agrégations en aval. Si vous utilisez également KLAVIYO_PROFILE pour effectuer des recherches de profil individuelles au service d’une application, d’une API ou d’une interface utilisateur, une table hybride renvoie aussi ces recherches plus rapidement.

Avant de commencer

Passez en revue les quatre vérifications ci-dessous avant de modifier quoi que ce soit.

1. Confirmez que votre compte prend en charge les tables hybrides

Remplacez KLAVIYO_DATABASE et KLAVIYO_DATA_TRANSFER_WAREHOUSE par les noms que vous avez définis dans votre script de configuration Snowflake. Le script crée la table des profils à partir d’une variable $profile_table, alors remplacez par la valeur que vous y avez attribuée partout où cet article fait référence à 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;

Si l’une ou l’autre instruction échoue, les tableaux hybrides ne sont pas activés pour votre compte ou votre région, et vous devez vous arrêter ici.

2. Dimensionnez votre table de profils

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';

Les tables hybrides utilisent un stockage principal basé sur les lignes ; les mêmes données occupent donc généralement plus d’espace que dans une table standard en colonnes. Considérez le chiffre SIZE_GB comme un minimum, et non comme une estimation, et prévoyez une marge sous le quota de 2 TB par base de données.

3. Vérifier les ID en double ou nuls

Le script de configuration de Klaviyo déclare déjà une clé primaire (ID) sur la table standard, mais Snowflake n’applique pas les clés primaires sur les tables standard. Les tables hybrides les appliquent, donc les ID dupliqués ou nuls qui étaient tolérés auparavant bloqueront désormais le chargement. Les deux requêtes doivent renvoyer 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;

Si l’une ou l’autre renvoie une valeur différente de zéro, résolvez le problème de qualité des données dans la table standard avant de continuer. Sinon, le chargement à l’étape 2 échouera.

4. Vérifier les dépendances en aval

Les tables hybrides ne prennent pas en charge les clés de clustering, le partage de données, les tables dynamiques, Fail-safe, les vues matérialisées, Query Acceleration Service, la réplication, Search Optimization Service, Snowpipe, Snowpipe Streaming, les streams ni UNDROP. Time Travel est pris en charge avec des limitations.

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

Si un élément en aval dépend d’une fonctionnalité non prise en charge, reconstruisez-le avant de migrer.

Étape 1 : mettez en pause votre synchronisation d’exportation

Dans Klaviyo, accédez à Advanced KDP > Data management > Syncing, cliquez sur votre destination Snowflake, ouvrez l’onglet Periodic, puis sélectionnez Pause.

Attendez que toute synchronisation en cours affiche le statut Terminé ou En pause avant de continuer. La migration pendant qu’une synchronisation écrit dans la table peut entraîner la suppression de lignes.

Étape 2 : créer la table hybride et la charger

CREATE HYBRID TABLE ... AS SELECT vous oblige à déclarer explicitement le schéma complet des colonnes ; il ne peut pas être déduit du SELECT. Utilisez les mêmes noms de colonnes et types de données que la table existante afin que la synchronisation de Klaviyo continue d’y écrire sans modifications.

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;

Charger une table très volumineuse par lots

Si une seule instruction CTAS est trop volumineuse pour s’exécuter confortablement, créez la table hybride vide, puis chargez-la par plages de dates. INSERT INTO ... SELECT utilise également le chemin optimisé de chargement en masse.

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;

Ajustez les limites en fonction de vos données, et assurez-vous que les plages ne se chevauchent pas et ne laissent pas de lacunes.

Étape 3 : ajouter des index secondaires

La clé primaire sur l’ID est indexée automatiquement. Ajoutez des index secondaires uniquement pour les colonnes sur lesquelles vous filtrez réellement, car chaque index consomme du stockage, et augmente le coût de chaque écriture. Si vous recherchez des profils par EMAIL ou EXTERNAL_ID, indexez ces colonnes ; si vous filtrez ou triez également par récence (par exemple, en récupérant les profils mis à jour depuis un moment donné), indexez UPDATED.

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);

Pour voir les index de la table :

SHOW INDEXES IN TABLE KLAVIYO_PROFILE_HYBRID;

Étape 4 : valider le texte

Le nombre de lignes doit correspondre, et la requête de différence doit renvoyer 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
);

Confirmez que la nouvelle table est bien hybride, puis effectuez une vérification ponctuelle d’une lecture ponctuelle par rapport à la même requête sur la table standard :

SHOW HYBRID TABLES LIKE 'KLAVIYO_PROFILE_HYBRID';

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

Étape 5 : remplacer la table hybride

Renommez la table standard pour la mettre de côté plutôt que de la supprimer, afin de disposer d’une option de restauration.

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;

Étape 6 : réattribuez les privilèges au rôle Klaviyo

Remplacez le nom du rôle que vous avez défini comme role_name dans votre script de configuration 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;

Étape 7 : reprendre la synchronisation et confirmer

Dans Klaviyo, revenez à Advanced Klaviyo Data Platform > Gestion des données > Synchronisation, cliquez sur votre destination Snowflake, ouvrez l’onglet Périodique, puis sélectionnez Reprendre.

Les synchronisations périodiques s’exécutent toutes les heures. Une fois le prochain cycle terminé, confirmez que l’état est Terminé et vérifiez que les données sont bien ingérées :

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

Si la synchronisation génère une erreur, ouvrez l’exportation ayant échoué dans l’onglet Périodique pour lire le récapitulatif de l’erreur, le code, et le message renvoyé par Snowflake. Consultez la section Afficher les journaux d’erreurs de Comprendre la synchronisation des entrepôts de données dans Klaviyo.

Rétablissement

Si la synchronisation échoue avec la table hybride et que vous devez revenir en arrière, mettez la synchronisation en pause et échangez à nouveau les tables.

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;

Reprenez ensuite la synchronisation. La prochaine synchronisation périodique de Klaviyo complète rétroactivement tout élément créé ou mis à jour pendant que la table a été remplacée.

Après votre migration

Une fois que vous avez confiance dans la nouvelle table, supprimez la sauvegarde afin qu’elle cesse d’accumuler des coûts de stockage.

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

Gardez les points suivants à l’esprit au fil du temps :

• Quota de stockage: vous êtes limité à 2 TB de données de tables hybrides par base de données Snowflake. Si vous le dépassez, les écritures dans chaque table hybride de cette base de données sont bloquées jusqu’à ce que vous rameniez l’utilisation sous le quota, ce qui fera échouer votre synchronisation Klaviyo.
• Quota de requêtes: environ 16 000 opérations par seconde et par base de données pour une charge de travail équilibrée de 80 % de lecture / 20 % d’écriture.
• Aucune sécurité intégrée, voyage dans le temps limité: UNDROP n’est pas pris en charge pour les tables hybrides. Maintenez votre propre processus de sauvegarde si vous en avez besoin.
• Aucun cache des résultats: les requêtes sur des tables hybrides n’utilisent pas le cache des résultats de requête persistés de Snowflake.
• Coût: le stockage de table hybride et les requêtes sont facturés séparément du stockage de table standard et du calcul. Consultez la documentation sur les coûts de Snowflake avant de migrer une grande table.

Ressources supplémentaires

• Comprendre la synchronisation des entrepôts de données dans Klaviyo
• Connexion de Klaviyo et Snowflake
• Snowflake : Tables hybrides
• Snowflake : Créer des tables hybrides
• Snowflake: Limitations et fonctionnalités non prises en charge pour les tables hybrides
• Snowflake: Évaluer le coût des tables hybrides
• Snowflake : conversion de tables Snowflake standard en tables hybrides