ShopifyQL in Notebooks verwenden

ShopifyQL ist die Abfragesprache von Shopify für den Handel. Abfragesprachen werden verwendet, um Daten aus Datenbanken anzufragen und abzurufen. Du kannst ShopifyQL mit der Notebooks-App von Shopify verwenden, um deine eigene Unternehmensdatenbank zu erkunden und die Daten abzurufen, die dir dabei helfen, dein Unternehmen besser zu verstehen.

Eine vollständige Liste verfügbarer Werte und Maße, die in ShopifyQL-Notizbuch-Abfragen verwendet werden können, findest du im Bestellschema und im Produktschema.

ShopifyQL-Übersicht

Die Daten deines Shops werden in Datenbanktabellen gespeichert, die in festgelegte Spalten und Zeilen unterteilt sind. Spalten bestimmen die Art der enthaltenen Informationen, wie zum Beispiel Umsatz, und Zeilen legen den letztendlichen Wert des Datentyps fest, zum Beispiel 2.450 USD Umsatz.

Um deine Daten in einem sinnvollen Format abzurufen, muss eine Abfrage an die Datenbank gesendet werden. Eine Abfrage ist eine Frage, auf die bestimmte Daten als Antwort erwartet werden. Eine Abfragesprache wie ShopifyQL stellt eine standardisierte Art dar, diese Frage zu erstellen. Eine Abfrage besteht aus Keywords und deren entsprechenden Parametern. Aus der Kombination mehrerer Keywords mit bestimmten Parametern entsteht deine Abfrage. Sobald du deine Abfrage erstellt hast, kannst du sie ausführen und eine Antwort erhalten.

Dies ist ein Beispiel für einen ShopifyQL-Syntax, der als Abfrage formuliert ist. Die Keywords sind fett hervorgehoben und die entsprechenden Parameter befinden sich in Klammern. Die hier gezeigten Parameter sind Platzhalter:

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 }

Glossar der Begriffe

Definitionen zu ShopifyQL-Begriffen

Begriff	Definition
Maß	Ein Attribut, das Daten unterteilt, sodass sie sortiert und deutlicher wiedergegeben werden können. Häufige Beispiele für Dimensionen sind Zeit, Produkte und Orte. Dimensionen werden in ShopifyQL als Parameter verwendet.
Keyword	ShopifyQL-Syntax, der als Befehl fungiert, um deine Abfrage zu leiten.
Kennzahl	Eine quantitative Messung von Daten. Häufige Beispiele für Kennzahlen enthalten den Gesamtumsatz, die Anzahl an Bestellungen und den Bruttogewinn.
Parameter	ShopifyQL-Syntax, der die Datenbankelemente oder -details identifiziert, die Teil deiner Abfrage sein sollen.

Keyword-Referenztabelle

Dies sind die Keywords, die du zum Schreiben deiner Abfrage verwenden kannst:

Liste von ShopifyQL-Keywords

Keyword	Funktionale Nutzung
FROM	Legt fest, aus welcher Datensatztabelle die Daten ausgewählt werden.
SHOW	Wählt die Spalten aus, die du aus der Datensatztabelle extrahieren möchtest.
VISUALIZE	Zeigt deine Daten als Zeile oder Balken an.
GROUP BY	Gruppiert die extrahierten Daten anhand einer Dimension oder anhand von Zeitdimensionen.
WHERE	Legt die Bedingung(en) fest, die Zeilen erfüllen müssen, um ausgewählt zu werden.
SINCE	Zeigt Daten seit einem bestimmten Zeitpunkt in der Vergangenheit an.
UNTIL	Zeigt Daten bis zu einem bestimmten Zeitpunkt in der Vergangenheit an.
DURING	Zeigt Daten seit einem bestimmten Zeitpunkt in der Vergangenheit an.
COMPARE TO	Zeigt Daten bis zu einem bestimmten Zeitpunkt in der Vergangenheit an.
ORDER BY	Legt fest, nach welcher Spalte die Daten sortiert werden sollen.
LIMIT	Begrenzt die Anzahl an angezeigten Datenzeilen.
AS	Benennt eine Spalte in einen Namen deiner Wahl um.

