Usar ShopifyQL no Notebooks

Esta página foi impressa em Apr 20, 2024. Para a versão mais recente, acesse https://help.shopify.com/pt-BR/manual/reports-and-analytics/shopifyql-notebooks/using-shopifyql-for-notebooks.

ShopifyQL é a linguagem de consulta da Shopify criada para comércio. As linguagens de consulta são usadas para solicitação e recuperação de dados dos bancos de dados. Use o ShopifyQL com o app Notebooks da Shopify para explorar seu próprio banco de dados comercial e recuperar os dados que oferecem um entendimento mais profundo dos seus negócios.

Para ver uma lista completa de valores e dimensões disponíveis que podem ser usados nas consultas do ShopifyQL Notebooks, consulte o esquema de pedidos e o esquema de produtos.

Nesta página

Visão geral do ShopifyQL

Antes de começar, você precisa saber que os dados da loja ficam armazenados em tabelas de banco de dados, com colunas e linhas definidas. As colunas indicam o tipo de informação, como vendas; já as linhas especificam o valor real do tipo de dado, por exemplo, US$ 2.450 em vendas.

Mas como funciona? Se você quiser recuperar dados em um formato relevante, vai precisar enviar uma consulta ao banco de dados. A consulta é uma pergunta que solicita dados específicos como resposta, e a linguagem de consulta (como a ShopifyQL) é uma forma padronizada de criar essa pergunta com palavras-chave e parâmetros correspondentes. Depois de criar a consulta, basta executá-la para receber uma resposta.

Veja um exemplo de sintaxe da ShopifyQL escrita como consulta. As palavras-chave estão em negrito, e os parâmetros correspondentes entre chaves são marcadores de posição:

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 }

Glossário de termos

Definições de termos da ShopifyQL
Termo Definição
Dimensão Atributo que segmenta dados para classificação e apresentação mais clara. Alguns exemplos comuns: tempo, produtos e lugares. As dimensões são usadas como parâmetros na ShopifyQL.
Palavra-chave Sintaxe da ShopifyQL que funciona como um comando para direcionar a consulta.
Métrica Medida quantitativa para dados. Alguns exemplos comuns: total de vendas, número de pedidos e receita bruta.
Parâmetro Sintaxe da ShopifyQL que identifica os elementos ou informações do banco de dados a serem incluídos na consulta.

Tabela de referência para palavras-chave

Veja as palavras-chave que podem ser usadas para escrever a consulta:

Lista de palavras-chave da ShopifyQL
Palavra-chave Uso funcional
FROM Especifica a tabela de conjunto de dados que vai fornecer os dados.
SHOW Seleciona as colunas a serem extraídas da tabela de conjuntos de dados.
VISUALIZE Exibe dados em uma visualização de linha ou barra.
GROUP BY Agrupa os dados extraídos por uma dimensão ou dimensões de tempo.
WHERE Define as condições que as linhas precisam cumprir para serem selecionadas.
SINCE Mostra dados a partir de um momento específico no passado.
UNTIL Mostra os dados até um determinado momento no passado.
DURING Mostra dados a partir de um momento específico no passado.
COMPARE TO Mostra os dados até um determinado momento no passado.
ORDER BY Especifica a coluna a ser usada para classificar os dados.
LIMIT Limita o número de linhas de dados exibidas.
AS Renomeia uma coluna com um nome de sua escolha.

Escrever consultas com a ShopifyQL

Uma consulta que use a ShopifyQL pode ser básica (para insights de dados gerais) ou abrangente (para insights mais detalhados). Vale lembrar que cada palavra-chave tem uma função específica que compõe a consulta.

ShopifyQL básica: FROM e SHOW

Você só precisa de duas palavras-chave para criar a consulta mais simples em ShopifyQL: FROM e SHOW, exatamente nessa ordem. FROM, seguida pelo parâmetro de nome da tabela, especifica a tabela a ser consultada. SHOW, seguida pelo parâmetro de nome da coluna, especifica as colunas a serem selecionadas.

Por exemplo, é possível listar todos os IDs de produto e os títulos em questão presentes na tabela de vendas com esta consulta:

FROM products
  SHOW product_id, product_title

Agrupar dados: GROUP BY

Para segmentar uma métrica por uma dimensão, como vendas de grupo por região, use a palavra-chave GROUP BY, que pode ser emparelhada com qualquer parâmetro de dimensão.

Por exemplo, uma consulta que agrupa os preços de frete por país e região de faturamento é escrita como:

FROM orders
  SHOW shipping
  GROUP BY billing_country, billing_region

Veja outro exemplo de consulta que usa uma dimensão de tempo para mostrar as vendas líquidas por mês:

FROM orders
  SHOW net_sales
  GROUP BY month

A consulta acima não retorna meses em que não houve vendas. Portanto, se você quiser uma que mostre o período completo, sem interrupções, use o modificador ALL:

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

