Aan de slag met SQL in Composer en de Klaviyo MCP-server

Wat je leert

Lees hoe je in gewone taal analysevragen kunt stellen over je Klaviyo-gegevens met Composer of de Klaviyo Model Context Protocol (MCP)-server. Klaviyo Data Platform SQL brengt profielen, doelgroepen, campagnes, producten en events samen om vragen te beantwoorden die meerdere datasets omvatten. Je hoeft geen SQL te schrijven.

SQL is momenteel in bèta en is beschikbaar voor alle klanten.

Voordat je van start gaat

Kies waar je je vragen wilt stellen:

• Gebruik Composer om in de chat binnen Klaviyo te werken. Er is geen extra SQL-configuratie nodig.
• Gebruik de Klaviyo MCP server om te werken in een verbonden AI-client, zoals Claude of ChatGPT. Als je Klaviyo al hebt verbonden, hoef je geen andere tool te installeren, al moet je mogelijk de toollijst van de client vernieuwen.

Beide opties gebruiken dezelfde data en ondersteunen dezelfde soorten analyticsvragen. SQL is ontworpen voor analyse. Gebruik voor bulkdata-exports andere tools van Klaviyo, zoals aangepaste rapporten.

Gegevens lopen meestal ongeveer 30 minuten achter op activiteit in je account. Voor een heel recente bestelling, verzending of lidmaatschapswijziging check je dit direct in Klaviyo.

Stel je eerste analyticsvraag

Gebruik Composer

1. Open Composer in Klaviyo. Als je hulp nodig hebt om het te vinden, bekijk dan Aan de slag met Composer.
2. Stel een analytics-vraag in gewone taal. Neem de meetwaarde, datumbereik en eventuele doelgroep- of productdetails op. Bijvoorbeeld: "Wat zijn mijn top 5 producten op basis van verkochte aantallen in de afgelopen 90 dagen?"
3. Bekijk het antwoord en stel daarna vervolgvragen in hetzelfde gesprek om het verder te verkennen.

Composer bepaalt wanneer SQL wordt gebruikt. Je hoeft geen tool te benoemen of een instelling te wijzigen.

De Klaviyo MCP-server gebruiken

Om een AI-client te koppelen, heb je de rol eigenaar, Beheerder of manager nodig in het Klaviyo-account dat je wilt gebruiken. Wanneer je verbinding een API-sleutel gebruikt, moet de sleutel toegang hebben tot de datasets die betrokken zijn bij je vraag. Een vraag over bestellingen en segmenten heeft bijvoorbeeld toegang nodig tot events en segmenten.

1. Koppel Klaviyo met behulp van de handleiding voor je klant of setup:
   • Ontwikkelaarsdocumentatie voor de Klaviyo MCP-server voor terminal- en externe serververbindingen
   • Klaviyo-app voor Claude: veelgestelde vragen
   • Zo gebruik je de Klaviyo-app voor ChatGPT
   • Klaviyo MCP-servergids voor bureaus om te werken in meerdere klantaccounts
2. Stel een gedetailleerde analyticsvraag in je gekoppelde client. Je hoeft de tool ask_analytics_question niet te benoemen. Je client selecteert deze wanneer dat passend is voor de vraag.
3. Bekijk het antwoord en ga door met vervolgvragen. Als de tool niet beschikbaar is, vernieuw je de Klaviyo-toollijst van je klant met de stappen voor probleemoplossing hieronder.

Als je verbinding maakt via OAuth, volg je de handleiding van je klant om de gevraagde machtigingen te bekijken en te verlenen.

Bouw voort op een antwoord en controleer de berekening

SQL is handig wanneer je voor een vraag informatie uit meerdere datasets nodig hebt. Een telling van bestellingen wordt bijvoorbeeld een gedetailleerdere doelgroepanalyse wanneer je klanten, segmentlidmaatschap en land toevoegt.

Begin met een vraag en bouw daarna voort op het antwoord in hetzelfde gesprek:

1. "Hoeveel bestellingen hebben we vorige maand binnengehaald?"
2. "Hoeveel klanten hebben die bestellingen geplaatst?"
3. "Splits die bestellingen uit op basis van de segmenten waar de klanten momenteel bij horen."
4. "Splits de resultaten uit per segment en land en voeg voor elke groep de omzet toe."
5. “Voor kopers die voor het eerst iets kopen: hoeveel productbrowsing vond er plaats in de 10 dagen vóór hun eerste bestelling?”

