Utiliser ShopifyQL dans Notebooks

ShopifyQL est le langage de requête de Shopify conçu pour le commerce. Les langages de requête sont utilisés pour demander et récupérer des données dans les bases de données. Vous pouvez utiliser ShopifyQL avec l’application Carnets de Shopify pour explorer la base de données de votre entreprise et récupérer les données qui vous permettent d’acquérir une connaissance plus approfondie de votre entreprise.

Pour obtenir une liste complète des valeurs et dimensions qui peuvent être utilisées dans les requêtes de ShopifyQL Notebook, voir le schéma des commandes et le schéma des produits.

Sur cette page

Aperçu de ShopifyQL

Les données de votre boutique sont stockées dans des tables de base de données, structurées en colonnes et lignes définies. Les colonnes définissent le type d’informations qu’elles contiennent, telles que les ventes, et les lignes précisent la valeur réelle du type de données, par exemple 2 450 USD de ventes.

Pour récupérer vos données dans un format cohérent, vous devez soumettre une requête à la base de données. Une requête est une question qui demande une réponse sous forme de données spécifiques. Un langage de requête, comme ShopifyQL, est une façon standardisée de construire cette question. Une requête est composée de mots-clés et des paramètres correspondants à ces mots-clés. La combinaison de plusieurs mots-clés avec des paramètres spécifiques construit votre requête. Une fois votre requête conçue, vous pouvez l’exécuter et recevoir une réponse.

Voici un exemple de syntaxe ShopifyQL, écrit sous la forme d’une requête. Les mots–clés sont en gras, leurs paramètres correspondants sont entre accolades. Les paramètres indiqués ici sont des paramètres fictifs :

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 }

Glossaire de termes

Définitions des termes de ShopifyQL
Terme	Définition
Dimension	Un attribut qui segmente les données afin qu’elles puissent être triées et présentées plus clairement. Les exemples courants de dimensions comprennent l’heure, les produits et les lieux. Les dimensions sont utilisées comme paramètres dans ShopifyQL.
Mot-clé	Syntaxe ShopifyQL qui agit comme une commande pour diriger votre requête.
Indicateur	Une mesure quantitative de données. Les exemples courants d’indicateurs comprennent les ventes totales, le nombre de commandes et le bénéfice brut.
Paramètre	Syntaxe ShopifyQL qui identifie les éléments ou les détails de la base de données à inclure dans votre requête.

Tableau de référence des mots-clés

Voici les mots–clés que vous pouvez utiliser pour rédiger votre requête :

Liste des mots–clés ShopifyQL
Mot-clé	Utilisation fonctionnelle
FROM	Indique la table de données à partir de laquelle sélectionner les données.
SHOW	Sélectionne les colonnes que vous souhaitez extraire de la table de données.
VISUALIZE	Affiche vos données dans une visualisation en ligne ou à barres.
GROUP BY	Regroupe les données extraites par une dimension ou des dimensions temporelles.
WHERE	Définit la condition ou les conditions que les lignes doivent satisfaire pour être sélectionnées.
SINCE	Affiche les données depuis un moment spécifié dans le passé.
UNTIL	Affiche les données jusqu’à un moment spécifié dans le passé.
DURING	Affiche les données depuis un moment spécifié dans le passé.
COMPARE TO	Affiche les données jusqu’à un moment spécifié dans le passé.
ORDER BY	Indique par quelle colonne ordonner les données.
LIMIT	Limite le nombre de lignes de données affichées.
AS	Donne à une colonne le nom de votre choix.

Rédiger des requêtes ShopifyQL

Les requêtes ShopifyQL peuvent être basiques, pour des analyses de données globales, ou plus complexes, pour des analyses détaillées. Chaque mot–clé a une fonction spécifique permettant de construire votre requête.

Bases de ShopifyQL : FROM et SHOW

Pour créer la requête ShopifyQL la plus simple, deux mots–clés suffisent : FROM et SHOW, écrits dans cet ordre. FROM, suivi d’un paramètre de nom de table, indique la table que vous souhaitez interroger. SHOW, suivi d’un paramètre de nom de colonne, indique les colonnes que vous souhaitez sélectionner.