ShopifyQL-Abfragen schreiben

ShopifyQL-Abfragen reichen von grundlegend, für Dateneinblicke auf hoher Ebene, bis umfassend, für detaillierte Einblicke. Jedes Keyword hat eine bestimmte Funktion, die deine Abfrage ausbaut.

ShopifyQL-Grundlagen: FROM und SHOW

Um die einfachste ShopifyQL-Abfrage zu erstellen, werden nur zwei Keywords benötigt: FROM und SHOW, in genau dieser Reihenfolge. FROM, gefolgt von einem Tabellennamenparameter, legt fest, welche Tabelle du abfragen möchtest. SHOW, gefolgt von einem Spaltennamenparameter, legt die Spalten fest, die du auswählen möchtest.

Du kannst beispielsweise alle Produkt-IDs und ihre entsprechenden Titel aus der Verkaufstabelle auflisten, indem du folgende Abfrage schreibst:

FROM products
  SHOW product_id, product_title

---

Daten gruppieren: GROUP BY

Um eine Kennzahl anhand einer Dimension zu unterteilen, z. B. zum Gruppieren von Verkäufen nach Region, verwende das Keyword GROUP BY. Das Keyword GROUP BY kann mit einem beliebigen Parameter des Typs "dimension" gekoppelt werden.

Eine Abfrage, die die Gesamtversandkosten nach Land und Region der Rechnungsadresse zusammenfasst, wird beispielsweise folgendermaßen geschrieben:

FROM orders
  SHOW shipping
  GROUP BY billing_country, billing_region

Hier ist ein weiteres Beispiel für eine Abfrage, die die zeitliche Dimension nutzt, um den Nettoumsatz nach Monat anzuzeigen:

FROM orders
  SHOW net_sales
  GROUP BY month

Die obenstehende Abfrage gibt keine Monate zurück, in denen keine Umsätze generiert wurden. Wenn du eine Abfrage ausführen möchtest, die einen vollständigen Zeitraum ohne Unterbrechungen zurückgibt, verwende den Modifizierer ALL:

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

Wenn du den Modifizierer ALL verwendest, musst du auch SINCE und UNTIL angeben. Beachte, dass der Modifizierer ALL nur mit einer Zeitdimension funktioniert.

Zeitliche Dimensionen

Das sind die zeitlichen Dimensionen, mit denen du deine Daten unterteilen kannst:

Zeitliche Dimensionen für ShopifyQL

Operator	Funktionale Nutzung
Stunden	Gruppieren nach Stunde des Kalendertags.
Tag	Nach Kalendertag zusammenfassen.
Woche	Nach Kalenderwoche zusammenfassen.
Monat	Nach Kalendermonat zusammenfassen.
quarter	Nach Kalenderquartal zusammenfassen.
Jahr	Nach Kalenderjahr zusammenfassen.
hour_of_day	Nach 24 Stunden zusammenfassen (1, 2, ..., 24).
day_of_week	Nach Wochentag zusammenfassen (M, D, M, ..., S).
week_of_year	Nach Jahreswoche zusammenfassen (1, 2, ..., 52).

---

Daten filtern: WHERE

Das Keyword WHERE ermöglicht dir, einen dimensionalen Filter auf eine ganze ShopifyQL-Abfrage anzuwenden.

Wenn du zum Beispiel möchtest, dass der nach Monat zusammengefasste Nettoumsatz ausschließlich für eine bestimmte Region zurückgegeben wird, sollte deine Abfrage folgendermaßen aussehen:

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

