Verbindung zwischen Klaviyo und Snowflake

In diesem Artikel verwenden wir den Begriff „Tabelle“, aber Views, Materialized Views und Tabellen sind alles gültige Snowflake-Objekte, die importiert werden können. Solange Klaviyo SELECT col1 FROM table_name auf dem Objekt ausführen kann, kannst du verwenden, was du willst. 

Die Schlüsselwörter "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", und "OPTIONAL" in diesem Dokument sind wie in RFC 2119 beschrieben zu interpretieren.

Snowflake Administrator Setup

In diesem Abschnitt werden die Schritte beschrieben, die du in deiner Snowflake-Umgebung durchführen musst, damit Klaviyo deine Daten importieren kann. 

1. Erstelle einen privaten Schlüssel, indem du den folgenden Befehl in deinem lokalen Terminal ausführst:

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

2. Erstelle einen öffentlichen Schlüssel, der auf den privaten Schlüssel verweist, indem du den folgenden Befehl in deinem Terminal ausführst:

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

3. Kopiere die rsa_key.pub und füge sie in das folgende Skript ein, um den Platzhalter 'GENERATE_PUBLIC_KEY' für user_rsa_public_key zu ersetzen. Das unten stehende Skript funktioniert für Mac-Benutzer. Du kannst rsa_key.pub auch in einer IDE öffnen und den gesamten Inhalt der Datei kopieren, wenn du das möchtest. 

# Mac-Terminal-Befehl, um den Schlüssel in dein Terminal zu schreiben und ihn in die Zwischenablage zu kopieren
cat rsa_key.pub | tee /dev/tty | pbcopy

4. Führe das folgende Skript in deiner Snowflake-Umgebung aus, um einen Service-Benutzer zu erstellen, den Klaviyo nutzen kann. Du musst über securityadmin- und sysadmin-Rechte verfügen, um die folgenden Einstellungen vornehmen zu können. Um zu überprüfen, welche Rolle(n) du hast, führe SHOW GRANTS TO USER <your_username> aus und stelle sicher, dass beide Rollen aufgelistet sind. erreichst du einen Systemadministrator, wenn du deine Rolle anpassen lassen musst.
   1. Du kannst jede der Variablen, die am Anfang des Skripts gesetzt wurden, aktualisieren.
   2. Zusammengefasst wirst du:
      1. Wähle ein bestehendes Lager oder erstelle ein neues
      2. Wähle eine bestehende Datenbank oder erstelle eine neue, um die neuen Schemata zu speichern
      3. Erstelle zwei neue Schemas KLAVIYO_TMP und KLAVIYO_IMPORT_FROM_DWH
      4. Erstelle eine neue Netzwerkrichtlinie und erlaube die Liste der Klaviyo IPs
      5. Erstelle einen Benutzer und eine Rolle für Klaviyo
   3. Dieses Skript ist idempotent (kann sicher mehrmals ausgeführt werden), überschreibt aber keine bestehenden Objekte mit widersprüchlichen Namen. 

BEGIN;

-- Erstelle Variablen für Benutzer / Passwort / Rolle / Lager / Datenbank. 
-- Ändere sie in das, was du bevorzugst.
SET role_name = 'KLAVIYO_DATA_TRANSFER_ROLE'; -- alle Buchstaben müssen in Großbuchstaben geschrieben werden, z.B. 'KLAVIYO_DATA_TRANSFER_ROLE'
SET user_name = 'KLAVIYO_DATA_TRANSFER_USER'; -- alle Buchstaben müssen in Großbuchstaben geschrieben werden, z.B. 'KLAVIYO_DATA_TRANSFER_USER'
SET warehouse_name = 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'; -- alle Buchstaben müssen in Großbuchstaben geschrieben werden, z.B. 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'
SET database_name = 'KLAVIYO_DATABASE'; -- alle Buchstaben müssen in Großbuchstaben geschrieben werden, z.B. 'KLAVIYO_DATABASE'. Wenn diese Datenbank nicht existiert, wird eine neue erstellt.
SET network_policy = 'KLAVIYO_DATA_TRANSFER_NETWORK_POLICY'; -- alle Buchstaben müssen in Großbuchstaben geschrieben werden, z.B. 'KLAVIYO_NETWORK_POLICY'
SET network_rule = 'KLAVIYO_DATA_TRANSFER_NETWORK_RULE'; -- alle Buchstaben müssen in Großbuchstaben geschrieben werden, z.B. 'KLAVIYO_NETWORK_RULE'
/* ersetze GENERATE_PUBLIC_KEY unten durch den generierten öffentlichen Schlüssel */

