> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Riferimento di AftersellQL (AQL)

> Il riferimento del linguaggio di query AftersellQL: metriche e dimensioni disponibili, sintassi delle clausole AQL con esempi e regole sui fusi orari per l'Explorer.

Ogni query che crei nell'[Explorer](/it/aftersell/reports_explorer) è un'istruzione **AftersellQL (AQL)**. Nella maggior parte dei casi crei le query in modo visuale e non scrivi mai AQL a mano; questa pagina è il riferimento per le metriche e le dimensioni che puoi scegliere, per la forma testuale di AQL e per le regole sui fusi orari.

<div id="available-metrics">
  ## Metriche disponibili
</div>

Queste sono le metriche che puoi scegliere, raggruppate nello stesso modo in cui le raggruppa il selettore delle metriche.

<div id="revenue-profit">
  ### Ricavi e profitto
</div>

| Metrica | Descrizione |
| - | - |
| **Revenue** | Ricavi da upsell nella valuta nativa del tuo negozio. |
| **Revenue (USD)** | Ricavi da upsell normalizzati in USD per confronti tra valute. |
| **Revenue Per Visit** | Ricavi da upsell per sessione di impression. Non può essere suddivisa per prodotto, placement, funnel o dispositivo. |
| **Avg. Conversion Value** | Ricavi per offerta accettata. Detto anche Average Upsell Value. |
| **Upsell Revenue Per Order** | Ricavi da upsell (USD) divisi per il totale degli ordini. Solo a livello di negozio. |
| **Product Profit** | Ricavi meno il costo del venduto (COGS) per i prodotti in upsell. Si basa sui COGS configurati dal merchant, quindi trattala come una stima: i prodotti senza un costo tracciato riportano i ricavi come profitto e la copertura dei costi varia da negozio a negozio. Solo a granularità di prodotto; non può essere suddivisa per funnel, placement o dispositivo. |

<div id="conversions">
  ### Conversioni
</div>

| Metrica | Descrizione |
| - | - |
| **Conversions** | Il numero di eventi di offerta accettata. Un'offerta accettata è una conversione, quindi una sessione che accetta due offerte conta due volte. |
| **Accept Rate** | Basato sulle sessioni: la quota di sessioni che hanno visto un'offerta e ne hanno accettata almeno una. È calcolato indipendentemente da Conversions, da un rollup diverso, quindi non è Conversions ÷ Impressions. |
| **Units Sold** | Unità totali vendute tramite offerte di upsell. |
| **Decline Rate** | Percentuale di offerte post-acquisto rifiutate esplicitamente. Solo post-acquisto. |

<div id="engagement">
  ### Interazione
</div>

| Metrica | Descrizione |
| - | - |
| **Impressions** | Sessioni uniche che hanno visto un'offerta. |
| **Show Rate** | Percentuale di decisioni che hanno prodotto un'impression. |

<div id="store-performance">
  ### Prestazioni del negozio
</div>

| Metrica | Descrizione |
| - | - |
| **Total Store Revenue** | Ricavi totali degli ordini pagati su Shopify. Solo a livello di negozio; non può essere suddivisa per superficie, funnel, placement o dispositivo. |
| **Orders** | Totale degli ordini pagati su Shopify. Solo a livello di negozio. |
| **Average Total Order Value** | Ricavi del negozio divisi per gli ordini. Valore medio dell'ordine a livello di negozio. |

<div id="rokt-network">
  ### Rete Rokt
</div>

| Metrica | Descrizione |
| - | - |
| **Rokt Revenue** | Ricavi della rete Rokt attribuiti al tuo negozio. |
| **Rokt Transactions** | Numero di transazioni della rete Rokt per il tuo negozio. |
| **Rokt Revenue / Transaction** | Ricavi Rokt divisi per le transazioni per intervallo temporale. |
| **Rokt Impressions** | Impression totali della rete Rokt su tutti i placement del tuo negozio. Distinta dalle **Impressions** di upsell. |
| **Rokt Referrals** | Referral della rete Rokt, interazioni positive che hanno indirizzato l'acquirente a un partner Rokt. |

<div id="dimensions">
  ## Dimensioni
</div>

