> ## 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.

# Referência do AftersellQL (AQL)

> A referência da linguagem de consulta AftersellQL: métricas e dimensões disponíveis, sintaxe das cláusulas AQL com exemplos e regras de fuso horário para o Explorer.

Toda consulta que você cria no [Explorer](/pt/aftersell/reports_explorer) é uma instrução **AftersellQL (AQL)**. Na maior parte do tempo, você cria consultas visualmente e nunca escreve AQL à mão; esta página é a referência para as métricas e dimensões que você pode escolher, a forma textual do AQL e as regras de fuso horário.

<div id="available-metrics">
  ## Métricas disponíveis
</div>

Estas são as métricas que você pode escolher, agrupadas da mesma forma que o seletor de métricas as agrupa.

<div id="revenue-profit">
  ### Receita e lucro
</div>

| Métrica | Descrição |
| - | - |
| **Revenue** | Receita de upsell na moeda nativa da sua loja. |
| **Revenue (USD)** | Receita de upsell normalizada para USD, para comparações entre moedas. |
| **Revenue Per Visit** | Receita de upsell por sessão com impressão. Não pode ser dividida por produto, posicionamento, funil ou dispositivo. |
| **Avg. Conversion Value** | Receita por oferta aceita. Também chamada de Average Upsell Value. |
| **Upsell Revenue Per Order** | Receita de upsell (USD) dividida pelo total de pedidos. Apenas no nível da loja. |
| **Product Profit** | Receita menos o custo dos produtos vendidos (COGS) dos produtos de upsell. Depende do COGS configurado pelo lojista, então trate-o como uma estimativa: produtos sem custo rastreado reportam a receita como lucro, e a cobertura de custos varia de loja para loja. Apenas na granularidade de produto; não pode ser dividido por funil, posicionamento ou dispositivo. |

<div id="conversions">
  ### Conversões
</div>

| Métrica | Descrição |
| - | - |
| **Conversions** | O número de eventos de oferta aceita. Uma oferta aceita é uma conversão, então uma sessão que aceita duas ofertas conta duas vezes. |
| **Accept Rate** | Baseada em sessões: a parcela de sessões que viram uma oferta e aceitaram pelo menos uma. Calculada independentemente de Conversions, a partir de um rollup diferente, portanto não é Conversions ÷ Impressions. |
| **Units Sold** | Total de unidades vendidas por meio de ofertas de upsell. |
| **Decline Rate** | Porcentagem de ofertas de pós-compra recusadas explicitamente. Apenas pós-compra. |

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

| Métrica | Descrição |
| - | - |
| **Impressions** | Sessões únicas que viram uma oferta. |
| **Show Rate** | Porcentagem de decisões que resultaram em uma impressão. |

<div id="store-performance">
  ### Desempenho da loja
</div>

| Métrica | Descrição |
| - | - |
| **Total Store Revenue** | Receita total de pedidos pagos no Shopify. Apenas no nível da loja; não pode ser dividida por superfície, funil, posicionamento ou dispositivo. |
| **Orders** | Total de pedidos pagos no Shopify. Apenas no nível da loja. |
| **Average Total Order Value** | Receita da loja dividida pelos pedidos. Valor médio do pedido no nível da loja. |

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

| Métrica | Descrição |
| - | - |
| **Rokt Revenue** | Receita da rede Rokt atribuída à sua loja. |
| **Rokt Transactions** | Contagem de transações da rede Rokt para a sua loja. |
| **Rokt Revenue / Transaction** | Receita da Rokt dividida pelas transações em cada intervalo de tempo. |
| **Rokt Impressions** | Total de impressões da rede Rokt nos posicionamentos da sua loja. Diferente das **Impressions** de upsell. |
| **Rokt Referrals** | Indicações da rede Rokt, engajamentos positivos que enviaram o comprador a um parceiro da Rokt. |

<div id="dimensions">
  ## Dimensões
</div>

As dimensões dividem uma métrica por um atributo. Nem todas as dimensões são compatíveis com todas as métricas; o Explorer impede automaticamente combinações incompatíveis (por exemplo, **Decline rate** e **Show rate** não podem ser divididas por **Currency**).

<div id="available-dimensions">
  ### Dimensões disponíveis
</div>

| Dimensão | Descrição |
| - | - |
| **Date** | Agrupa os resultados por dia, semana ou mês. |
| **Surface** | A superfície de upsell: PPU (pós-compra), Checkout, Thank You Page ou Cart. |
| **Funnel** | O funil específico ao qual a oferta pertence. |
| **Product** | O produto de upsell. |
| **Placement** | O posicionamento dentro de um funil. |
| **Device** | O tipo de dispositivo: Mobile, Desktop ou Unknown. Não há um valor separado para tablet. |
| **Currency** | O código de moeda ISO (por exemplo, USD, EUR, GBP). Útil para lojas com várias moedas. |