Vraag hoe het antwoord is berekend voordat je een belangrijk getal deelt of het gebruikt om een beslissing te nemen. Bijvoorbeeld:

• "Welke datasets heb je gebruikt?"
• "Welk datumbereik en welke filters heb je toegepast?"
• "Hoe heb je omzet gedefinieerd in deze berekening?"
• "Kun je me stap voor stap uitleggen hoe je dat hebt berekend?"

Gebruik de uitleg om te controleren of het antwoord overeenkomt met je bedoelde vraag. Als dat niet zo is, verduidelijk dan de meetwaarde, datums of filters en vraag het opnieuw.

Over welke data je vragen kunt stellen

SQL kan vragen beantwoorden over deze datasets, afhankelijk van de machtigingen op je verbinding.

Evenementen en details binnen evenementen

Beschikbare gebeurtenisgegevens zijn:

• Commerce-activiteit, zoals iets aan een winkelwagen toevoegen, een bestelling plaatsen of annuleren, terugbetalingen en productweergaven
• E-mailactiviteit, waaronder ontvangsten, opens, klikken, bounces, drops en afmeldingen
• Sms- en WhatsApp-activiteit, waaronder ontvangen berichten, klikken, fouten, toestemming en afmeldingen
• Push-activiteit, waaronder ontvangsten, opens en bounces
• Wijzigingen in toestemming en onderdrukking, waaronder abonnementen, afmeldingen, toevoegingen of verwijderingen van onderdrukking en voorkeurupdates
• Flow-activiteit, waaronder items die de flow binnenkomen, verwijderingen, afhandeling, overslaan en starts
• Samenvoegingen van profielen
• Inzendingen, bewerkingen en verwijderingen van reviews en beoordelingen, en gereedheid om te beoordelen
• Coupon-toewijzingen en gebruik
• Activiteit van supportgesprekken, waaronder starts, ontvangen of verzonden berichten, escalaties, oplossingen en het aanmaken of sluiten van tickets
• Activiteit in Klaviyo Customer Hub, zoals logins, favorieten, klikken op producten of coupon, en weergaven van contentblokken
• Integratiegebeurtenissen uit bronnen zoals je API, Shopify en Lightspeed, waaronder checkout-activiteit, formulierinzendingen, loyaliteitsinschrijvingen, zoekopdrachten en verzendingen
• Marketingmeetwaarden, waaronder aantallen en percentages voor levering, ontvangers, openen, klikken, bounces, afmelden, spamklachten en menselijke betrokkenheid

Sommige events bevatten geneste waarden: groepen gerelateerde details binnen een event. Een bestelling kan bijvoorbeeld een lijst met items bevatten, elk met een SKU, hoeveelheid en prijs. SQL kan die details lezen, zodat je kunt vragen hoeveel bestellingen een specifieke SKU bevatten of wat het gemiddelde aantal items per bestelling was.

Gegevenssets combineren

SQL kan gerelateerde datasets aan elkaar koppelen om een vraag te beantwoorden. Dit heet een join, maar je hoeft niet expliciet om een join te vragen. Je kunt bijvoorbeeld:

• Koppel campagneberichten aan campagnenamen en betrokkenheidsgegevens om campagnes met naam te vergelijken.
• Koppel het huidige lidmaatschap van lijsten of segmenten aan profielen en bestellingen om de aankoopactiviteit van een doelgroep te analyseren.
• Splits een doelgroep op per land, toestemmingsstatus of voorspelde klantwaarde.
• Koppel producten aan categorieën, of variaties aan bovenliggende producten, om de prestaties van producten of categorieën te analyseren.
• Koppel coupon-toewijzingen aan coupon-gebruik om inwisselingen te berekenen en niet-ingewisselde coupons te identificeren.

Voorbeeldvragen

Pas de datums, producten, segmenten en campagnedetails aan voor je account.

Over de limieten

Niet beschikbare gegevens

SQL ondersteunt momenteel niet:

• Lidmaatschap van een lijst of segment op een eerder moment
• Aanmeldingsformulier of hun prestaties
• Aangepaste objecten
• E-mail- of sms-templates