Par exemple, vous pouvez lister tous les ID de produits et leurs titres correspondants dans le tableau des ventes en rédigeant cette requête :

FROM products
  SHOW product_id, product_title

Données de regroupement : GROUP BY

Pour segmenter un indicateur par une dimension, par exemple pour regrouper les ventes par région, utilisez le mot-clé « GROUP BY » (grouper par). Le mot-clé GROUP BY peut être associé à n’importe quel paramètre de dimension.

Par exemple, une requête qui regroupe les frais d’expédition totaux par pays et région de facturation est écrite ainsi :

FROM orders
  SHOW shipping
  GROUP BY billing_country, billing_region

Voici un autre exemple de requête qui utilise une dimension de temps pour afficher les ventes nettes par mois :

FROM orders
  SHOW net_sales
  GROUP BY month

La requête ci-dessus ne renvoie aucun mois là où vous n’avez aucune vente. Si vous souhaitez qu’une requête renvoie une période complète et ininterrompue, utilisez le modificateur ALL :

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

Lorsque vous utilisez le modificateur ALL (tout), vous devez également spécifier SINCE (depuis) et UNTIL (jusqu'à). Notez que le modificateur ALL (tout) ne fonctionne qu’avec une dimension temporelle.

Dimensions temporelles

Voici les dimensions de temps que vous pouvez utiliser pour regrouper vos données :

Dimensions de temps de ShopifyQL
Opérateur	Utilisation fonctionnelle
heure	Regroupement par heure de jour civil.
jour	Regroupement par jour civil.
semaine	Regroupement par semaine civile.
mois	Regroupement par mois civil.
quarter	Regroupement par trimestre civil.
année	Regroupement par année civile.
hour_of_day	Regroupement par 24 heures (1,2,...,24).
day_of_week	Regroupement par jour de la semaine (M, T,W,...,S).
week_of_year	Regroupement par semaine de l’année (1,2,...,52).

Filtrage des données : WHERE

Le mot–clé WHERE vous permet d’appliquer un filtre dimensionnel à l’ensemble d’une requête ShopifyQL.

Par exemple, si vous souhaitez renvoyer les ventes nettes, regroupées par mois, mais uniquement pour une région spécifique, votre requête est :

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

Comme vous pouvez le voir dans l’exemple ci-dessus, vous pouvez filtrer l’ensemble de résultats avec le paramètre WHERE, même si ce paramètre n’est pas inclus dans les mots-clés SHOW ou GROUP BY. Dans ce cas, les ventes nettes sont filtrées sur tous les mois pour les commandes dont l’adresse de facturation se trouve uniquement en Ohio, même si billing_region n’est pas inclus dans l’ensemble de résultats.

Opérateurs de comparaison

Le mot–clé WHERE utilise des opérateurs de comparaison pour filtrer les données. Dans l’exemple ci–dessus, « = » a été utilisé pour spécifier que la requête filtre selon une valeur spécifique. Cependant, d’autres opérateurs sont à votre disposition :

Opérateurs de comparaison de ShopifyQL
Opérateur de comparaison	Utilisation fonctionnelle
=	:
!=	n'est pas
<	est inférieur(e) à
>	est supérieur(e) à
<=	est inférieur(e) ou égal(e) à
>=	est supérieur(e) ou égal(e) à

Opérateurs logiques

Pour filtrer davantage vos données, vous pouvez ajouter des opérateurs logiques à votre requête. Les opérateurs logiques de ShopifyQL sont les suivants :

Opérateurs logiques de ShopifyQL
Opérateur logique	Utilisation fonctionnelle
AND	Filtre pour afficher toutes les lignes où les conditions séparées par AND sont remplies.
OR	Filtre pour afficher toutes les lignes où l’une des conditions séparées par OR est remplie.
NOT	Filtre pour afficher uniquement les lignes où les conditions ne sont pas remplies, par exemple les lignes qui ne contiennent pas la valeur spécifiée.

Vous pouvez utiliser plusieurs filtres avec le mot–clé WHERE en ajoutant des opérateurs logiques.

En ajoutant à l’exemple de requête de jeu de données, pour obtenir un regroupement mensuel des ventes nettes pour toutes les commandes où l’adresse de facturation se trouvait en Ohio et où une réduction a été appliquée, la requête est :

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

Plages de dates : SINCE et UNTIL

Si vous souhaitez filtrer votre requête par date ou par période, vous pouvez utiliser les mots–clés SINCE et UNTIL ainsi que leurs paramètres associés. Ces mots-clés sont uniques, car ils ne filtrent que les périodes.

Par exemple, voici une requête pour trouver les ventes nettes au cours des 12 derniers mois, au Canada, à partir d’aujourd’hui :

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

Opérateurs de compensation

Vous pouvez filtrer par dates spécifiques ou par décalages de date. Les opérateurs de compensation de ShopifyQL sont les suivants :

Opérateurs de compensation de ShopifyQL
Opérateur de compensation	Utilisation fonctionnelle
-{#}d	Nombre de jours passés depuis le jour d’exécution de la requête.
-{#}w	Nombre de semaines passées depuis le jour d’exécution de la requête.
-{#}m	Nombre de mois passés depuis le jour d’exécution de la requête.
-{#}q	Nombre de trimestres passés depuis le jour d’exécution de la requête.
-{#}y	Nombre d’années passées depuis le jour d’exécution de la requête.
aaaa-mm-jj	Une date spécifique.
aujourd'hui	Date d’exécution de la requête.
yesterday	La période de 24 heures précédant le moment où la requête est exécutée.

Filtrage des plages de dates : DURING

Le mot-clé « DURING » simplifie le filtrage des dates pour les plages de dates. Vous pouvez utiliser le mot-clé « DURING » pour filtrer les résultats des requêtes pour une période connue, telle qu’une année civile ou un mois spécifique, ou pour des plages de dates différentes chaque année, telles que les Black Friday Cyber Monday. Par exemple :

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

DURING accepte l’un des opérateurs de plages de dates nommés suivants :

Opérateurs de plages de dates nommés ShopifyQL
Opérateur de plage de dates	Utilisation fonctionnelle
aujourd'hui	La date d’exécution de la requête.
yesterday	La période de 24 heures précédant le moment où la requête est exécutée.
this_week	La semaine civile en cours.
this_month	Le mois civil en cours.
this_quarter	Le trimestre civil en cours.
this_year	L’année civile en cours.
last_week	La semaine civile précédente.
last_month	Le mois civil précédent.
last_quarter	Le trimestre civil précédent.
last_year	L’année civile précédente.
bfcm2022	Du 25 novembre au 28 novembre 2022.
bfcm2021	Du 26 novembre au 29 novembre 2021.

Comparaison de plages de dates : COMPARE TO

Le mot-clé « COMPARE TO » vous permet de comparer les données entre la plage de dates « DURING » et celle « COMPARE TO ». Il accepte tous les opérateurs de plages de dates nommés qui sont répertoriés dans la section DURING. L’opérateur utilisé par « COMPARE TO » doit avoir la même durée que celui utilisé par « DURING ». Par exemple, DURING this_week COMPARE TO last_week est une combinaison valide, mais DURING this_week COMPARE TO last_month ne l’est pas.

L’exemple suivant compare les ventes nettes pendant le Black Friday Cyber Monday 2022 à celles du Black Friday Cyber Monday 2021.

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

Tri des données : ORDER BY

Vous pouvez spécifier comment vous souhaitez trier les données renvoyées par votre requête à l’aide du mot-clé ORDER BY et de ses paramètres : ASC, pour l’ordre croissant et DESC pour l'ordre décroissant.

Vous pouvez spécifier n’importe quel indicateur ou dimension inclus dans votre requête dans le mot-clé ORDER BY, y compris plusieurs champs.

Par exemple, cette requête renvoie les ventes nettes pour chaque pays et région de facturation, triés dans l’ordre alphabétique inverse par pays de facturation, puis par région de facturation dans chaque pays.

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

L’ordre dans lequel vous rédigez vos indicateurs ou vos dimensions est important. Si vous spécifiez plusieurs valeurs pour ORDER BY, le tri est appliqué à chaque indicateur ou dimension de la commande donnée.

Limite du nombre de lignes : LIMIT

Le mot–clé LIMIT vous permet de choisir le nombre de lignes que renvoie la requête. Cette information est utile lorsque vous souhaitez simplement avoir une idée de l’apparence des données dans chaque colonne. Ou encore, vous pouvez l’associer à ORDER BY pour créer des listes ordonnées.

Cet exemple utilise LIMIT et ORDER BY pour créer une liste des 10 produits les plus vendus par quantité au cours des 3 derniers mois :

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

Présentation de vos requêtes sous forme de graphiques : VISUALIZE et TYPE

Le mot–clé VISUALIZE vous permet d’écrire une requête ShopifyQL qui affiche les données dans une visualisation en ligne ou à barres.

Le mot–clé TYPE est facultatif et doit être accompagné de « line » ou de « bar » pour que votre requête renvoie une visualisation dans un graphique en ligne ou un graphique à barres, respectivement. Si TYPE n’est pas inclus dans votre requête, ShopifyQL choisit automatiquement la visualisation la plus adaptée pour votre requête. Si votre requête ne peut pas être visualisée telle qu'elle est écrite, ShopifyQL renvoie les données tabulaires.

Par exemple, vous pouvez visualiser la tendance de vos ventes au cours de l’année écoulée par mois à l’aide d’une courbe de tendance. Cette requête renvoie un tableau de séries chronologiques affichant les ventes brutes par mois au cours de l’année écoulée. Les ventes brutes sont représentées par une seule courbe, avec l’axe des abscisses pour le mois et l’axe des ordonnées pour les ventes brutes :

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

Opérateurs mathématiques

ShopifyQL autorise les opérations arithmétiques avec les indicateurs de vos données. Les opérateurs mathématiques suivants sont disponibles :

Opérateurs de compensation de ShopifyQL
Opérateur mathématique	Utilisation fonctionnelle
+	Addition de deux nombres.
-	Soustraction de deux nombres.
*	Multiplication de deux nmbres.
/	Division de deux nombres.

Par exemple, cette requête calcule la valeur des commandes pour chaque région au cours de l’année écoulée. Lorsque vous utilisez des opérateurs mathématiques avec des indicateurs, vous pouvez utiliser le mot-clé AS pour attribuer un nouveau nom au nouvel indicateur.

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

Fonctions

Les fonctions de ShopifyQL vous permettent d’agréger des colonnes, comme dans les tableaux croisés dynamiques de Microsoft Excel. Agréger des colonnes revient à les combiner pour créer une nouvelle valeur. Les opérateurs de fonction suivants sont disponibles dans la version actuelle de ShopifyQL :

Opérateurs de compensation de ShopifyQL
Opérateur de fonction	Utilisation fonctionnelle
quantité()	Nombre d’instances dans l'ensemble de résultats.
somme()	Somme des valeurs dans l'ensemble de résultats.
min()	Valeur minimale dans l'ensemble de résultats.
max()	Valeur maximum dans l’ensemble de résultats.
moy()	Valeur moyenne du résultat définie.

Les fonctions sum, min, max et avg ne peuvent être utilisées qu’avec des valeurs numériques tandis que count peut être utilisée pour compter différents cas d’attributs dimensionnels. Vous ne pouvez pas utiliser les champs agrégés comme arguments dans les fonctions. Les champs agrégés se terminent par _sum, _count ou par _percent.

Par exemple, cette requête renvoie une erreur puisque total_sales a déjà été agrégé :

FROM orders
  SHOW sum(total_sales)

Voici une requête valide qui associe des champs agrégés et des fonctions agrégées :

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

Cette requête renvoie la somme agrégée de la valeur moyenne du panier, la somme de ventes brutes grâce à la fonction sum. Ces indicateurs sont divisés par région de facturation pour toutes les commandes passées en 2021.

Commentaires

Vous pouvez utiliser les commentaires pour expliquer des sections des énoncés ShopifyQL ou empêcher l’exécution d’un relevé ShopifyQL. Tout texte d’un commentaire sera ignoré pendant la durée d’exécution.

Les commentaires d’une seule ligne commencent avec -- et se terminent à la fin de la ligne.

Les commentaires multi-lignes commencent par /* et se terminent avec */.

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