<div id="unavailable-dimensions">
  ### Dimensões indisponíveis
</div>

As dimensões a seguir estão em desenvolvimento. Elas aparecem no seletor, mas são exibidas como 'Not compatible' para todas as métricas até serem implementadas.

| Dimensão | Descrição |
| - | - |
| **Flow type** | O tipo de fluxo de upsell. |
| **Experiment** | O teste A/B ou a variante do experimento. |
| **Outcome** | O resultado da decisão (por exemplo, elegível, fora de estoque). |
| **Reason code** | O motivo de um resultado de decisão. |
| **Scope** | O escopo da decisão (Flow, Experience, Placement ou ItemSlot). |
| **Response type** | A resposta à oferta (Accepted, Declined ou Timeout). |

<div id="aql-statement-syntax">
  ## Sintaxe das instruções AQL
</div>

Uma instrução AQL é uma única pergunta composta por cláusulas. Apenas `SELECT` e um intervalo de tempo (`SINCE`) são obrigatórios; todo o resto é opcional. Ao incluir cláusulas opcionais, elas devem aparecer nesta ordem:

```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
```

Um exemplo mínimo, receita de upsell diária e taxa de aceitação dos últimos 30 dias:

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

<Note>
  As palavras-chave não diferenciam maiúsculas de minúsculas (`SELECT` e `select` funcionam) e as instruções não terminam com ponto e vírgula. Valores de texto ficam entre aspas duplas; números e listas não.
</Note>

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

* **`SELECT`** lista as métricas a medir, separadas por vírgulas, por exemplo `SELECT revenue, impressions, accept_rate`.
* **`GROUP BY`** divide essas métricas por uma ou mais dimensões, como `date`, `device`, `surface` ou `funnel`. Sem `GROUP BY`, você obtém um único total para todo o período.

<div id="filtering-with-where">
  ### Filtrando com WHERE
</div>

`WHERE` restringe os dados antes de serem medidos. Combine condições com `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` **não podem** ser filtradas ou agrupadas por dispositivo, funil, posicionamento ou produto; o rollup de origem delas não tem essa coluna. Adicionar `WHERE device = "mobile"` a uma consulta que selecione qualquer uma delas é rejeitado com `metric "impressions" cannot be filtered by "device"`.
</Warning>

As comparações suportadas são `=`, `!=`, `IN`, `NOT IN`, `>`, `<`, `>=` e `<=`. Use uma lista com `IN` para corresponder a vários valores:

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

`experiment` **não** é um campo filtrável; ele não tem fonte de rollup, então `WHERE experiment IN [...]` é rejeitado com `filters on "experiment" are not supported.`

O filtro de **funnel** suporta seleção múltipla: **is one of** (`IN`) inclui apenas os funis selecionados, e **is not one of** (`NOT IN`) os exclui. Quando você agrupa por **Funnel** e aplica um filtro **is one of**, o gráfico mostra uma linha por funil selecionado, sem agrupamento em "Other".

<div id="time-ranges-and-comparisons">
  ### Intervalos de tempo e comparações
</div>

Toda consulta precisa de um intervalo de tempo, definido com `SINCE`:

| Forma | Exemplo | Significado |
| - | - | - |
| Predefinição | `SINCE last_30d` | Uma janela móvel que termina **ontem** (UTC). O dia atual em andamento é excluído de propósito, então `last_1d` significa apenas ontem, e `this_month` vai do dia 1º até ontem. |
| Janela personalizada | `SINCE 2026-07-02 UNTIL 2026-07-05` | Um intervalo fixo, usando datas ISO (`YYYY-MM-DD`). |

Predefinições disponíveis: `last_1d`, `last_7d`, `last_30d`, `last_90d`, `this_month`, `last_month` e `this_year`.

* **`GRAIN`** define o tamanho do intervalo para séries temporais: `day`, `week` ou `month`. (`hour` é interpretado, mas nenhum rollup fornece dados por hora, então essa consulta é rejeitada com `group_by / time_grain combination is not supported.`)
* **`COMPARE`** sobrepõe um segundo período. Use `previous_period`, a janela de mesma duração imediatamente anterior. `previous_year` fica oculto no seletor Compare porque o data warehouse não contém dados anteriores a fevereiro de 2026; ele continua aceito no AQL apenas para que consultas salvas anteriormente continuem sendo interpretadas.

