Usar ShopifyQL no 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.

Visão geral da 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.
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.

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 de cada país e região de faturamento, classificada em ordem alfabética inversa por país de faturamento e por região de faturamento 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.


Limite

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.

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

Experimente de graça