Le dimensioni suddividono una metrica in base a un attributo. Non tutte le dimensioni sono compatibili con ogni metrica; l'Explorer impedisce automaticamente le combinazioni incompatibili (ad esempio, **Decline rate** e **Show rate** non possono essere suddivise per **Currency**).

<div id="available-dimensions">
  ### Dimensioni disponibili
</div>

| Dimensione | Descrizione |
| - | - |
| **Date** | Raggruppa i risultati per giorno, settimana o mese. |
| **Surface** | La superficie di upsell: PPU (post-acquisto), Checkout, Thank You Page o Cart. |
| **Funnel** | Il funnel specifico a cui appartiene l'offerta. |
| **Product** | Il prodotto proposto in upsell. |
| **Placement** | Il placement all'interno di un funnel. |
| **Device** | Il tipo di dispositivo: Mobile, Desktop o Unknown. Non esiste un valore separato per tablet. |
| **Currency** | Il codice valuta ISO (ad esempio USD, EUR, GBP). Utile per negozi multi-valuta. |

<div id="unavailable-dimensions">
  ### Dimensioni non disponibili
</div>

Le seguenti sono ancora in fase di sviluppo. Compaiono nel selettore ma risultano 'Not compatible' per ogni metrica finché non saranno implementate.

| Dimensione | Descrizione |
| - | - |
| **Flow type** | Il tipo di flusso di upsell. |
| **Experiment** | La variante del test A/B o dell'esperimento. |
| **Outcome** | L'esito della decisione (ad esempio idoneo, esaurito). |
| **Reason code** | Il motivo dell'esito di una decisione. |
| **Scope** | L'ambito della decisione (Flow, Experience, Placement o ItemSlot). |
| **Response type** | La risposta all'offerta (Accepted, Declined o Timeout). |

<div id="aql-statement-syntax">
  ## Sintassi delle istruzioni AQL
</div>

Un'istruzione AQL è una singola domanda composta da clausole. Solo `SELECT` e un intervallo di tempo (`SINCE`) sono obbligatori; tutto il resto è facoltativo. Quando includi clausole facoltative, devono comparire in questo ordine:

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT    <metrics>                    -- what to measure (required)
WHERE     <filters>                    -- narrow the data
GROUP BY  <dimensions>                 -- break the numbers down
SINCE     <time range>                 -- the period to cover (required)
GRAIN     <time grain>                 -- bucket size for time series
COMPARE   <comparison>                 -- compare against another period
CHART     <visualization>              -- how to display the result
TIMEZONE  "<timezone>"                 -- timezone for date buckets
ORDER BY  <field> <direction>          -- sort the results
LIMIT     <number>                     -- cap the number of rows
```

Un esempio minimo, ricavi da upsell giornalieri e tasso di accettazione degli ultimi 30 giorni:

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
```

<Note>
  Le parole chiave non fanno distinzione tra maiuscole e minuscole (`SELECT` e `select` funzionano entrambe) e le istruzioni non terminano con un punto e virgola. I valori stringa sono racchiusi tra virgolette doppie; i numeri e gli elenchi no.
</Note>

<div id="select-and-group-by">
  ### SELECT e GROUP BY
</div>

* **`SELECT`** elenca le metriche da misurare, separate da virgole, ad esempio `SELECT revenue, impressions, accept_rate`.
* **`GROUP BY`** suddivide quelle metriche in base a una o più dimensioni, come `date`, `device`, `surface` o `funnel`. Senza `GROUP BY`, ottieni un unico totale per l'intero periodo.

<div id="filtering-with-where">
  ### Filtrare con WHERE
</div>

`WHERE` restringe i dati prima che vengano misurati. Combina le condizioni con `AND`.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue
WHERE device = "mobile"
GROUP BY date
SINCE last_month
GRAIN day
```

<Warning>
  `impressions`, `accept_rate` e `rpv` **non possono** essere filtrate o raggruppate per dispositivo, funnel, placement o prodotto; il loro rollup di origine non ha una colonna di questo tipo. L'aggiunta di `WHERE device = "mobile"` a una query che seleziona una di esse viene rifiutata con `metric "impressions" cannot be filtered by "device"`.
</Warning>

I confronti supportati sono `=`, `!=`, `IN`, `NOT IN`, `>`, `<`, `>=` e `<=`. Usa un elenco con `IN` per corrispondere a più valori:

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
WHERE surface IN ["PPU", "Checkout"]
```