Sempre especifique também SINCE e UNTIL quando usar o modificador ALL, que funciona apenas com dimensão de tempo.

Dimensões de tempo

Veja as dimensões de tempo que podem ser usadas para agrupar dados:

Dimensões de tempo da ShopifyQL
Operador Uso funcional
Hora Agrupa por hora do dia corrido.
Dias Agrupa por dia corrido.
Semana Agrupa por semana civil.
mês Agrupa por mês civil.
quarter Agrupa por trimestre civil.
Ano Agrupa por ano civil.
hour_of_day Agrupa por 24 horas (1, 2,…, 24).
day_of_week Agrupa por dia da semana (S, T, Q,..., D).
week_of_year Agrupa por semana do ano (1, 2,…, 52).

Filtrar dados: WHERE

Com a palavra-chave WHERE, é possível aplicar um filtro dimensional a uma consulta inteira em ShopifyQL.

Por exemplo, para ver as vendas líquidas agrupadas por mês, mas apenas de uma região específica, a consulta será:

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

Como pode ver no exemplo acima, é possível filtrar o resultado definido com o parâmetro WHERE, mesmo que esse parâmetro não seja incluído nas palavras-chave SHOW ou GROUP BY. Nesse caso, as vendas líquidas são filtradas ao longo de todos os meses para pedidos com endereço de faturamento apenas em Ohio, mesmo que billing_region não seja incluído no conjunto de resultados.

Operadores de comparação

A palavra-chave WHERE usa operadores de comparação para filtrar dados. No exemplo acima, "=" foi usado para especificar que a consulta filtra um determinado valor. No entanto, vale ressaltar que há outros operadores disponíveis para uso:

Operadores de comparação da ShopifyQL
Operador de comparação Uso funcional
= igual a
!= diferente de
< menor que
> maior que
<= menor ou igual a
>= maior ou igual a

Operadores lógicos

Para filtrar ainda mais os dados, use operadores lógicos na consulta. A ShopifyQL conta com algumas opções:

Operadores lógicos da ShopifyQL
Operador lógico Uso funcional
AND Filtra e mostra todas as linhas em que as condições separadas por AND são verdadeiras.
OR Filtra e mostra todas as linhas em que uma das condições separadas por OR é verdadeira.
NOT Filtra e mostra apenas as linhas em que as condições não são verdadeiras, como aquelas que não contêm o valor especificado.

É possível usar diversos filtros com a palavra-chave WHERE, basta adicionar operadores lógicos.

Com esse exemplo de consulta de conjunto de dados, para obter um agrupamento mensal das vendas líquidas para todos os pedidos em que o endereço de faturamento era em Ohio e houve um desconto aplicado, a consulta será:

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

Períodos: SINCE e UNTIL

Para filtrar uma consulta por data ou período de tempo, use SINCE e UNTIL e os parâmetros associados. Lembre-se: essas palavras-chave são únicas, porque só filtram períodos de tempo.

Por exemplo, temos aqui uma consulta para encontrar as vendas líquidas nos últimos 12 meses no Canadá, a partir de hoje:

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

Operadores de ajuste

É possível filtrar por datas específicas ou ajustes de data. Confira os operadores de ajuste da ShopifyQL:

Operadores de ajuste da ShopifyQL
Operador de compensação Uso funcional
-{#}d Número de dias desde o dia de execução da consulta.
-{#}w Número de semanas desde o dia de execução da consulta.
-{#}m Número de meses desde o dia de execução da consulta.
-{#}q Número de trimestres desde o dia de execução da consulta.
-{#}y Número de anos desde o dia de execução da consulta.
aaaa-mm-dd Uma data específica.
hoje Data em que a consulta é executada.
ontem O período anterior de 24 horas a partir do momento em que a consulta é executada.

Filtragem em intervalos de datas: DURING

A palavra-chave DURING simplifica a filtragem em intervalos de datas. É possível usá-la para filtrar os resultados da consulta por um período de tempo conhecido, como um ano civil ou um mês específico, ou por eventos com datas que mudam todo ano, como a Black Friday Cyber Monday. Por exemplo:

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

DURING aceita todos os seguintes operadores de intervalo de datas:

Operadores nomeados de intervalo de datas da ShopifyQL
Operador de intervalo de datas Uso funcional
hoje A data em que a consulta é executada.
ontem O período anterior de 24 horas a partir do momento em que a consulta é executada.
this_week A semana atual do ano civil.
this_month O mês atual do ano civil.
this_quarter O trimestre atual do ano civil.
this_year O ano civil atual.
last_week A semana anterior do ano civil.
last_month O mês anterior do ano civil.
last_quarter O trimestre anterior do ano civil.
last_year O ano civil anterior.
bfcm2022 25 a 28 de novembro de 2022.
bfcm2021 26 a 29 de novembro de 2021.

Comparação entre intervalos de datas: COMPARE TO

Esta palavra-chave permite comparar os dados entre os períodos em DURING e COMPARE TO e aceita todos os operadores nomeados de intervalo de datas listados na seção DURING. O operador usado por COMPARE TO precisa ter o mesmo período de tempo que o usado por DURING. Por exemplo, DURING this_week COMPARE TO last_week é uma combinação válida, mas DURING this_week COMPARE TO last_month não é.

O exemplo a seguir compara as vendas líquidas da Black Friday Cyber Monday de 2022 com a de 2021.

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

Classificação de dados: ORDER BY

É possível especificar como você quer classificar os dados retornados pela consulta com a palavra-chave ORDER BY e os parâmetros associados: ASC (para ordem crescente) e DESC (para ordem decrescente).

É importante destacar que o lojista pode especificar qualquer métrica ou dimensão a ser incluída na consulta com a palavra-chave ORDER BY, até mesmo vários campos.

Por exemplo, essa consulta retorna a soma das vendas líquidas de cada país e região de faturamento, classificada em ordem alfabética inversa por país e região dentro de cada país.

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

A ordem na qual você escreve suas métricas ou dimensões é importante. Se você especificar vários valores para ORDER BY, a classificação será aplicada a cada métrica ou dimensão em um pedido.

Limitar

A palavra-chave LIMIT permite especificar quantas linhas a consulta retorna. É um recurso útil para quando você só quer entender a aparência dos dados em cada coluna. Também é possível combiná-la com ORDER BY para criar listas superiores e inferiores.

Este exemplo usa LIMIT e ORDER BY para criar uma lista dos dez principais produtos de vendas por quantidade nos últimos três meses:

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

Ver consultas em gráficos: VISUALIZE e TYPE

A palavra-chave VISUALIZE permite escrever uma consulta ShopifyQL que exibe dados em barras ou linhas.

Já a palavra-chave TYPE é opcional e precisa ser acompanhada por "line" ou "bar" para que a consulta retorne uma visualização em gráfico de linha ou gráfico de barras, respectivamente. Portanto, se a consulta não incluir TYPE, a ShopifyQL decidirá automaticamente a melhor opção de visualização. E se a consulta não puder ser visualizada conforme o escrito, a ShopifyQL retornará os dados em tabela.

Por exemplo, é possível visualizar a linha de tendência de vendas ao longo do ano passado por mês. Esta consulta retorna um gráfico de série temporal com essas informações, em que uma linha simples representa as vendas brutas, o eixo X indica o mês e o eixo Y indica as vendas brutas:

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

Operadores matemáticos

Com a ShopifyQL, é possível fazer operações aritméticas com as métricas dos dados. Estes são os operadores matemáticos disponíveis:

Operadores de ajuste da ShopifyQL
Operador matemático Uso funcional
+ Soma de dois números.
- Subtração de dois números.
* Multiplicação de dois números.
/ Divisão de dois números.

Por exemplo, esta consulta calcula o valor do pedido para cada região no último ano. Ao usar operadores matemáticos com métricas, não se esqueça de incluir a palavra-chave AS para atribuir um novo nome à nova métrica.

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

Funções

Com as funções da ShopifyQL, é possível agregar colunas semelhantes a tabelas dinâmicas no Microsoft Excel. Nesse procedimento, você combina colunas para criar um novo valor. Estes são os operadores de função disponíveis na versão atual da ShopifyQL:

Operadores de ajuste da ShopifyQL
Operador de função Uso funcional
count() Número de instâncias no conjunto de resultados.
sum() Soma dos valores no conjunto de resultados.
min() Valor mínimo no conjunto de resultados.
max() Valor máximo no conjunto de resultados.
avg() Valor médio no conjunto de resultados.

Só é possível usar as funções sum, min, max e avg com valores numéricos; já count pode ser usado para contar diferentes instâncias de atributos dimensionais. No entanto, vale lembrar que não é permitido usar campos agregados (terminados em _sum, _count ou _percent) na função.

Por exemplo, esta consulta retorna um erro, pois total_sales já foi agregado:

FROM orders
  SHOW sum(total_sales)

Veja esta consulta válida que combina campos agregados com funções agregadas:

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

Essa consulta retorna a soma agregada do valor do ticket médio, a soma das vendas brutas como resultado da função sum. Essas métricas são detalhadas por região de faturamento de todos os pedidos feitos em 2021.

Comentários

É possível usar os comentários para explicar seções das instruções ShopifyQL ou evitar a execução de uma. Vale lembrar que todo o texto do comentário será ignorado durante o tempo de execução.

Comentários de linha única começam com -- e terminam no final da linha.

Comentários com várias linhas começam com /* e terminam com */.

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

Tudo pronto para começar a vender com a Shopify?

Experimente de graça