-- 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; -- NICHT ÄNDERN
SET full_network_rule_import = $schema_name_import || '.' || $network_rule; -- DO NOT CHANGE


-- ändere die Rolle in sysadmin für die Schritte warehouse / database
USE ROLE sysadmin;

-- erstelle ein warehouse für den Datentransferdienst
CREATE WAREHOUSE IF NOT EXISTS IDENTIFIER($warehouse_name)
 warehouse_size = xsmall
 warehouse_type = standard
 auto_suspend = 60
 auto_resume = true
 initially_suspended = true;

-- Datenbank für Datenübertragungsdienst erstellen
CREATE DATABASE IF NOT EXISTS IDENTIFIER($database_name);

-- Schemas für Datenübertragungsdienst erstellen
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_tmp);
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($schema_name_import);

-- Rolle in securityadmin für Benutzer/Rollenschritte ändern
USE ROLE securityadmin;

-- Netzwerk erstellen  Regel und Richtlinie für Datenbank
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, für 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);


-- Rolle für den Datentransferdienst erstellen
CREATE ROLE IF NOT EXISTS IDENTIFIER($role_name);
GRANT ROLE IDENTIFIER($role_name) TO ROLE sysadmin;

-- einen Benutzer für den Datentransferdienst erstellen
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);

-- gewährt dem Dienst Zugriff auf die Datenbank
GRANT überwachen, USAGE
 ON DATABASE IDENTIFIER($database_name)
 TO ROLE IDENTIFIER($role_name);

-- gewährt Privilegien für KLAVIYO_TMP 
GRANT USAGE ON SCHEMA IDENTIFIER($schema_name_tmp) TO ROLE IDENTIFIER($role_name);
GRANT überwachen, 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);

-- Erteile Rechte für 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;

Snowflake Daten Setup

Oben hast du zwei neue Schemata erstellt. 

• KLAVIYO_TMP wird ausschließlich von Klaviyo verwendet. Du MUSST KEINE Tabellen ändern, die in diesem Schema erstellt wurden. Klaviyo löscht diese Tabellen, wenn sie nicht mehr benötigt werden.
• KLAVIYO_IMPORT_FROM_DWH ist der Ort, an dem du im Online-Shop deine endgültigen Tabellen für Klaviyo importieren solltest. Wenn du die Synchronisierung durchführst, werden alle Tabellen in diesem Schema aufgelistet, aus denen du auswählen kannst. Daher solltest du nur die Endtabellen, die du importieren willst, im Online-Shop bestellen, um Verwirrung bei der Einrichtung zu vermeiden. 

Alle Tabellen, die du mit deinem Abonnement in Klaviyo importieren möchtest, müssen die folgenden Kriterien erfüllen. 

Zeitstempel Anforderungen 

1. Tabellen MÜSSEN ein Zeitstempelfeld enthalten, das angibt, wann die Zeile erstellt oder aktualisiert wurde. Oft wird dies inserted_at oder updated_at sein. Du stellst dies für jede Tabelle während der Erstellung der Synchronisierung ein.
   1. Das Zeitstempelfeld MUSS monoton ansteigen (d.h. es muss immer größer werden oder gleich bleiben, niemals kleiner werden).
   2. Nach der Synchronisierung darfst du den Zeitstempel einer Zeile NICHT auf einen Zeitpunkt in der Vergangenheit setzen, sonst kann Klaviyo diese Zeile nicht abrufen.
   3. Die Zeitzone dieses Feldes ist für Klaviyo nicht wichtig, solange du die oben genannten Anforderungen erfüllst
   4. Klaviyo EMPFIEHLT dir, das Zeitstempelfeld mit CURRENT_TIMESTAMP() oder einer gleichwertigen Funktion zu setzen. Mehrere Zeilen können denselben Zeitstempel haben. Siehe Beispiel unten. 

