Uso di ShopifyQL su Notebooks

Questa pagina è stata stampata il Apr 18, 2024. Per la versione aggiornata, visita https://help.shopify.com/it/manual/reports-and-analytics/shopifyql-notebooks/using-shopifyql-for-notebooks.

ShopifyQL è il linguaggio di query di Shopify creato per il commercio. I linguaggi di query vengono utilizzati per richiedere e recuperare dati dai database. Puoi utilizzare ShopifyQL con l'app Notebooks di Shopify per esplorare il database del tuo negozio e recuperare i dati in grado di offrirti una conoscenza più approfondita della tua attività.

Per un elenco completo dei valori e delle dimensioni disponibili da poter utilizzare nelle query di ShopifyQL Notebook, consulta Orders schema (Schema ordini) e Products schema (Schema prodotti).

Su questa pagina

Panoramica di ShopifyQL

I dati del tuo negozio sono memorizzati in tabelle di database strutturate in colonne e righe definite. Le colonne definiscono il tipo di informazioni che contengono, ad esempio le vendite, mentre le righe specificano il valore effettivo del tipo di dati, ad esempio 2.450 USD di vendite.

Per recuperare i dati in un formato utilizzabile, è necessario inviare una query al database. Una query è una domanda che richiede dati specifici come risposta. Un linguaggio di query, come ShopifyQL, rappresenta un modo standard per dare forma a questa domanda. Una query è composta da parole chiave e dai parametri corrispondenti. La combinazione di diverse parole chiave con parametri specifici compone la query, che può quindi essere eseguita per ricevere una risposta.

Questo è un esempio di sintassi ShopifyQL, scritta in forma di query. Le parole chiave sono in grassetto, i parametri corrispondenti sono tra parentesi. I parametri mostrati di seguito sono dei segnaposto:

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 }

Glossario dei termini

Definizioni dei termini di ShopifyQL
Termine Definizione
Dimensione Attributo che segmenta i dati in modo che possano essere ordinati e presentati con maggiore chiarezza. Esempi comuni di dimensioni includono tempo, prodotti e luoghi. Le dimensioni vengono utilizzate come parametri di ShopifyQL.
Parola chiave Sintassi di ShopifyQL che agisce come comando per indirizzare la query.
Metrica Misurazione quantitativa dei dati. Esempi comuni di metriche includono le vendite totali, il numero di ordini e il profitto lordo.
Parametro Sintassi di ShopifyQL che identifica gli elementi o i dati del database da includere nella query.

Tabella di riferimento per le parole chiave

Di seguito sono elencate le parole chiave che puoi utilizzare per scrivere una query:

Elenco delle parole chiave di ShopifyQL
Parola chiave Uso funzionale
FROM Specifica la tabella di set di dati da cui selezionare i dati.
SHOW Seleziona le colonne che desideri estrarre dalla tabella di set di dati.
VISUALIZE Mostra i dati in una visualizzazione a linee o a barre.
GROUP BY Raggruppa i dati estratti in base a una dimensione o a dimensioni di tempo.
WHERE Definisce la condizione o le condizioni che le righe devono soddisfare per poter essere selezionate.
SINCE Mostra i dati a partire da un momento specifico del passato.
UNTIL Mostra i dati fino a un momento specifico del passato.
DURANTE Mostra i dati a partire da un momento specifico del passato.
CONFRONTA CON Mostra i dati fino a un momento specifico del passato.
ORDER BY Specifica la colonna in base a cui ordinare i dati.
LIMIT Limita il numero di righe di dati mostrate.
AS Rinomina una colonna con un nome a tua scelta.

Scrittura delle query di ShopifyQL

Le query di ShopifyQL possono variare da quelle di base, per approfondimenti generici sui dati, a quelle complete, per approfondimenti dettagliati. Ogni parola chiave ha una funzione specifica che crea la tua query.

Nozioni di base su ShopifyQL: FROM e SHOW

