ShopifyQL gebruiken in Notebooks

ShopifyQL is de querytaal van Shopify die speciaal voor commerce is ontwikkeld. Querytalen worden gebruikt om gegevens van de organisatie aan te vragen en op te halen. Je kunt ShopifyQL gebruiken met de Notebooks-app van Shopify om de database van je eigen bedrijf te verkennen en de gegevens op te halen die je een diepgaander inzicht geven in je bedrijf.

Zie het Bestellingenschema en het Productenschema voor een volledige lijst met beschikbare waarden en dimensies die je kunt gebruiken in ShopifyQL Notebook-query's.

ShopifyQL-overzicht

De gegevens van je winkel worden opgeslagen in databasetabellen, gestructureerd in gedefinieerde kolommen en rijen. Kolommen definiëren het type gegevens dat ze bevatten, zoals verkopen, en rijen de werkelijke waarde van het gegevenstype, zoals 2.450 USD aan verkopen.

Dien een query in bij de database om je gegevens in een zinvolle indeling op te halen. Een query is een vraag die om specifieke gegevens vraagt als antwoord. Een querytaal, zoals ShopifyQL, is een standaardmanier om die vraag op te stellen. Een query wordt gemaakt van trefwoorden en de bijbehorende parameters. Aan de hand van de combinatie van verschillende trefwoorden met specifieke parameters wordt de query opgebouwd. Nadat je de query hebt opgebouwd, kun je deze uitvoeren en een antwoord ontvangen.

Dit is een voorbeeld van de ShopifyQL-syntaxis, die als een query is uitgeschreven. De trefwoorden zijn vetgedrukt, de bijbehorende parameters staan tussen haakjes. De parameters die hier worden weergegeven, zijn tijdelijke aanduidingen:

FROM { table_name }
  SHOW { column1, column2, ... }
  GROUP BY { dimension | date_group }
  WHERE { condition }
  SINCE { date_offset }
  UNTIL { date_offset }
  ORDER BY { column } DESC
  LIMIT { count }

Termenlijst

Definities van ShopifyQL-voorwaarden

Term	Definitie
Afmetingen	Een attribuut dat gegevens segmenteert, zodat deze duidelijker kunnen worden gesorteerd en gepresenteerd. Veelvoorkomende voorbeelden van dimensies zijn tijd, producten en plaatsen. Afmetingen worden gebruikt als parameters in ShopifyQL.
Trefwoord	ShopifyQL-syntaxis die fungeert als een opdracht om je query te sturen.
Statistiek	Een afmeting van gegevens. Veelvoorkomende voorbeelden van statistieken zijn de totale verkoop, het aantal bestellingen en de brutowinst.
Parameter	ShopifyQL-syntaxis die de database-elementen of -gegevens identificeert die in je zoekopdracht moeten worden opgenomen.

Referentietabel met trefwoorden

Dit zijn de trefwoorden die je kunt gebruiken om je query te schrijven:

Lijst met ShopifyQL-trefwoorden

Trefwoord	Functioneel gebruik
FROM	Geeft aan uit welke datasettabel gegevens moeten worden geselecteerd.
SHOW	Selecteert de kolommen die je uit de datasettabel wilt extraheren.
VISUALIZE	Geeft je gegevens weer in een regel of balk.
GROUP BY	Groepeert de opgehaalde gegevens op een dimensie of op tijdsdimensies.
WAAR	Definieert de voorwaarde of voorwaarden waar rijen aan moeten voldoen om te worden geselecteerd.
SINCE	Toont gegevens vanaf een gespecificeerd moment in het verleden.
UNTIL	Toont gegevens tot een bepaalde tijd in het verleden.
DURING	Toont gegevens vanaf een gespecificeerd moment in het verleden.
COMPARE TO	Toont gegevens tot een bepaalde tijd in het verleden.
ORDER BY	Specificeert op welke kolom de gegevens moeten worden gesorteerd.
LIMIT	Beperkt het aantal rijen gegevens dat wordt weergegeven.
AS	Geeft een kolom een andere, door jou gekozen naam.

ShopifyQL-query's schrijven

ShopifyQL-query's kunnen variëren van basisvragen, voor hoogwaardige gegevensinzichten, tot uitgebreide, voor gedetailleerde inzichten. Elk trefwoord heeft een specifieke functie die je zoekopdracht opbouwt.

ShopifyQL-basisinformatie: FROM en SHOW

Voor het maken van de eenvoudigste ShopifyQL-query zijn slechts twee trefwoorden nodig: FROM en SHOW, geschreven in die volgorde. FROM, gevolgd door een tabelnaamparameter geeft aan welke tabel je wilt opvragen. SHOW, gevolgd door een kolomnaamparameter, geeft de kolommen op die je wilt selecteren.