INSERT INTO table_name AS 

SELECT ... 

, CURRENT_TIMESTAMP() AS inserted_at

... 

2. Deine Zeitstempel MÜSSEN in UTC angegeben werden oder Informationen zur Zeitzone enthalten. Wenn die Zeitzone nicht angegeben ist, geht Klaviyo von UTC aus. Bei benutzerdefinierten Eigenschaften bleiben diese Zeitstempel im String-Format, so dass du sie in deiner bevorzugten Zeitzone interpretieren kannst.

Struktur der Tabelle 

3. Tabellen SOLLTEN als „append-only“ (aka „insert-only“) behandelt werden.
   1. Wenn du stattdessen die Zeilen aktualisieren möchtest, MUSST du das Zeitstempelfeld aktualisieren, damit Klaviyo die Änderung identifizieren kann.
4. Die Tabellen SOLLTEN nach deiner Zeitstempelspalte geordnet sein. Snowflake übernimmt das Clustering und die Partitionierung basierend auf deiner Einfügereihenfolge. Dies wird dazu beitragen, die Importabfragen von Klaviyo zu optimieren und die Rechenkosten in Snowflake zu senken.

Profil Einzigartigkeit und Beständigkeit 

5. Du MUSST sicherstellen, dass jede Profileigenschaft nur aus einer Datenquelle (Tabelle) importiert wird. Klaviyo verhindert, dass bei der Erstellung der Synchronisierung dieselbe Eigenschaft aus verschiedenen Tabellen ausgewählt wird, was diese Anforderung vereinfacht.
6. Du SOLLST in all deinen Importtabellen dieselbe(n) Profilkennung(en) (E-Mail, Telefonnummer, externe ID usw.) verwenden, um das Risiko zu minimieren, dass doppelte Profile erstellt werden.
   1. Klaviyo erstellt ein neues Profil, wenn die Profilkennung, die du angibst, nicht mit einem bestehenden Profil auf Klaviyo übereinstimmt.
   2. Beispiel: Tabelle1 (E-Mail, fav_color) + Tabelle2 (Telefon, Geburtstag)
      1. Dadurch können 2 Profile für dieselbe Person erstellt werden, wenn das Profil noch nicht existiert. Wenn ein Profil vorhanden ist, kümmert sich Klaviyo intern um die Profilauflösung und Aktualisierung. 
   3. Eine Möglichkeit, dieses Problem zu vermeiden, ist, nur eine einzige Importtabelle für dein gesamtes Profil zu verwenden. 

Vermeidung von Import-Export-Kreisläufen 

7. Du SOLLST Szenarien, in denen sowohl Import- als auch Exportfunktionen verwendet werden, sorgfältig verwalten, um zirkuläre Import-Export-Schleifen zu vermeiden. Stelle sicher, dass dein Exportprozess keine Daten in eine Tabelle zurückführt, die deiner Importtabelle vorgelagert ist, da Klaviyo dieses Szenario derzeit nicht erkennt.
   1. Klaviyo hat noch keine Logik, um dieses Szenario zu erkennen.
   2. Das würde etwa so aussehen:
      1. Bei jedem Export-Sync-Zyklus exportiert Klaviyo alle deine Profil
      2. Dann fügst du alle deine exportierten Profile durch eine Reihe von Transformationen zu deiner Importtabelle hinzu.
      3. Bei jedem Import-Sync-Zyklus liest Klaviyo alle Profile in deiner Importtabelle, die schließlich wieder exportiert werden
   3. Szenarien, in denen dies wahrscheinlich sicher ist 
      1. wenn du die Exporttabelle nur dazu verwendest, die zu deiner Importtabelle hinzugefügten Zeilen einzuschränken
      2. Wenn du überprüfst, dass die Exporttabelle keine Zeilen zu deiner Importtabelle hinzufügt.
   4. Was sind die Folgen einer zirkulären Import-Export-Schleife?
      1. Das führt zu unnötigen Rechenkosten für dich und Klaviyo.