Wie du im obigen Beispiel sehen kannst, kannst du den Ergebnissatz mit dem WHERE-Parameter filtern, auch wenn der Parameter nicht in den Keywords SHOW oder GROUP BY enthalten ist. In diesem Fall wird nur der Nettoumsatz für Bestellungen mit einer Rechnungsadresse in Ohio über alle Monate gefiltert, auch wenn "billing_region" nicht im Ergebnissatz enthalten ist.

Vergleichsoperatoren

Das Keyword WHERE verwendet Vergleichsoperatoren, um Daten zu filtern. Im obigen Beispiel wurde "=" verwendet, um festzulegen, dass die Abfrage nach einem bestimmten Wert filtert. Jedoch stehen dir noch weitere Operatoren zur Verfügung:

Vergleichsoperatoren für ShopifyQL

Vergleichsoperator	Funktionale Nutzung
=	entspricht
!=	entspricht nicht
<	weniger als
>	größer als
<=	kleiner als oder gleich
>=	größer als oder gleich

Logische Operatoren

Um deine Daten gründlicher zu filtern, kannst du logische Operatoren zu deiner Abfrage hinzufügen. Die logischen Operatoren für ShopifyQL sind:

Logische Operatoren für ShopifyQL

Logischer Operator	Funktionale Nutzung
AND	Filtern, um alle Zeilen anzuzeigen, deren Bedingungen durch AND getrennt und erfüllt sind.
OR	Filtern, um alle Zeilen anzuzeigen, bei denen eine der durch OR getrennten Bedingungen erfüllt ist.
NOT	Filtern, um nur Zeilen anzuzeigen, deren Bedingungen nicht erfüllt sind, z. B. Zeilen, die den festgelegten Wert nicht enthalten.

Du kannst mehrere Filter mit dem Keyword WHERE verwenden, indem du logische Operatoren hinzufügst.

Mit der Ergänzung zur Beispiel-Datensatzabfrage, die eine monatliche Zusammenfassung des Nettoumsatzes für alle Bestellungen mit einer Rechnungsadresse in Ohio zurückgibt, sieht die Abfrage wie folgt aus:

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

---

Datumsbereiche: SINCE und UNTIL

Wenn du deine Abfrage nach einem Datum oder einem bestimmten Zeitraum filtern möchtest, kannst du die Keywords SINCE und UNTIL und die entsprechenden Parameter verwenden. Diese Keywords sind einzigartig, da sie nur Zeiträume filtern.

Dies ist ein Beispiel für eine Abfrage ab dem heutigen Datum, die den Nettoumsatz in Kanada der letzten 12 Monate zurückgibt:

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

Offset-Operatoren

Du kannst nach bestimmten Daten oder Daten-Offsets filtern. Die Offset-Operatoren für ShopifyQL sind:

Offset-Operatoren für ShopifyQL

