Come esportare i dati di Klaviyo in Databricks
Advanced Klaviyo Data Platform non è incluso nell'applicazione di marketing standard di Klaviyo e per accedere alle funzionalità associate è necessario un abbonamento. Visita la nostra guida alla fatturazione per scoprire come acquistare questo piano.
Cosa imparerai
Scopri come configurare Databricks come destinazione di sincronizzazione in uscita, così Klaviyo scrive continuamente i dati di profilo, evento e metrica nelle tabelle Delta nel tuo workspace Databricks. Una volta effettuata la connessione, il tuo team di dati può unire i dati di Klaviyo al resto del tuo lakehouse per analisi, modellazione e reportistica.
Vuoi invece importare dati in Klaviyo da Databricks? Vedi Collegare Klaviyo e Databricks.
Prima di iniziare
Assicurati di avere quanto segue:
- Uno spazio di lavoro Databricks con Unity Catalog abilitato. Gli spazi di lavoro solo Hive metastore non sono supportati. Se usi Hive metastore, valuta la federazione di Hive metastore.
- Un data warehouse SQL che supporta
VARIANTcolonne e tabelle temporanee con ambito di sessione, in modo che Klaviyo possa scrivere i dati. Ti consigliamo i data warehouse SQL serverless; i data warehouse Classic e Pro possono impiegare diversi minuti ad avviarsi, il che potrebbe ritardare le sincronizzazioni. - Autorizzazione a creare schemi, tabelle e autorizzazioni nel catalogo che utilizzerai (oppure supporto di un amministratore Databricks).
- Autorizzazione a gestire le integrazioni in Klaviyo.
- Gli indirizzi IP in uscita di Klaviyo inseriti nella allowlist, se il tuo spazio di lavoro limita il traffico in ingresso con elenchi di accesso IP:
184.72.183.187/3252.206.71.52/323.227.146.32/3244.198.39.11/3235.172.58.121/323.228.37.244/3254.88.219.8/323.214.211.176/32
Puoi avere solo 1 destinazione di esportazione del magazzino dati per ogni account Klaviyo. Se esporti già in un altro data warehouse (ad esempio Snowflake o S3), dovrai rimuovere quella destinazione prima di aggiungere Databricks.
Passaggio 1: crea uno schema per i dati di Klaviyo
In Databricks, gli schemi si trovano all'interno di un catalogo. Crea uno schema dedicato per contenere le tabelle su cui scrive Klaviyo. Gli esempi SQL in questo articolo usano main come catalogo e KLAVIYO_EXPORT come schema. Se usi nomi diversi, sostituiscili in tutti gli esempi SQL e inserisci gli stessi nomi in Klaviyo durante il passaggio 5.
USE CATALOG main; -- or your organization's designated catalog
CREATE SCHEMA IF NOT EXISTS KLAVIYO_EXPORT;Passaggio 2: crea le tabelle di destinazione
Esegui lo script seguente nello schema che hai creato nel passaggio 1. Klaviyo scrive su 3 tabelle:
klaviyo_profile: Una riga per profilo, inclusi campi standard, posizione e proprietà personalizzate.klaviyo_event: Una riga per evento (ad esempio Placed Order o Opened Email), collegata a un profilo e a una metrica.klaviyo_metric: Una riga per metrica, usata per cercare il nome della metrica e l'integrazione di origine per ogni evento.
Le proprietà personalizzate del profilo e le proprietà evento vengono archiviate in colonne VARIANT, così puoi eseguire query su JSON nidificato direttamente senza gestire centinaia di singole colonne.
USE SCHEMA main.KLAVIYO_EXPORT;
CREATE TABLE klaviyo_profile (
id STRING NOT NULL,
external_id STRING,
email STRING,
phone_number STRING,
first_name STRING,
last_name STRING,
title STRING,
organization STRING,
properties VARIANT,
image STRING,
created TIMESTAMP,
updated TIMESTAMP,
location_address1 STRING,
location_address2 STRING,
location_city STRING,
location_country STRING,
location_latitude STRING,
location_longitude STRING,
location_region STRING,
location_zip STRING,
PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');
CREATE TABLE klaviyo_event (
id STRING NOT NULL,
metric_id STRING NOT NULL,
profile_id STRING,
event_properties VARIANT,
datetime TIMESTAMP,
uuid STRING,
PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');
CREATE TABLE klaviyo_metric (
id STRING NOT NULL,
name STRING NOT NULL,
integration_id STRING,
integration_name STRING,
integration_category STRING,
created TIMESTAMP,
updated TIMESTAMP,
PRIMARY KEY (id)
);I nomi delle tabelle devono corrispondere esattamente. Klaviyo cerca klaviyo_profile, klaviyo_event e klaviyo_metric nello schema che fornisci durante la configurazione.
Passaggio 3: crea un service principal e un token di accesso
Klaviyo esegue l’autenticazione su Databricks con un token di accesso personale (PAT). Ti consigliamo di creare un service principal dedicato da usare solo per questa integrazione, anziché l'account di una persona.
- Crea un service principal (o un utente dello spazio di lavoro) per Klaviyo.
- Genera un token di accesso personale:
- Service principal: chiedi a un amministratore del workspace di creare il token iniziale con la Databricks CLI.
- Utente dello spazio di lavoro: Crea un token nell’interfaccia utente di Databricks.
- Archivia il token in un luogo sicuro. Lo incollerai in Klaviyo al passaggio 5.
Tratta il token di accesso come una password. Chiunque disponga del token può accedere a Databricks con le autorizzazioni dell'account associato. Ruotalo regolarmente e dopo cambiamenti nel personale.
Se hai già creato un service principal per importare da Databricks, puoi riutilizzarlo. Aggiungi semplicemente le autorizzazioni di esportazione nel passaggio 4.
Passaggio 4: concedi le autorizzazioni
Concedi al service principal di Klaviyo l'accesso al catalogo, allo schema e al warehouse SQL. Sostituisci klaviyo_service_user con l'ID applicazione o il nome utente del tuo service principal.
GRANT USE CATALOG ON CATALOG main TO `klaviyo_service_user`;
GRANT USE SCHEMA, SELECT, MODIFY ON SCHEMA main.KLAVIYO_EXPORT TO `klaviyo_service_user`;Privilegio | Obiettivo |
|---|---|
| Consente a Klaviyo di accedere al catalogo che contiene lo schema di esportazione. |
| Consente a Klaviyo di accedere allo schema di esportazione. |
| Consente a Klaviyo di leggere le righe esistenti, così può aggiornare i record invece di duplicarli. |
| Consente a Klaviyo di inserire, aggiornare ed eliminare righe nelle tabelle di destinazione. |
Assegna inoltre al service principal l’autorizzazione Può usare sul data warehouse SQL che intendi utilizzare. In Databricks, vai a Data warehouse SQL, seleziona il tuo data warehouse, fai clic su Autorizzazioni e aggiungi il service principal.
Verifica la tua configurazione (facoltativo)
Usando la stessa identità e lo stesso token che fornirai a Klaviyo, conferma le tabelle e le autorizzazioni:
SHOW TABLES IN main.KLAVIYO_EXPORT;
SHOW GRANTS ON SCHEMA main.KLAVIYO_EXPORT;Dovresti vedere tutte e 3 le tabelle e il service principal dovrebbe essere elencato con USE SCHEMA, SELECT e MODIFY.
Passaggio 5: connetti Databricks in Klaviyo
- In Klaviyo, vai a Advanced > Data management > Syncing.
- Se hai già una sincronizzazione, fai clic su Crea sincronizzazione.
- Seleziona Esporta i dati nel tuo magazzino dati.
- Scegli Databricks, poi fai clic su Connetti a Databricks.
- Inserisci i dettagli della connessione:
Campo | Descrizione | Dove trovarla |
|---|---|---|
Nome | Un nome che ti aiuti a identificare questa connessione. | Inserisci un nome descrittivo, ad esempio esportazione di Klaviyo. |
Nome host del server | L'host della tua area di lavoro Databricks. | La barra degli indirizzi del browser quando hai effettuato l’accesso a Databricks. Esempio: |
Percorso HTTP | Il percorso HTTP del data warehouse SQL che Klaviyo utilizzerà. | SQL Warehouses > seleziona il tuo warehouse > Dettagli della connessione. Esempio: |
Catalogo | Il catalogo che contiene lo schema di esportazione. | Il catalogo che hai utilizzato nel passaggio 1 (ad esempio, |
Schema | Lo schema che contiene le 3 tabelle Klaviyo. | Lo schema che hai creato nel passaggio 1 (ad esempio, |
Token di accesso | Il token di accesso personale per il service principal o l’utente dell’area di lavoro che hai creato. | Il token che hai generato nel passaggio 3. |
Clicca su Avanti per configurare la sincronizzazione.
Puoi anche trovare Databricks nel marketplace delle app di Klaviyo andando su Integrazioni > Esplora app e cercando Databricks.
Passaggio 6: configura la sincronizzazione dei dati
Scegli cosa Klaviyo invia a Databricks e quando esegue la sincronizzazione.
Oggetti dei dati
Scegli se sincronizzare profili, eventi o entrambi. I dati delle metriche vengono sincronizzati insieme agli eventi, così puoi cercare il nome e la fonte della metrica di ogni evento.
La sincronizzazione di tutti i dati da Klaviyo può aumentare i costi di calcolo e archiviazione di Databricks.
Integrazioni da escludere
Seleziona le integrazioni i cui eventi non vuoi inviare a Databricks. Questo vale solo per i dati degli eventi; non esclude i profili.
Sincronizzazione selettiva
Seleziona le metriche i cui eventi vuoi sincronizzare, ad esempio Placed Order. Lascia vuoto Sincronizzazione selettiva per sincronizzare tutti gli eventi dalle integrazioni che non hai escluso. Questo campo viene visualizzato solo se selezioni l’oggetto dati Eventi.
Frequenza di sincronizzazione
In Ogni, scegli con quale frequenza sincronizzare i dati nuovi e aggiornati: ogni 1, 2, 4, 6, 12 o 24 ore. L’impostazione predefinita è 1 ora. Imposta Data di inizio, Ora di inizio e Fuso orario per la pianificazione.
Dati storici
Scegli la quantità di storico dei dati da inviare durante la sincronizzazione iniziale:
- 30 giorni
- 90 giorni
- 1 anno
- Per tutto il tempo
Le sincronizzazioni storiche di grandi dimensioni possono richiedere un po' di tempo per essere completate e potrebbero aumentare i costi di Databricks. Valuta di iniziare con un intervallo più breve se ti servono solo dati recenti.
Passaggio 7: rivedi, collega e monitora la sincronizzazione
- Fai clic su Avanti per aprire Revisione. Controlla i dettagli della connessione, i dati condivisi, le integrazioni escluse, le metriche selezionate e l'intervallo iniziale di sincronizzazione dei dati.
- Clicca su Connetti. Klaviyo testa la connessione e crea l’esportazione se il test va a buon fine.
Quando la configurazione va a buon fine, Klaviyo mostra un messaggio di conferma e ti riporta a Syncing. La tua esportazione è abilitata e puoi monitorarne lo stato di sincronizzazione lì.
Se il test di connessione non riesce, controlla i dettagli dell’errore. Fai clic su Modifica credenziali per correggere i dettagli della connessione, poi fai clic su Avanti nelle impostazioni dei dati per tornare a Riepilogo e fai di nuovo clic su Connetti.
Per monitorare la sincronizzazione, vai a Advanced > Data management > Syncing e fai clic su Databricks nella riga contrassegnata Export. Usa queste schede:
- Cronologia: lo stato del backfill iniziale.
- Periodico: lo stato delle sincronizzazioni secondo la cadenza selezionata, inclusa la freschezza dei dati (quanto sono indietro rispetto a Klaviyo le tabelle Databricks).
- Impostazioni: visualizza e modifica i dettagli della connessione, la selezione dei dati, la frequenza di sincronizzazione e l’intervallo storico. Fai clic su Aggiorna informazioni nella sezione che modifichi per salvare.
Per i dettagli sugli stati di sincronizzazione, la messa in pausa e la ripresa delle sincronizzazioni e la visualizzazione dei registri degli errori, consulta Informazioni sulla sincronizzazione del magazzino dati in Klaviyo.
Esegui query sui dati di Klaviyo in Databricks
Ecco alcuni esempi per iniziare.
Conta gli eventi in base al nome della metrica negli ultimi 7 giorni:
SELECT m.name AS metric, COUNT(*) AS events
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE e.datetime >= current_timestamp() - INTERVAL 7 DAYS
GROUP BY m.name
ORDER BY events DESC;Leggi una Proprietà del profilo personalizzata dalla colonna properties variante:
SELECT id, email, properties:loyalty_tier::STRING AS loyalty_tier
FROM main.KLAVIYO_EXPORT.klaviyo_profile
WHERE properties:loyalty_tier IS NOT NULL;Ottieni il valore dell'ordine dagli eventi Placed Order:
SELECT e.profile_id, e.datetime, e.event_properties:`$value`::DOUBLE AS order_value
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE m.name = 'Placed Order';Risoluzione dei problemi
Problema | Cosa verificare |
|---|---|
Il test di connessione non riesce a causa di un errore di autenticazione | Verifica che l’hostname non abbia il prefisso |
Il test di connessione non riesce a causa di un errore di autorizzazioni | Conferma le concessioni nel passaggio 4, incluse |
Klaviyo non riesce a trovare le tabelle di destinazione | Verifica che il catalogo e lo schema in Klaviyo corrispondano a dove hai eseguito lo script del passaggio 2 e che i nomi delle tabelle siano esattamente |
Errori relativi al tipo | Assicurati che il tuo magazzino SQL esegua una versione di Databricks SQL che supporta |
Le sincronizzazioni sono lente ad avviarsi | I warehouse SQL Classic e Pro possono impiegare diversi minuti per avviarsi. Usa un warehouse SQL serverless o aumenta il tempo di arresto automatico del warehouse. |
Le richieste sono bloccate | Se il tuo spazio di lavoro utilizza elenchi di accesso IP, aggiungi alla lista consentita gli indirizzi IP di Klaviyo elencati in Before you begin. |
Rimuovi un'esportazione Databricks
La rimozione dell’esportazione interrompe le sincronizzazioni future. I dati già scritti nelle tabelle Databricks non vengono eliminati.
- Vai a integrazioni in Klaviyo.
- Apri il menu accanto all’integrazione di esportazione Databricks e seleziona Rimuovi integrazione.
- Fai clic su Rimuovi integrazione nella finestra di dialogo di conferma.