Je kunt bijvoorbeeld alle product-ID's en de bijbehorende titels uit de verkooptabel gebruiken door deze query te schrijven:

FROM products
  SHOW product_id, product_title

---

Gegevens groeperen: GROUP BY

Gebruik het trefwoord GROUP BY als je een statistiek wilt segmenteren op een dimensie, zoals groepsverkopen per regio. Je kunt het trefwoord GROUP BY koppelen aan elke gewenste dimensieparameter.

Een query die de totale verzendprijzen per land en regio voor factuur groepeert, wordt bijvoorbeeld geschreven als:

FROM orders
  SHOW shipping
  GROUP BY billing_country, billing_region

Dit is een ander voorbeeld van een query met een tijddimensie om de netto-omzet per maand weer te geven:

FROM orders
  SHOW net_sales
  GROUP BY month

De bovenstaande query levert geen resultaat op voor maanden waarin je geen omzet hebt. Gebruik de parameter ALL als je een query wilt die een volledige, ononderbroken periode als resultaat geeft:

FROM orders
  SHOW net_sales
  GROUP BY month ALL
  SINCE last_year
  UNTIL today

Wanneer je de parameter ALL gebruikt, geef je ook SINCE en UNTIL op. Let op: de parameter ALL werkt alleen met een tijdsdimensie.

Tijdsdimensies

Dit zijn de tijdsafmetingen die je kunt gebruiken om je gegevens te groepeert:

ShopifyQL-tijdafmetingen

Operator	Functioneel gebruik
uur	Groeperen op uur van kalenderdag.
dag	Groeperen op kalenderdag.
week	Groeperen op kalenderweek.
maand	Groeperen op kalendermaand.
quarter	Groeperen op kalenderkwartaal.
jaar	Groeperen op kalenderjaar.
hour_of_day	Groeperen op 24 uur (1,2,...,24).
day_of_week	Groeperen op dag van de week (M,D,W,...,Z).
week_of_year	Groeperen op week van het jaar (1,2,...,52).

---

Gegevens filteren: WHERE

Met het trefwoord WHERE kun je een dimensiefilter toepassen op een volledige ShopifyQL-query.

Als je bijvoorbeeld de netto-omzet, gegroepeerd op maand, maar alleen voor een specifieke regio wilt retourneren, is de query:

FROM orders
  SHOW net_sales
  GROUP BY month ALL
  WHERE billing_region = 'ohio'
  SINCE last_year
  UNTIL today

In het bovenstaande voorbeeld zie je dat je de resultatenset kunt filteren met de parameter WHERE, zelfs als die parameter niet is opgenomen in de trefwoorden SHOW of GROUP BY. In dit geval wordt de netto-omzet over alle maanden gefilterd op alleen bestellingen met een factuuradres in Ohio, ook al is billing_region niet is opgenomen in de resultatenset.

Vergelijkingsoperators

Het trefwoord WHERE maakt gebruik van vergelijkingsoperators om gegevens te filteren. In het bovenstaande voorbeeld is '=' gebruikt om op te geven dat de queryfilters op een specifieke waarde worden gefilterd, maar er staan andere operators tot je beschikking:

ShopifyQL-vergelijkingsoperators

Vergelijkingsoperator	Functioneel gebruik
=	gelijk aan
!=	niet gelijk aan
<	kleiner dan
>	groter dan
<=	kleiner dan of gelijk aan
>=	groter dan of gelijk aan

Logistieke operators

Om je gegevens verder te filteren, kun je logische operators aan je zoekopdracht toevoegen. De logische operators van ShopifyQL zijn:

Logische operators voor ShopifyQL

Logische operator	Functioneel gebruik
EN	Filter om alle rijen weer te geven die aan de door AND gescheiden voorwaarden voldoen.
OF	Filter om alle rijen weer te geven die aan een van de door OR gescheiden voorwaarden voldoen.
NIET	Filter om alleen rijen weer te geven die niet aan de voorwaarden voldoen, zoals rijen die de opgegeven waarde niet bevatten.

Je kunt meerdere filters gebruiken met het trefwoord WHERE door logische operators toe te voegen.

Als extra toevoeging aan de voorbeeldquery van een dataset: de query om een maandelijks overzicht te krijgen van de netto-omzet voor alle bestellingen met een factuuradres in Ohio en een toegepaste korting, is:

FROM orders
  SHOW net_sales
  GROUP BY month ALL
  WHERE billing_region = 'ohio' AND discounts > 0
  SINCE last_year
  UNTIL today

---

Datumbereiken: SINCE en UNTIL