Offset-Operatoren	Funktionale Nutzung
-{#}d	Anzahl an Tagen, die seit dem Tag vergangen sind, an dem die Abfrage ausgeführt wurde.
-{#}w	Anzahl an Wochen, die seit dem Tag vergangen sind, an dem die Abfrage ausgeführt wurde.
-{#}m	Anzahl an Monaten, die seit dem Tag vergangen sind, an dem die Abfrage ausgeführt wurde.
-{#}q	Anzahl an Quartalen, die seit dem Tag vergangen sind, an dem die Abfrage ausgeführt wurde.
-{#}y	Anzahl an Jahren, die seit dem Tag vergangen sind, an dem die Abfrage ausgeführt wurde.
tt-mm-jjjj	Ein bestimmtes Datum.
heute	Datum, an dem die Abfrage ausgeführt wurde.
gestern	Der vorherige 24-h-Zeitraum seit dem Zeitpunkt, zu dem die Abfrage ausgeführt wurde.

---

Nach Datumsbereichen filtern: DURING

Das Keyword DURING vereinfacht das Filtern nach Daten für Zeiträume. Du kannst das Keyword DURING verwenden, um die Abfrageergebnisse für einen bestimmten Zeitraum zu filtern, z. B. für ein Kalenderjahr oder einen bestimmten Monat. Du kannst es auch für Datumsbereiche verwenden, die jedes Jahr unterschiedliche Daten haben, z. B. Black Friday Cyber Monday. Beispiel:

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

DURING akzeptiert die folgenden benannten Operatoren für Zeiträume:

Benannte ShopifyQL-Operatoren für Zeiträume

Zeitraum-Operator	Funktionale Nutzung
heute	Das Datum, an dem die Abfrage ausgeführt wird
gestern	Der vorherige 24-Stunden-Zeitraum bis zum Zeitpunkt, an dem die Abfrage ausgeführt wurde
this_week	Die aktuelle Kalenderwoche
this_month	Der aktuelle Kalendermonat
this_quarter	Das aktuelle Kalenderquartal
this_year	Das aktuelle Kalenderjahr
last_week	Die vorherige Kalenderwoche
last_month	Der vorherige Kalendermonat
last_quarter	Das vorherige Kalenderquartal
last_year	Das vorherige Kalenderjahr
bfcm2022	25. November – 28. November 2022
bfcm2021	26. November – 29. November 2021

---

Verschiedene Datumsbereiche vergleichen: COMPARE TO

Mit dem Keyword COMPARE TO kannst du Daten in dem Zeitraum, den du für DURING angibst, mit Daten in dem Zeitraum vergleichen, den du für COMPARE TO angibst. Es akzeptiert alle im Abschnitt DURING aufgeführten benannten Operatoren für Zeiträume. Der für COMPARE TO verwendete Operator muss dieselbe Dauer angeben wie der für DURING verwendete Operator. Beispielsweise ist DURING this_week COMPARE TO last_week eine gültige Kombination, DURING this_week COMPARE TO last_month jedoch nicht.

Im folgenden Beispiel wird der Nettoumsatz während Black Friday Cyber Monday 2022 mit dem Nettoumsatz während Black Friday Cyber Monday 2021 verglichen.

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

---

Daten sortieren: ORDER BY

Mit dem Keyword ORDER BY und seinen Parametern kannst du festlegen, wie die von deiner Abfrage herausgegebenen Daten sortiert werden sollen: ASC für eine aufsteigende Reihenfolge und DESC für eine absteigende Reihenfolge.

Du kannst im Keyword ORDER BY beliebige Kennzahlen oder Dimensionen festlegen, die Teil deiner Abfrage sein sollen, einschließlich mehrerer Felder.

Diese Abfrage gibt beispielsweise den Nettoumsatz für jedes Land/jede Region der Rechnungsadresse sortiert in umgekehrter alphabetischer Reihenfolge nach Land der Rechnungsadresse und dann nach Region der Rechnungsadresse innerhalb der einzelnen Länder zurück.

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

Die Reihenfolge, in der du deine Kennzahlen und Dimension angibst, spielt eine Rolle. Wenn du mehrere Werte für ORDER BY angibst, wird die Sortierung auf jede Kennzahl oder Dimension in der angegebenen Reihenfolge angewendet.

---

Einschränkung: LIMIT

Mit dem Keyword LIMIT kannst du festlegen, wie viele Zeilen die Abfrage herausgeben soll. Dies ist nützlich, wenn du nur einen Blick auf die Daten in jeder Spalte werfen möchtest. In Kombination mit ORDER BY kannst du Listen erstellen, die die obersten und untersten Daten enthalten.

In diesem Beispiel werden LIMIT und ORDER BY verwendet, um eine Liste der 10 bestverkauften Produkte nach Menge der letzten 3 Monate zu erstellen:

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

---

Abfragen graphisch darstellen: VISUALIZE und TYPE

Mit dem Keyword VISUALIZE kannst du eine ShopifyQL-Abfrage schreiben, die Daten als Zeile oder Balken anzeigt.

Das Keyword TYPE ist optional und muss zusammen mit "line" oder "bar" verwendet werden, damit deine Abfrage eine Visualisierung in Form eines Linien- oder Balkendiagramms herausgibt. Wenn TYPE nicht Teil deiner Abfrage ist, entscheidet ShopifyQL automatisch, welche Visualisierung sich am besten für deine Abfrage eignet. Wenn deine Abfrage nicht geschrieben visualisiert werden kann, gibt ShopifyQL tabellarische Daten heraus.

Zum Beispiel kannst du deine Umsatzentwicklung im letzten Jahr nach Monat mit einer Trendlinie visualisieren. Diese Abfrage gibt ein Zeitdiagramm zurück, das den Bruttoumsatz nach Monat im letzten Jahr widerspiegelt. Der Bruttoumsatz wird als einzelne Linie dargestellt, wobei die X-Achse für die Monate und die Y-Achse für den Bruttoumsatz steht:

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

---

Mathematische Operatoren

ShopifyQL ermöglicht Rechenoperationen mit den Kennzahlen in deinen Daten. Die folgenden mathematischen Operatoren stehen zur Verfügung:

Offset-Operatoren für ShopifyQL

Mathematischer Operator	Funktionale Nutzung
+	Addition zweier Zahlen.
–	Subtraktion zweier Zahlen.
*	Multiplikation zweier Zahlen.
/	Division zweier Zahlen.

Diese Abfrage berechnet beispielsweise den Bestellwert für jede Region im letzten Jahr. Bei der Verwendung mathematischer Operatoren mit Kennzahlen kannst du das Keyword AS verwenden, um der neuen Kennzahl einen neuen Namen zuzuweisen.

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

---

Funktionen

ShopifyQL-Funktionen ermöglichen dir, Spalten zusammenzufassen, ähnlich wie bei Pivot-Tabellen in Microsoft Excel. Das Zusammenfassen von Spalten bedeutet, dass Spalten kombiniert werden, um einen neuen Wert zu erstellen. Die folgenden Funktionsoperatoren stehen in der aktuellen Version von ShopifyQL zur Verfügung:

Offset-Operatoren für ShopifyQL

Funktionsoperator	Funktionale Nutzung
count()	Anzahl der Instanzen im Ergebnissatz.
sum()	Summierung der Werte im Ergebnissatz.
min()	Mindestwert im Ergebnissatz.
max()	Maximalwert im Ergebnissatz.
avg()	Durchschnittlicher Wert im Ergebnissatz.

Die Funktionen sum, min, max und avg können nur mit numerischen Werten verwendet werden, während count zur Zählung verschiedener Instanzen dimensionaler Attribute verwendet werden kann. Du kannst zusammengefasste Felder nicht als Argumente in den Funktionen verwenden. Zusammengefasste Felder enden auf _sum, _count oder _percent.

Diese Abfrage gibt beispielsweise eine Fehlermeldung heraus, da total_sales bereits zusammengefasst wurde:

FROM orders
  SHOW sum(total_sales)

Nachfolgend siehst du eine Abfrage, die zusammengefasste Felder mit Zusammenfassungsfunktionen kombiniert:

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

Diese Abfrage gibt als Ergebnis der sum-Funktion die zusammengefasste Summe des durchschnittlichen Bestellwerts und die Summe des Bruttoumsatzes zurück. Diese Kennzahlen werden für alle im Jahr 2021 aufgegebenen Bestellungen nach Region der Rechnungsadresse aufgeschlüsselt.

---

Kommentare

Du kannst Kommentare verwenden, um Abschnitte mit ShopifyQL-Anweisungen zu erklären oder um die Ausführung einer ShopifyQL-Anweisung zu verhindern. Jeder Text innerhalb eines Kommentars wird während der Ausführung ignoriert.

Kommentare mit einer einzelnen Zeile beginnen mit -- und enden am Ende der Zeile.

Kommentare mit mehreren Zeilen beginnen mit /* und enden mit */.

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
*/