Integratiegebeurtenissen kunnen formulierinzendingen bevatten, maar dat betekent niet dat SQL analyses van aanmeldingsformulieren of hun prestaties ondersteunt. Als je vraag afhangt van niet-beschikbare data, kan het antwoord onvolledig zijn of kan de client mogelijk geen antwoord geven.

Actuele gegevens en verschillen ten opzichte van Klaviyo-rapporten

Gegevens lopen meestal ongeveer 30 minuten achter op je account. Recente activiteit wordt mogelijk niet direct weergegeven.

Cijfers moeten over het algemeen overeenkomen met Klaviyo, maar er kunnen kleine verschillen optreden door verschillen in definities, query-optimalisaties of de actualiteit van de data. SQL gebruikt een andere databron dan andere manieren om toegang te krijgen tot Klaviyo-data. Klaviyo heeft gecontroleerd dat deze data de afgelopen 3 jaar voor 99% consistent is.

Vraag naar de berekening, de datumbereik en de filters wanneer een getal afwijkt van een rapport. De uitleg kan je helpen vast te stellen of je dezelfde meetwaarde en periode vergelijkt.

Gegenereerde queries en time-outs

SQL genereert een query op basis van je vraag. Er is momenteel geen eindpunt waar je je eigen SQL-query kunt indienen en een gegarandeerd, herhaalbaar resultaat kunt ontvangen. Andere bewoordingen kunnen andere queries en iets andere resultaten opleveren. Controleer de berekening voor belangrijke cijfers.

Een MCP-client kan eerder stoppen met wachten op een antwoord dan Composer zou doen. Claude heeft bijvoorbeeld een time-outvenster van 60 seconden. Als een vraag een time-out krijgt, beperk dan het datumbereik, verminder het aantal uitsplitsingen, of splits de analyse met een splitsing op in kleinere vragen.

Probleemoplossing

De analysetool is niet beschikbaar

Als je ask_analytics_question niet ziet in je AI-client, controleer dan of SQL is ingeschakeld voor je account en vernieuw de lijst met Klaviyo-tools van de client.

In Claude:

1. Ga naar Aanpassen > Connectors > Klaviyo.
2. Open het menu met de drie puntjes in de rechterbovenhoek.
3. Klik op Lijst met tools vernieuwen en probeer je vraag daarna opnieuw.

SQL kan geen data teruggeven waarvan je weet dat die in je account staat

Controleer of de dataset wordt ondersteund en houd rekening met de gebruikelijke vertraging van 30 minuten. Als je verbinding een API-sleutel gebruikt, controleer dan of die toegang heeft tot elke betrokken dataset, zoals profielen, segmenten, lijsten, campagnes, catalogi of events. Werk ontbrekende machtigingen bij in Klaviyo, ververs de Klaviyo-toollijst van de client en probeer de vraag opnieuw.

Voor een OAuth-verbinding bekijk je de machtigingen via de verbindingsgids van je klant.

Time-out voor vraag is verlopen

Probeer een korter datumbereik of minder uitsplitsingen, of splits de vraag op in kleinere vragen. Probeer de beperktere vraag opnieuw en bouw daarna voort op het resultaat met vervolgvragen.

Een nummer komt niet overeen met Klaviyo

Vraag hoe SQL het getal heeft berekend, inclusief de datasets, het datumbereik en de filters. Controleer of de definities van meetwaarden en de gegevensactualiteit het verschil verklaren. Als het verschil groot is, neem contact op met Klaviyo Support en deel de vraag, het teruggegeven getal en het getal dat je verwachtte.

Composer wijst een vraag af

Herschrijf de vraag met een specifieke meetwaarde, datumbereik en doelgroep. Controleer of het een van de ondersteunde datasets gebruikt en probeer het daarna opnieuw.

Extra hulpbronnen

• Aan de slag met Composer
• Klaviyo MCP-serverontwikkelaarsdocumentatie
• Klaviyo-app voor Claude: veelgestelde vragen
• Zo gebruik je de Klaviyo-app voor ChatGPT
• Klaviyo MCP-serverhandleiding voor bureaus
• Aan de slag met aangepaste rapporten in Klaviyo