```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>
  Os dados de relatórios começam em **fevereiro de 2026**, então uma janela anterior a isso retorna vazio para ambos os períodos.
</Note>

<div id="choosing-a-chart">
  ### Escolhendo um gráfico
</div>

* **`CHART`** define como o resultado é exibido: `scorecard`, `line_chart`, `bar_chart`, `area_chart`, `funnel_chart` ou `table`.
* **`TIMEZONE`** define o fuso horário usado para agrupar datas, como um nome IANA entre aspas, por exemplo `TIMEZONE "America/New_York"`. O padrão é UTC (veja [Fusos horários](#timezones)).

O tipo `funnel_chart` tem requisitos específicos:

* **Modo de posicionamento.** Agrupe por `placement` e selecione uma métrica. As etapas são ordenadas pela sequência canônica de posicionamentos (upsell padrão, depois downsell, depois upsells adicionais). Apenas a primeira métrica é plotada; métricas adicionais são mencionadas em uma nota de rodapé.
* **Modo de métricas.** Selecione duas ou mais métricas sem `GROUP BY`. Cada métrica se torna uma etapa do funil na ordem da consulta (por exemplo, `SELECT impressions, conversions` mostra a queda de impressões para conversões). Todas as métricas devem ter a mesma unidade.

```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>
  O modo de posicionamento precisa de uma métrica que possa ser dividida por posicionamento. `impressions`, `accept_rate` e `rpv` não podem; para elas, o gráfico de funil 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">
  ### Ordenação e limite
</div>

* **`ORDER BY`** ordena os resultados por uma métrica ou dimensão, com `ASC` ou `DESC`.
* **`LIMIT`** limita o número de linhas retornadas, útil para perguntas do 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">
  ### Mais exemplos
</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` não podem ser divididas por dispositivo; o rollup delas é loja × superfície × dia, sem coluna de dispositivo. Use `revenue` (ou outra métrica originada de conversões) para comparações por dispositivo.
</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">
  ## Fusos horários
</div>

Por padrão, as consultas são executadas em UTC. Você pode substituir o fuso horário para que os resultados agrupados por data reflitam o horário local (veja [Definindo um fuso horário](/pt/aftersell/reports_explorer#setting-a-timezone) para os passos na barra de ferramentas).

<Note>
  Consultas que incluem **Impressions**, **Accept Rate** ou **Revenue Per Visit** sempre agrupam datas em UTC, independentemente do fuso horário selecionado, porque elas vêm de um rollup diário reportado em dias UTC. Se uma consulta misturar uma delas com outras métricas, todo o conjunto de resultados volta para UTC para que os intervalos de data permaneçam alinhados.
</Note>

<div id="the-timezone-clause">
  ### A cláusula TIMEZONE
</div>

Especifique um fuso horário diretamente no AQL com a cláusula `TIMEZONE`, que aparece entre `CHART` e `ORDER BY`:

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

Quando presente, a cláusula substitui a seleção da barra de ferramentas para aquela consulta e é preservada quando você salva e recarrega.

<div id="available-timezones">
  ### Fusos horários disponíveis
</div>

O seletor (e a cláusula `TIMEZONE`) aceita um conjunto fechado de dez fusos. Qualquer outro fuso horário IANA é rejeitado como não suportado.

| Fuso horário | Localização de exemplo |
| - | - |
| UTC | Tempo Universal Coordenado |
| America/New\_York | Nova York (ET) |
| America/Chicago | Chicago (CT) |
| America/Denver | Denver (MT) |
| America/Los\_Angeles | Los Angeles (PT) |
| Europe/London | Londres (GMT/BST) |
| Europe/Paris | Paris (CET/CEST) |
| Asia/Tokyo | Tóquio (JST) |
| Asia/Singapore | Singapura (SGT) |
| Australia/Sydney | Sydney (AEST/AEDT) |

<div id="account-default-and-how-timezone-affects-results">
  ### Padrão da conta e como o fuso horário afeta os resultados
</div>

Se **Lock reporting timezone** estiver ativado nas suas configurações de análises, selecionar **Account default** usa esse fuso horário bloqueado (a barra de ferramentas mostra o fuso resolvido, por exemplo **Timezone: Account default (Paris (CET))**). A página de configurações de análises aceita a lista IANA completa, mas o Reports respeita apenas os dez fusos acima; se o seu fuso bloqueado não for um deles, **Account default** é resolvido silenciosamente para UTC. Se **Lock reporting timezone** não estiver ativado, **Account default** volta para UTC.

Quando um fuso horário é definido, o agrupamento por data usa o horário local em vez de UTC. Por exemplo, um evento em `2026-03-29T01:30:00Z` cai em 28 de março em Nova York (ET), mas em 29 de março em Paris (CET). Consultas sem fuso horário, incluindo as salvas anteriormente, continuam sendo executadas em UTC.