La creazione della query di ShopifyQL più semplice richiede solo due parole chiave: FROM e SHOW, scritte in questo ordine. FROM seguito dal parametro del nome di una tabella specifica la tabella su cui desideri eseguire una query. SHOW seguito dal parametro del nome di una colonna specifica le colonne che desideri selezionare.

Ad esempio, puoi elencare tutti gli ID prodotto e i titoli corrispondenti della tabella relativa alle vendite scrivendo questa query:

FROM products
  SHOW product_id, product_title

Raggruppamento dei dati: GROUP BY

Per segmentare una metrica in base a una dimensione, ad esempio per raggruppare le vendite in base all'area geografica, utilizza la parola chiave GROUP BY. La parola chiave GROUP BY può essere associata a qualsiasi parametro di dimensione.

Ad esempio, una query che raggruppa le tariffe di spedizione totali per paese e area geografica di fatturazione sarà scritta come segue:

FROM orders
  SHOW shipping
  GROUP BY billing_country, billing_region

Ecco un'altra query di esempio che utilizza una dimensione temporale per mostrare il fatturato netto per mese:

FROM orders
  SHOW net_sales
  GROUP BY month

La query qui sopra non restituisce nessuno dei mesi in cui non sono presenti vendite. Se desideri una query che restituisca un periodo di tempo completo e ininterrotto, utilizza il modificatore ALL:

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

Quando utilizzi il modificatore ALL, devi specificare anche SINCE e UNTIL. Nota: il modificatore ALL funziona solo con la dimensione temporale.

Dimensioni temporali

Di seguito sono elencate le dimensioni temporali che puoi utilizzare per raggruppare i dati:

Dimensioni temporali di ShopifyQL
Operatore Uso funzionale
ora Raggruppamento per ora del giorno di calendario.
giorno Raggruppamento per giorno di calendario.
settimana Raggruppamento per settimana di calendario.
mese Raggruppamento per mese di calendario.
quarter Raggruppamento per trimestre di calendario.
anno Raggruppamento per anno di calendario.
hour_of_day Raggruppamento per 24 ore (1,2,...,24).
day_of_week Raggruppamento per giorno della settimana (L,M,M,...,D).
week_of_year Raggruppamento per settimana dell'anno (1,2,...,52).

Filtro dei dati: WHERE

La parola chiave WHERE ti consente di applicare un filtro dimensionale a un'intera query di ShopifyQL.

Ad esempio, se desideri che venga restituito il fatturato netto, raggruppato per mese, ma solo per un'area geografica specifica, la tua query sarà:

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

Come puoi vedere nell'esempio sopra riportato, puoi filtrare il set di risultati con il parametro WHERE anche se quel parametro non è incluso nelle parole chiave SHOW o GROUP BY. In questo caso, il fatturato netto viene filtrato per tutti i mesi per gli ordini con indirizzo di fatturazione solo in Ohio, anche se area_geografica_di_fatturazione non è incluso nel set di risultati.

Operatori di confronto

La parola chiave WHERE utilizza operatori di confronto per filtrare i dati. Nell'esempio qui sopra "=" è stato utilizzato per specificare che la query filtri un valore specifico, tuttavia sono disponibili anche altri operatori:

Operatori di confronto di ShopifyQL
Operatore di confronto Uso funzionale
= uguale a
!= non uguale a
< minore di
> maggiore di
<= minore di o uguale a
>= maggiore di o uguale a

Operatori logici

Per filtrare ulteriormente i dati, puoi aggiungere operatori logici alla query. Gli operatori logici di ShopifyQL sono:

Operatori logici di ShopifyQL
Operatore logico Uso funzionale
AND Filtro per mostrare tutte le righe in cui le condizioni separate da AND sono soddisfatte.
OR Filtro per mostrare tutte le righe in cui una delle condizioni separate da OR è soddisfatta.
NOT Filtro per mostrare solo le righe in cui le condizioni non sono soddisfatte, ad esempio le righe che non contengono il valore specificato.

Con la parola chiave WHERE puoi utilizzare più filtri aggiungendo operatori logici.