`experiment` **non** è un campo filtrabile; non ha una fonte di rollup, quindi `WHERE experiment IN [...]` viene rifiutato con `filters on "experiment" are not supported.`

Il filtro **funnel** supporta la selezione multipla: **is one of** (`IN`) include solo i funnel selezionati, **is not one of** (`NOT IN`) li esclude. Quando raggruppi per **Funnel** e applichi un filtro **is one of**, il grafico mostra una linea per ogni funnel selezionato, senza raggruppamento in "Other".

<div id="time-ranges-and-comparisons">
  ### Intervalli di tempo e confronti
</div>

Ogni query ha bisogno di un intervallo di tempo, impostato con `SINCE`:

| Forma | Esempio | Significato |
| - | - | - |
| Preimpostato | `SINCE last_30d` | Una finestra mobile che termina **ieri** (UTC). Il giorno corrente in corso è escluso deliberatamente, quindi `last_1d` significa solo ieri e `this_month` va dal 1° del mese fino a ieri. |
| Finestra personalizzata | `SINCE 2026-07-02 UNTIL 2026-07-05` | Un intervallo fisso, con date ISO (`YYYY-MM-DD`). |

Preimpostazioni disponibili: `last_1d`, `last_7d`, `last_30d`, `last_90d`, `this_month`, `last_month` e `this_year`.

* **`GRAIN`** imposta la dimensione degli intervalli per le serie temporali: `day`, `week` o `month`. (`hour` viene interpretato, ma nessun rollup fornisce dati orari, quindi una query di questo tipo viene rifiutata con `group_by / time_grain combination is not supported.`)
* **`COMPARE`** sovrappone un secondo periodo. Usa `previous_period`, la finestra di pari durata immediatamente precedente. `previous_year` è nascosto dal selettore Compare perché il data warehouse non contiene dati precedenti a febbraio 2026; resta digitabile in AQL solo affinché le query salvate in precedenza continuino a essere interpretate.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- A four-day sale vs the four days immediately before it
SELECT revenue, impressions, accept_rate
GROUP BY date
SINCE 2026-07-02 UNTIL 2026-07-05
GRAIN day
COMPARE previous_period
```

<Note>
  I dati di reporting partono da **febbraio 2026**, quindi una finestra precedente a tale data restituisce risultati vuoti per entrambi i periodi.
</Note>

<div id="choosing-a-chart">
  ### Scegliere un grafico
</div>

* **`CHART`** imposta come viene visualizzato il risultato: `scorecard`, `line_chart`, `bar_chart`, `area_chart`, `funnel_chart` o `table`.
* **`TIMEZONE`** imposta il fuso orario usato per raggruppare le date, come nome IANA tra virgolette, ad esempio `TIMEZONE "America/New_York"`. Il valore predefinito è UTC (vedi [Fusi orari](#timezones)).

Il tipo `funnel_chart` ha requisiti specifici:

* **Modalità placement.** Raggruppa per `placement` e seleziona una metrica. Le fasi sono ordinate secondo la sequenza canonica dei placement (upsell predefinito, poi downsell, poi upsell aggiuntivi). Viene tracciata solo la prima metrica; le metriche aggiuntive sono indicate in una nota a piè di pagina.
* **Modalità metrica.** Seleziona due o più metriche senza `GROUP BY`. Ogni metrica diventa una fase del funnel nell'ordine della query (ad esempio, `SELECT impressions, conversions` mostra il calo da impressioni a conversioni). Tutte le metriche devono avere la stessa unità.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Placement funnel: conversion drop-off across placements
SELECT conversions
GROUP BY placement
SINCE last_30d
CHART funnel_chart
```

<Warning>
  La modalità placement richiede una metrica che possa essere suddivisa per placement. `impressions`, `accept_rate` e `rpv` non possono esserlo; per queste il grafico a funnel mostra "These metrics can't be grouped by placement".
