Estrutura da consulta

As consultas de campos de métrica e segmento podem ser enviadas ao método reports.search. Para criar uma consulta na linguagem de consulta do Merchant Center, primeiro você precisa compor a consulta usando a gramática da linguagem. Uma consulta é composta por várias cláusulas:

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT

As cláusulas usam nomes de campos, nomes de tabelas, operadores, condições e ordenações para ajudar você a selecionar os dados desejados. Depois de combinadas em uma única consulta, uma solicitação pode ser feita usando a Google Content API for Shopping. Vamos conferir como cada cláusula pode ser usada.

Cláusulas

SELECT

A cláusula SELECT especifica um conjunto de campos a serem buscados na solicitação. SELECT recebe uma lista de campos e métricas de segmento separados por vírgulas, retornando os valores na resposta. A cláusula SELECT é obrigatória em uma consulta.

Confira um exemplo de consulta que seleciona as métricas de cliques de uma determinada tabela:

SELECT
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’

Também é possível consultar diferentes tipos de campo em uma única solicitação:

SELECT
  segments.date,
  segments.program,
  metrics.impressions,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’

  • Campos de segmentos

    • segments.date
    • segments.program

  • Métricas

    • metrics.impressions
    • metrics.clicks

Alguns campos não são permitidos na cláusula SELECT devido à seguinte restrição:

  • Consultar campos de segmento sem pelo menos um campo de métrica.

Confira mais informações sobre a condição acima nos nossos documentos de referência.

FROM

A cláusula FROM especifica a tabela de onde os dados serão buscados na solicitação. A tabela na cláusula FROM define quais campos podem ser usados por todas as outras cláusulas para a consulta. Apenas uma tabela pode ser especificada na cláusula FROM. No momento, só a tabela MerchantPerformanceView é compatível. A cláusula FROM é obrigatória em uma consulta ao método search no serviço reports.

WHERE

A cláusula WHERE especifica as condições a serem aplicadas ao filtrar dados para a solicitação. Ao usar a cláusula WHERE, é possível especificar uma ou mais condições usando AND para separá-las. Cada condição precisa seguir o padrão field_name Operator value. Qualquer campo de segmentos pode ser usado na cláusula WHERE, mas os campos de métricas precisam ser especificados na cláusula SELECT para serem usados na cláusula WHERE. A cláusula WHERE é obrigatória em uma consulta, porque você precisa sempre especificar o período de datas em que quer que os dados de performance sejam retornados.

Confira a seguir um exemplo de como usar WHERE para retornar métricas de um determinado período de tempo:

SELECT
  segments.offer_id,
  metrics.impressions
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’

É possível combinar várias condições para filtrar os dados. Esse exemplo vai retornar o número de cliques por oferta do programa SHOPPING_ADS em que os cliques > 100 no período de 30 dias.

SELECT
  segments.offer_id,
  segments.program,
  metrics.clicks
FROM MerchantPerformanceView
WHERE metrics.clicks > 100
  AND segments.program = SHOPPING_ADS
  AND segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’;

Na consulta a seguir, você vai notar que segments.date foi selecionado. Independentemente de você selecionar segments.date, um período de tempo finito na cláusula WHERE sempre precisa ser fornecido para recuperar dados de performance.

SELECT
  segments.date,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’

Ao filtrar, é importante considerar a diferenciação entre maiúsculas e minúsculas do operador.

Para conferir uma lista completa de operadores, consulte a gramática do idioma.

ORDER BY

A cláusula ORDER BY especifica a ordem em que os resultados serão retornados. Isso permite organizar os dados em ordem crescente ou decrescente com base no nome de um campo. Cada ordenação é especificada como field_name seguida por ASC ou DESC. Se nem ASC nem DESC forem especificados, a ordem padrão será ASC. Somente os campos especificados na cláusula SELECT podem ser usados na cláusula ORDER BY. A cláusula ORDER BY é opcional em uma consulta.

A consulta a seguir ordena as linhas retornadas pelo número de cliques, do maior para o menor:

SELECT
  segments.offer_id,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’
ORDER BY metrics.clicks DESC

É possível especificar vários campos na cláusula ORDER BY usando uma lista separada por vírgulas. A ordenação vai ocorrer na mesma sequência especificada na consulta. Por exemplo, nesta consulta, os resultados serão classificados em ordem crescente por offer_id, depois em ordem decrescente pelo número de impressões e, em seguida, em ordem decrescente pelo número de cliques:

SELECT
  segments.offer_id,
  metrics.impressions,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’
ORDER BY
  segments.offer_id,
  metrics.impressions DESC,
  metrics.clicks DESC

LIMIT

A cláusula LIMIT permite especificar o número de resultados que serão retornados. Isso é útil se você só quer um resumo.

Por exemplo, LIMIT pode ser usado para restringir o número total de resultados da seguinte consulta:

SELECT
  segments.program,
  segments.offer_id,
  metrics.impressions
FROM MerchantPerformanceView
WHERE segments.date BETWEEN ‘2020-08-01’ AND ‘2020-08-31’
ORDER BY metrics.impressions DESC
LIMIT 50
Anterior
Gramática das consultas
Avançar
Períodos