Ampliando la query del set di dati di esempio in modo da ottenere un raggruppamento mensile del fatturato netto per tutti gli ordini con indirizzo di fatturazione in Ohio e con uno sconto applicato, la query sarà:

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

Intervalli di date: SINCE e UNTIL

Se desideri filtrare la query in base a una data o a un determinato periodo di tempo, puoi utilizzare le parole chiave SINCE e UNTIL e i loro parametri associati. Queste parole chiave sono univoche perché filtrano solo i periodi di tempo.

Ad esempio, questa è una query per trovare il fatturato netto degli ultimi 12 mesi, in Canada, a partire da oggi:

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

Operatori offset

Puoi filtrare in base a date specifiche o a offset di date. Gli operatori offset di ShopifyQL sono:

Operatori offset di ShopifyQL
Operatore offset Uso funzionale
-{#}d Numero di giorni trascorsi dal giorno in cui viene eseguita la query.
-{#}w Numero di settimane trascorse dal giorno in cui viene eseguita la query.
-{#}m Numero di mesi trascorsi dal giorno in cui viene eseguita la query.
-{#}q Numero di trimestri trascorsi dal giorno in cui viene eseguita la query.
-{#}y Numero di anni trascorsi dal giorno in cui viene eseguita la query.
aaaa-mm-gg Una data specifica.
oggi Data in cui viene eseguita la query.
ieri Le 24 ore che precedono il momento in cui viene eseguita la query.

Filtraggio basato su intervalli di date: DURING

La parola chiave DURANTE semplifica il filtro delle date per gli intervalli di date. Puoi utilizzare la parola chiave DURANTE per filtrare i risultati della query in base a un periodo di tempo noto, ad esempio un anno di calendario o un mese specifico, o per intervalli di date con date diverse ogni anno, ad esempio Black Friday Cyber Monday. Per esempio:

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

DURANTE accetta uno dei seguenti operatori di intervallo di date denominati:

Operatori dell'intervallo di date denominati ShopifyQL
Operatore intervallo di date Uso funzionale
oggi La data in cui viene eseguita la query.
ieri Le 24 ore che precedono il momento in cui viene eseguita la query.
this_week La settimana di calendario attuale.
this_month Il mese di calendario attuale.
this_quarter Il trimestre di calendario attuale.
this_year L'anno solare corrente.
last_week La settimana di calendario precedente.
last_month Il mese di calendario precedente.
last_quarter Il trimestre di calendario precedente.
last_year L'anno solare precedente.
bfcm2022 Dal 25 novembre al 28 novembre 2022.
bfcm2021 Dal 26 al 29 novembre 2021.

Confronto tra intervalli di date: COMPARE TO

La parola chiave CONFRONTA CON ti consente di confrontare i dati nell'intervallo di date in DURANTE e quello in CONFRONTA CON. Accetta qualunque operatore dell'intervallo di date denominato elencato nella sezione DURING. L'operatore utilizzato da CONFRONTA CON deve avere la stessa durata di quello utilizzato da DURANTE. Ad esempio, DURING this_week COMPARE TO last_week è una combinazione valida ma DURING this_week COMPARE TO last_month non lo è.

L'esempio seguente confronta il fatturato netto Black Friday Cyber Monday 2022 con quello Black Friday Cyber Monday 2021.

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

Ordinamento dei dati: ORDER BY

Puoi specificare come desideri ordinare i dati restituiti dalla query utilizzando la parola chiave ORDER BY e i relativi parametri: ASC, per l'ordine crescente e DESC, per l'ordine decrescente.

Nella parola chiave ORDER BY puoi specificare ogni metrica o dimensione inclusa nella query, anche specificando più campi.

Ad esempio, questa query restituisce il fatturato netto delle vendite per ogni paese e area geografica di fatturazione, ordinati in ordine alfabetico inverso in base al paese di fatturazione e poi in base all'area geografica di fatturazione all'interno di ciascun paese.

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

L'ordine in cui scrivi le metriche o le dimensioni è importante: se specifichi più valori per ORDER BY, l'ordinamento viene applicato per ciascuna metrica o dimensione nell'ordine fornito.

LIMIT

La parola chiave LIMIT ti consente di specificare il numero delle righe restituite dalla query. Questa operazione risulta utile quando desideri solo capire l'aspetto dei dati di ogni colonna. In alternativa, puoi combinarla con ORDER BY per creare elenchi con classifiche.

Questo esempio utilizza LIMIT e ORDER BY per creare un elenco dei 10 prodotti più venduti per quantità negli ultimi 3 mesi:

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

Grafici per le query: VISUALIZE e TYPE

La parola chiave VISUALIZE ti permette di scrivere una query di ShopifyQL che mostra i dati in una visualizzazione a linee o a barre.

La parola chiave TYPE è facoltativa e deve essere accompagnata da "linea" o "barra" in modo che la tua query restituisca una visualizzazione in un grafico rispettivamente a linee o a barre. Se TYPE non è inclusa nella query, ShopifyQL sceglie automaticamente la visualizzazione più adatta alla tua query; se quest'ultima non può essere visualizzata in forma scritta, ShopifyQL restituisce i dati in formato di tabella.

Ad esempio, puoi visualizzare il trend di vendita dell'ultimo anno per mese tramite una linea del trend. Questa query restituisce un grafico della serie temporale che mostra il fatturato lordo mensile nell'ultimo anno. Il fatturato lordo è raffigurato da una singola linea, con l'asse X che rappresenta il mese e l'asse Y che rappresenta il fatturato lordo:

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

Operatori aritmetici

ShopifyQL consente di effettuare operazioni aritmetiche con le metriche dei tuoi dati. Sono disponibili i seguenti operatori aritmetici:

Operatori offset di ShopifyQL
Operatori aritmetici Uso funzionale
+ Addizione di due numeri.
- Sottrazione di due numeri.
* Moltiplicazione di due numeri.
/ Divisione di due numeri.

Ad esempio, questa query calcola il valore dell'ordine per ogni area geografica nel corso dell'ultimo anno. Quando utilizzi gli operatori aritmetici con le metriche, puoi utilizzare la parola chiave AS per assegnare un nuovo nome alla nuova metrica.

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

Funzioni

Le funzioni di ShopifyQL ti permettono di aggregare colonne simili alle tabelle pivot di Microsoft Excel. Aggregare le colonne significa combinarle per creare un nuovo valore. Nella versione attuale di ShopifyQL sono disponibili i seguenti operatori di funzione:

Operatori offset di ShopifyQL
Operatore di funzione Uso funzionale
count() Conteggio delle istanze nel set di risultati.
sum() Somma dei valori nel set di risultati.
min() Valore minimo nel set di risultati.
max() Il valore massimo nel set di risultati.
avg() Valore medio nel set di risultati.

Le funzioni sum, min, max e avg possono essere utilizzate solo con valori numerici, mentre count può essere utilizzato per contare istanze diverse di attributi dimensionali. Non puoi utilizzare i campi aggregati come argomenti delle funzioni. I campi aggregati terminano in _sum, _counto _percent.

Ad esempio, questa query restituisce un errore dato che il valore vendite_totali è già stato aggregato:

FROM orders
  SHOW sum(total_sales)

Ecco una query valida che unisce campi aggregati e funzioni aggregate:

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

Questa query restituisce la somma aggregata del valore medio degli ordini, la somma del fatturato lordo come risultato della funzione sum. Queste metriche sono suddivise per area geografica di fatturazione per tutti gli ordini effettuati nel 2021.

Commenti

Puoi utilizzare i commenti per spiegare le sezioni delle istruzioni ShopifyQL o per impedire l'esecuzione di un'istruzione ShopifyQL. Qualsiasi testo all'interno di un commento verrà ignorato durante il tempo di esecuzione.

I commenti su una singola riga iniziano con -- e terminano alla fine della riga.

I commenti su più righe iniziano con /* e terminano con */.

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

Sei pronto per iniziare a vendere con Shopify?

Provalo, è gratis