</Warning>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Metric funnel: impressions to conversions drop-off
SELECT impressions, conversions
SINCE last_30d
CHART funnel_chart
```

<div id="sorting-and-limiting">
  ### Ordinamento e limitazione
</div>

* **`ORDER BY`** ordina i risultati in base a una metrica o dimensione, con `ASC` o `DESC`.
* **`LIMIT`** limita il numero di righe restituite, utile per domande del tipo "top N".

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Top 20 products by upsell revenue this month
SELECT revenue, conversions, avg_conversion_value
GROUP BY product
SINCE this_month
ORDER BY revenue DESC
LIMIT 20
```

<div id="more-examples">
  ### Altri esempi
</div>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Daily performance vs the previous period
SELECT revenue, impressions, conversions, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
COMPARE previous_period
```

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Mobile vs desktop revenue over the last 90 days
SELECT revenue
GROUP BY device
SINCE last_90d
ORDER BY revenue DESC
```

<Note>
  `impressions`, `accept_rate` e `rpv` non possono essere suddivise per dispositivo; il loro rollup è negozio × superficie × giorno, senza colonna del dispositivo. Usa `revenue` (o un'altra metrica basata sulle conversioni) per i confronti tra dispositivi.
</Note>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Which surface is driving the most revenue?
SELECT revenue, impressions, accept_rate
GROUP BY surface
SINCE last_30d
ORDER BY revenue DESC
```

<div id="timezones">
  ## Fusi orari
</div>

Per impostazione predefinita, le query vengono eseguite in UTC. Puoi sostituire il fuso orario in modo che i risultati raggruppati per data riflettano l'ora locale (vedi [Impostare un fuso orario](/it/aftersell/reports_explorer#setting-a-timezone) per i passaggi nella barra degli strumenti).

<Note>
  Le query che includono **Impressions**, **Accept Rate** o **Revenue Per Visit** raggruppano sempre le date in UTC, indipendentemente dal fuso orario selezionato, perché provengono da un rollup giornaliero riportato in giorni UTC. Se una query combina una di queste con altre metriche, l'intero set di risultati torna a UTC in modo che gli intervalli di date restino allineati.
</Note>

<div id="the-timezone-clause">
  ### La clausola TIMEZONE
</div>

Specifica un fuso orario direttamente in AQL con la clausola `TIMEZONE`, che compare tra `CHART` e `ORDER BY`:

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT ...
CHART ...
TIMEZONE "Asia/Tokyo"
ORDER BY ...
```

Quando è presente, la clausola sostituisce la selezione della barra degli strumenti per quella query e viene conservata quando salvi e ricarichi.

<div id="available-timezones">
  ### Fusi orari disponibili
</div>

Il selettore (e la clausola `TIMEZONE`) accetta un insieme chiuso di dieci fusi. Qualsiasi altro fuso orario IANA viene rifiutato come non supportato.

| Fuso orario | Località di esempio |
| - | - |
| UTC | Tempo coordinato universale |
| America/New\_York | New York (ET) |
| America/Chicago | Chicago (CT) |
| America/Denver | Denver (MT) |
| America/Los\_Angeles | Los Angeles (PT) |
| Europe/London | Londra (GMT/BST) |
| Europe/Paris | Parigi (CET/CEST) |
| Asia/Tokyo | Tokyo (JST) |
| Asia/Singapore | Singapore (SGT) |
| Australia/Sydney | Sydney (AEST/AEDT) |

<div id="account-default-and-how-timezone-affects-results">
  ### Account default e come il fuso orario influisce sui risultati
</div>

Se **Lock reporting timezone** è abilitato nelle impostazioni delle analitiche, selezionando **Account default** viene usato quel fuso orario bloccato (la barra degli strumenti mostra il fuso risolto, ad esempio **Timezone: Account default (Paris (CET))**). La pagina delle impostazioni delle analitiche accetta l'elenco IANA completo, ma Reports rispetta solo i dieci fusi indicati sopra; se il tuo fuso bloccato non è tra questi, **Account default** si risolve silenziosamente in UTC. Se **Lock reporting timezone** non è abilitato, **Account default** torna a UTC.

Quando è impostato un fuso orario, il raggruppamento per data usa l'ora locale invece di UTC. Ad esempio, un evento alle `2026-03-29T01:30:00Z` cade il 28 marzo a New York (ET) ma il 29 marzo a Parigi (CET). Le query senza fuso orario, incluse quelle salvate in precedenza, continuano a essere eseguite in UTC.