Als je je query wilt filteren op een datum of bepaalde periode, kun je de trefwoorden SINCE en UNTIL en de bijbehorende parameters gebruiken. Deze trefwoorden zijn uniek omdat ze alleen tijdsperioden filteren.

Dit is bijvoorbeeld een query om de netto-omzet van de afgelopen 12 maanden in Canada te vinden, beginnend bij vandaag:

FROM orders
  SHOW net_sales
  GROUP BY month ALL
  WHERE billing_country = 'Canada'
  SINCE -12m
  UNTIL today

Offset-operators

Je kunt filteren op specifieke datums of op datumcompensaties. De offset-operators van ShopifyQL zijn:

Offset-operators van ShopifyQL

Offset-operator	Functioneel gebruik
-{#}d	Aantal dagen geleden dat de query werd uitgevoerd.
-{#}w	Aantal weken sinds de aanvraag is gedaan.
-{#}m	Aantal maanden sinds de aanvraag is gedaan.
-{#}q	Aantal kwartalen sinds de aanvraag is gedaan.
-{#}y	Aantal jaren sinds de aanvraag is gedaan.
jjjj-mm-dd	Een specifieke datum.
vandaag	Datum waarop de query wordt uitgevoerd.
gisteren	De afgelopen 24 uur vanaf het moment dat de query werd uitgevoerd.

---

Filteren op datumbereik: DURING

Met het trefwoord DURING vereenvoudig je het filteren op datumbereik. Je kunt het trefwoord DURING gebruiken om de queryresultaten te filteren voor een bekende periode, zoals een kalenderjaar of specifieke maand, of voor een datumbereik dat elk jaar op een andere datum valt, zoals Black Friday Cyber Monday. Bijvoorbeeld:

FROM orders
  SHOW sum(net_sales)
  GROUP BY day ALL
  DURING bfcm2021

Bij DURING worden de volgende operatoren voor het datumbereik geaccepteerd:

Genoemde ShopifyQL-datumbereikoperators

Operator datumbereik	Functioneel gebruik
vandaag	De datum waarop de query wordt uitgevoerd.
gisteren	De afgelopen 24 uur vanaf het moment dat de query werd uitgevoerd.
this_week	De huidige kalenderweek.
this_month	De huidige kalendermaand.
this_quarter	Het huidige kalenderkwartaal.
this_year	Het huidige kalenderjaar.
last_week	De vorige kalenderweek.
last_month	De vorige kalendermaand.
last_quarter	Het vorige kalenderkwartaal.
last_year	Het vorige kalenderjaar.
bfcm2022	25 november t/m 28 november 2022.
bfcm2021	26 november t/m 29 november 2021.

---

Verschillende datumbereiken vergelijken: COMPARE TO

Met het trefwoord COMPARE TO kun je gegevens vergelijken tussen de datumbereiken in DURING en in COMPARE TO. Bij COMPARE TO worden elk van de genoemde datumbereikoperators in de sectie DURING geaccepteerd. Het werkt alleen als de operator voor COMPARE dezelfde tijdsduur heeft als de operator voor DURING. DURING this_week COMPARE TO last_week bijvoorbeeld is een geldige combinatie, maar DURING this_week COMPARE TO last_month is dat niet.

In het volgende voorbeeld vergelijken we de netto-omzet van Black Friday Cyber Monday 2022 met die van 2021.

FROM orders
  SHOW sum(net_sales)
  GROUP BY day ALL
  DURING bfcm2022
  COMPARE TO bfcm2021

---

Gegevens sorteren: ORDER BY

Je kunt opgeven hoe je de gegevens wilt sorteren die door je query worden opgehaald met behulp van het trefwoord ORDER BY en de parameters ervan: ASC, voor oplopende volgorde en DESC voor aflopende volgorde.

Je kunt elke statistiek of afmeting uit je query specificeren in het trefwoord ORDER BY, inclusief meerdere velden.

Met deze query wordt bijvoorbeeld de netto-omzet geretourneerd voor elk land voor factuur en elke regio voor factuur, gesorteerd in omgekeerde alfabetische volgorde op land voor factuur en vervolgens op regio voor factuur binnen elk land.

FROM orders
  SHOW net_sales
  GROUP BY billing_country, billing_region
  SINCE -1y
  UNTIL today
  ORDER BY billing_country, billing_region DESC

De volgorde waarin je de statistieken of dimensie schrijft, is belangrijk. Als je meerdere waarden opgeeft voor ORDER BY, wordt de sortering toegepast op elke statistiek of dimensie in de opgegeven volgorde.

---

Limiet

Met het trefwoord LIMIT kun je opgeven hoeveel rijen de query retourneert. Dit is handig wanneer je gewoon wilt zien hoe de data in elke kolom eruitzien. Of je kunt het combineren met ORDER BY om boven- en onderlijsten te maken.

In dit voorbeeld worden LIMIT en ORDER BY gebruikt om een lijst te maken met de tien best verkochte producten naar hoeveelheid van de afgelopen drie maanden:

FROM products
  SHOW net_product_quantity
  GROUP BY product_title
  SINCE -3m
  UNTIL today
  ORDER BY net_product_quantity DESC
  LIMIT 10

---

Query's in kaart brengen: VISUALIZE en TYPE

Met het trefwoord VISUALIZE kun je een ShopifyQL-query schrijven die gegevens in een regel of balk laat zien.

Het trefwoord TYPE is optioneel en moet worden vergezeld door 'regel' of 'balk', zodat je query een trefwoord oplevert in een regeltabel of staaftabel. Als TYPE niet in je query is opgenomen, bepaalt ShopifyQL automatisch welke visualisering het beste bij je query past. Als je query niet kan worden gevisualiseerd als geschreven, retourneert ShopifyQL tabelgegevens.

Je kunt bijvoorbeeld je verkooptrend van het afgelopen jaar per maand visualiseren met een trendlijn. Met deze query wordt een grafiek geretourneerd uit de tijdreeks die de bruto-omzet per maand van het afgelopen jaar weergeeft. De bruto-omzet wordt weergegeven door een enkele lijn, met de x-as als maand en de y-as als bruto-omzet:

FROM orders
  VISUALIZE gross_sales
  TYPE line
  GROUP BY month ALL
  SINCE -1y
  UNTIL today

---

Wiskundige operators

ShopifyQL maakt het mogelijk om gebruik te maken van metrische gegevens. Er zijn de volgende operators beschikbaar voor zelfoperators:

Offset-operators van ShopifyQL

Wiskundige operator	Functioneel gebruik
+	Toevoeging van twee cijfers.
-	Aftrekking van twee getallen.
*	Vermenigvuldiging van twee cijfers.
/	Deling van twee cijfers.

Deze query berekent bijvoorbeeld de bestelwaarde van elke regio van het afgelopen jaar. Wanneer je gebruikmaakt van operators met statistieken, kun je het trefwoord AS gebruiken om een nieuwe naam toe te wijzen aan de nieuwe statistiek.

FROM orders
  SHOW (net_sales + returns) AS order_value, orders, (net_sales + returns)/orders AS sales_per_order
  GROUP BY billing_region
  SINCE -1y
  UNTIL today

---

Functies

Met ShopifyQL-functies kun je kolommen verzamelen die lijken op draaitabellen in Microsoft Excel. Samenvoeging van kolommen betekent dat je ze combineert om een nieuwe waarde te creëren. De volgende functie-operators zijn beschikbaar in de huidige versie van ShopifyQL:

Offset-operators van ShopifyQL

Functie-operator	Functioneel gebruik
aantal()	Aantal gevallen in resultatenset.
som()	Som van waarden in resultatenset.
min()	Minimale waarde in resultatenset.
max()	Maximale waarde in resultatenset.
gem()	Gemiddelde waarde in resultatenset.

De functies sum, min, max en avg kunnen alleen worden gebruikt met numerieke waarden, terwijl count kan worden gebruikt om verschillende gevallen van dimensionale attributen te tellen. Je kunt samengestelde velden niet gebruiken als argumenten in de functies. Samengestelde velden eindigen op _sum, _count of _percent.

Deze query geeft bijvoorbeeld een fout aangezien total_sales al is samengesteld:

FROM orders
  SHOW sum(total_sales)

Hier is een geldige query die samengestelde velden mengt met samengestelde functies:

FROM orders
  SHOW average_order_value, sum(gross_sales)
  GROUP BY billing_region
  SINCE 2021-01-01
  UNTIL 2021-12-31

Met deze query wordt de samengestelde som geretourneerd van de gemiddelde orderwaarde en de som van de bruto-omzet als gevolg van de functie sum. Deze statistieken worden uitgesplitst per regio voor factuur voor alle bestellingen die in 2021 zijn geplaatst.

---

Reacties

Je kunt opmerkingen gebruiken om secties van ShopifyQL-overzichten uit te leggen of om de uitvoering van een ShopifyQL-overzicht te voorkomen. De tekst van een opmerking wordt tijdens de uitvoering genegeerd.

Opmerkingen op een regel beginnen met -- en eindigen na de regel.

Opmerkingen op meerdere regels beginnen met /* en eindigen met */.

FROM orders
  SHOW average_order_value, sum(gross_sales)
  -- the line below has been commented out and will not run
  -- GROUP BY billing_region
  WHERE billing_country = 'United States'
  /*
  this line and the two lines below it have been commented out and will not run
  SINCE 2021-01-01
  UNTIL 2021-12-31
*/