Primi passi con SQL in Composer e nel server MCP di Klaviyo
Cosa imparerai
Scopri come porre domande di analisi sui tuoi dati Klaviyo in linguaggio naturale usando Composer o il server Klaviyo Model Context Protocol (MCP). Klaviyo Data Platform SQL riunisce profili, segmenti di pubblico, campagne, prodotti ed eventi per rispondere a domande che coinvolgono più set di dati. Non devi scrivere SQL.
SQL è attualmente in beta ed è disponibile per tuttə i clienti.
Prima di iniziare
Scegli dove vuoi fare le tue domande:
- Usa Composer per lavorare nella chat in Klaviyo. Non è necessaria alcuna configurazione SQL aggiuntiva.
- Usa il server MCP di Klaviyo per lavorare in un client IA connesso, come Claude o ChatGPT. Se hai già connesso Klaviyo, non devi installare un altro strumento, anche se potresti dover aggiornare l'elenco degli strumenti del client.
Entrambe le opzioni usano gli stessi dati e supportano gli stessi tipi di domande di analisi. SQL è progettato per l’analisi. Per le esportazioni di dati in blocco, usa altri strumenti di Klaviyo, ad esempio i report personalizzati.
In genere, i dati hanno circa 30 minuti di ritardo rispetto all'attività nel tuo account. Per un ordine, un invio o una modifica dell’iscrizione molto recenti, controlla direttamente in Klaviyo.
Fai la tua prima domanda di analytics
Usa Composer
- Apri Composer in Klaviyo. Se hai bisogno di aiuto per trovarlo, consulta Primi passi con Composer.
- Poni una domanda di analisi in linguaggio naturale. Includi la metrica, l'intervallo di date ed eventuali dettagli su pubblico o prodotto. Ad esempio: “Quali sono i miei 5 prodotti principali per unità vendute negli ultimi 90 giorni?”
- Esamina la risposta, poi fai domande di approfondimento nella stessa conversazione per esplorarla ulteriormente.
Composer decide quando usare SQL. Non devi dare un nome a uno strumento o modificare un’impostazione.
Usa il Server MCP di Klaviyo
Per connettere un client IA, ti serve un ruolo di Proprietario, Amministratore o Manager nell'account Klaviyo che vuoi usare. Quando la connessione utilizza una chiave API, la chiave deve avere accesso ai set di dati coinvolti nella tua domanda. Ad esempio, una domanda su ordini e segmenti richiede l'accesso a eventi e segmenti.
- Connetti Klaviyo usando la guida per il tuo cliente o la tua configurazione:
- Documentazione per sviluppatori del server MCP di Klaviyo per connessioni al terminale e a server remoti
- FAQ sull'app Klaviyo per Claude
- Come utilizzare l'app Klaviyo per ChatGPT
- Guida al server MCP di Klaviyo per le agenzie per lavorare su più account cliente
- Fai una domanda di analisi dettagliata nel client connesso. Non devi nominare lo strumento ask_analytics_question. Il client lo seleziona quando è appropriato per la domanda.
- Rivedi la risposta e continua con le domande di approfondimento. Se lo strumento non è disponibile, aggiorna l’elenco degli strumenti Klaviyo del tuo cliente seguendo i passaggi di risoluzione dei problemi riportati di seguito.
Se ti connetti tramite OAuth, segui la guida del tuo cliente per rivedere e concedere le autorizzazioni richieste.
Sviluppa una risposta e verifica il calcolo
SQL è utile quando una domanda richiede informazioni provenienti da più set di dati. Ad esempio, un conteggio degli ordini diventa un'analisi del pubblico più dettagliata quando aggiungi clienti, appartenenza al segmento e paese.
Inizia con una domanda, poi sviluppa la risposta nella stessa conversazione:
- «Quanti ordini abbiamo ricevuto il mese scorso?»
- "Quanti clienti hanno effettuato quegli ordini?"
- "Suddividi questi ordini in base ai segmenti a cui attualmente appartengono i clienti."
- "Suddividi i risultati per segmento e Paese e includi le entrate per ogni gruppo."
- “Per chi acquista per la prima volta, quanta navigazione dei prodotti c’è stata nei 10 giorni precedenti al primo ordine?”
Chiedi come è stata calcolata la risposta prima di condividere un numero importante o di usarla per prendere una decisione. Per esempio:
- "Quali set di dati hai usato?"
- "Quale intervallo di date e quali filtri hai applicato?"
- "Come hai definito le entrate in questo calcolo?"
- «Mi spieghi come hai calcolato questo?»
Usa la spiegazione per verificare che la risposta corrisponda alla domanda che intendevi fare. In caso contrario, chiarisci la metrica, le date o i filtri e chiedi di nuovo.
Quali dati puoi chiedere
SQL può rispondere a domande su questi set di dati, in base alle autorizzazioni previste per la tua connessione.
Set di dati | Cosa puoi analizzare |
|---|---|
Profili | Attributi del cliente, identificatori, valore del ciclo di vita previsto, coinvolgimento degli utenti per canale, Proprietà del profilo personalizzate e consenso al marketing via e-mail e SMS |
Segmenti | Segmenti di pubblico dinamici con appartenenza ricalcolata in base alle condizioni salvate; l'analisi utilizza l'appartenenza corrente |
Elenchi | Tipi di pubblico la cui appartenenza attuale puoi collegare a profili ed eventi |
Campagne | Invii una tantum, messaggi, varianti inclusi i test A/B e segmenti di invio |
Catalogo | Prodotti sincronizzati dalla tua piattaforma di e-commerce, incluse le categorie di prodotti e le varianti |
Eventi | Attività di commercio, messaggistica, consenso, flusso, recensione, coupon, supporto, Customer Hub e integrazioni, oltre a conteggi e tassi di marketing |
Eventi e dettagli all'interno degli eventi
I dati evento disponibili includono:
- Attività di commerce, come l'aggiunta al carrello, l'invio o l'annullamento di un ordine, i rimborsi e le visualizzazioni dei prodotti
- Attività e-mail, tra cui ricevute, aperture, clic, rimbalzi, interruzioni e annullamenti dell'iscrizione
- Attività SMS e WhatsApp, inclusi ricezioni, clic, errori, consensi e annullamenti dell'iscrizione
- Attività push, inclusi ricevuti, aperture e rimbalzi
- Modifiche a consenso e sospensione, incluse iscrizioni, annullamenti dell'iscrizione, aggiunte o rimozioni della sospensione e aggiornamenti delle preferenze
- Attività del flusso, inclusi ingressi, rimozioni, evasione, salti e avvii
- Unioni profili
- Invii di recensioni e valutazioni, modifiche, eliminazioni e disponibilità alla recensione
- Assegnazioni e utilizzi dei coupon
- Attività delle conversazioni di assistenza, inclusi avvii, messaggi ricevuti o inviati, escalation, risoluzioni e creazione o chiusura dei ticket
- Attività di Customer Hub, ad esempio accessi, preferiti, clic su prodotti o coupon e visualizzazioni dei blocchi di contenuto
- Eventi delle integrazioni da origini come la tua API, Shopify e Lightspeed, inclusi attività di checkout, invii di moduli, iscrizioni al programma fedeltà, ricerche e spedizioni
- Metriche di marketing, tra cui conteggi e tassi di consegna, destinatari, aperture, clic, rimbalzi, annullamenti dell'iscrizione, segnalazioni di spam e coinvolgimento degli utenti umano
Alcuni eventi contengono valori annidati: gruppi di dettagli correlati all’interno di un evento. Ad esempio, un ordine può contenere un elenco di articoli, ciascuno con uno SKU, una quantità e un prezzo. SQL può leggere questi dettagli, quindi puoi chiedere quanti ordini includevano uno SKU specifico o qual era il numero medio di articoli per ordine.
Combina set di dati
SQL può connettere set di dati correlati per rispondere a una domanda. Questo si chiama join, ma non devi richiedere un join in modo esplicito. Ad esempio, puoi:
- Collega i messaggi della campagna ai nomi delle campagne e i dati sul coinvolgimento degli utenti per confrontare le campagne denominate.
- Collega l’appartenenza corrente a liste o segmenti a profili e ordini per analizzare l’attività di acquisto di un pubblico.
- Suddividi un pubblico per paese, stato del consenso o valore cliente previsto.
- Collega i prodotti alle categorie o le varianti ai prodotti principali per analizzare le prestazioni del prodotto o della categoria.
- Collega le assegnazioni dei coupon agli utilizzi dei coupon per calcolare il tasso di riscatto e identificare i coupon non riscattati.
Esempi di domande
Adatta le date, i prodotti, i segmenti e i dettagli della campagna al tuo account.
Obiettivo | Domanda di esempio |
|---|---|
Confronta gli ordini nel tempo | "Quanti ordini abbiamo ricevuto nel secondo trimestre 2025, nel primo trimestre 2026 e nel secondo trimestre 2026?" |
Analizza i dettagli dell'ordine | "Quanti ordini negli ultimi 90 giorni includevano lo SKU FACEBUND01?" |
Riepiloga ricavi e rimborsi | "Riepiloga gli ordini di giugno: ordini totali, ricavi totali, numero di ordini rimborsati e importo totale dei rimborsi." |
Capire gli acquisti ripetuti | “Che percentuale di clienti ha effettuato solo 1 ordine?” |
Misura il tempo tra gli acquisti | «Qual è il numero medio di giorni tra il primo e il secondo acquisto di un cliente?» |
Confronta il valore del cliente | “Confronta il valore del ciclo di vita dei clienti coinvolti via e-mail con quello dei clienti che non interagiscono.” |
Trova i prodotti migliori | “Quali sono i miei 5 prodotti principali per unità vendute negli ultimi 90 giorni?” |
Confronta il coinvolgimento degli utenti della campagna | "Quale giorno della settimana registra i migliori tassi di apertura delle campagne?" |
Esplora le prestazioni delle e-mail | «Quali sono state le mie 10 e-mail più aperte, escludendo le campagne promozionali?» |
Analizza i dispositivi | “Qual è lo split del dispositivo tra mobile e desktop per le aperture delle mie e-mail?” |
Rivedi l'attività del flusso | “Quali flussi hanno inviato messaggi nell’ultimo anno?” |
Confronta le prestazioni degli SMS | “Qual era la mia percentuale di clic (CR) e il mio tasso di annullamento dell'iscrizione per SMS ad aprile, maggio e giugno?” |
Analizza i bounce | “La mia newsletter del 2 luglio ha avuto 5.514 bounce. Venivano da 1 provider di posta? Quali erano i tipi di bounce?” |
Controlla la frequenza di invio | "Quanti profili hanno ricevuto 2 o più e-mail in 1 giorno?" |
Scopri i limiti
Dati non disponibili
SQL al momento non supporta:
- Appartenenza a liste o segmenti in un momento passato
- Moduli d'iscrizione o le loro prestazioni
- Oggetti personalizzati
- Modelli di e-mail o SMS
Gli eventi delle integrazioni possono includere gli invii dei moduli, ma questo non significa che SQL supporti l’analisi dei moduli d’iscrizione o delle loro prestazioni. Se la tua domanda dipende da dati non disponibili, la risposta potrebbe essere incompleta o il cliente potrebbe non essere in grado di rispondere.
Aggiornamento dei dati e differenze rispetto ai report di Klaviyo
In genere, i dati sono aggiornati con circa 30 minuti di ritardo rispetto al tuo account. L'attività recente potrebbe non comparire subito.
In genere, i numeri dovrebbero essere coerenti con Klaviyo, ma possono verificarsi piccole differenze a causa di differenze nelle definizioni, nelle ottimizzazioni delle query o nella freschezza dei dati. SQL utilizza un'origine dati diversa rispetto ad altri metodi di accesso ai dati di Klaviyo. Klaviyo ha verificato che questi dati sono coerenti al 99% negli ultimi 3 anni.
Chiedi il calcolo, l’intervallo di date e i filtri quando un numero differisce da un report. La spiegazione può aiutarti a capire se stai confrontando la stessa metrica e lo stesso periodo.
Query generate e timeout
SQL genera una query dalla tua domanda. Al momento non esiste un endpoint in cui puoi inviare una tua query SQL e ricevere un risultato garantito e ripetibile. Formulazioni diverse possono produrre query diverse e risultati leggermente diversi. Verifica il calcolo per i numeri importanti.
Un client MCP può smettere di attendere una risposta prima di quanto farebbe Composer. Claude, ad esempio, ha una finestra di timeout di 60 secondi. Se una domanda va in timeout, riduci l’intervallo di date, riduci il numero di suddivisioni oppure split l’analisi in domande più piccole.
Risoluzione dei problemi
Lo strumento di analisi non è disponibile
Se non vedi ask_analytics_question nel tuo client AI, verifica che SQL sia abilitato per il tuo account e aggiorna l’elenco degli strumenti Klaviyo del client.
In Claude:
- Vai a Personalizza > Connettori > Klaviyo.
- Apri il menu con i tre puntini nell'angolo in alto a destra.
- Fai clic su Aggiorna elenco strumenti, quindi riprova con la tua domanda.
SQL non riesce a restituire dati che sai essere presenti nel tuo account
Verifica se il set di dati è supportato e considera il tipico ritardo di 30 minuti. Se la connessione utilizza una chiave API, verifica che abbia accesso a ogni set di dati coinvolto, come profili, segmenti, liste, campagne, cataloghi o eventi. Aggiorna le autorizzazioni mancanti in Klaviyo, aggiorna l’elenco degli strumenti Klaviyo del cliente e riprova a inviare la domanda.
Per una connessione OAuth, verifica le autorizzazioni usando la guida alla connessione del tuo client.
Timeout della domanda
Prova un intervallo di date più breve o meno suddivisioni, oppure split la domanda in domande più piccole. Riprova con la domanda più specifica, poi sviluppa il risultato con domande di approfondimento.
Un numero non corrisponde a Klaviyo
Chiedi in che modo SQL ha calcolato il numero, inclusi i set di dati, l’intervallo di date e i filtri. Verifica se le definizioni della metrica e l’aggiornamento dei dati spiegano la differenza. Se la differenza è ampia, contatta l’assistenza Klaviyo e condividi la domanda, il numero restituito e il numero che ti aspettavi.
Composer rifiuta una domanda
Riformula la domanda includendo una metrica specifica, un intervallo di date e un pubblico. Verifica che utilizzi uno dei set di dati supportati, poi riprova.