Estrutura da consulta

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

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT

As cláusulas usam nomes de campos, nomes de tabelas, operadores, condições e ordens para ajudar você a selecionar os dados desejados. Depois de combinadas em uma única consulta, é possível fazer uma solicitação usando a API Content for Shopping do Google. Vamos ver 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 usa uma lista separada por vírgulas de campos e métricas de segmento, retornando os valores na resposta. A cláusula SELECT é obrigatória em uma consulta.

Veja a seguir um exemplo de consulta que seleciona 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 segmento

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

Informações relacionadas à condição acima podem ser encontradas em 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 especificada. Somente uma tabela pode ser especificada na cláusula FROM. No momento, apenas 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 os dados da solicitação. Ao usar a cláusula WHERE, uma ou mais condições podem ser especificadas 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 uso na cláusula WHERE. A cláusula WHERE é obrigatória em uma consulta porque você precisa sempre especificar o período para o retorno dos dados de desempenho.

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

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. Este exemplo vai retornar o número de cliques por oferta para o programa SHOPPING_ADS em que o número de cliques é maior que 100 em um determinado 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 abaixo, você vai perceber que segments.date foi selecionado. Independentemente de você selecionar segments.date, um período finito na cláusula WHERE sempre precisa ser fornecido para recuperar dados de desempenho.

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

Ao filtrar, é importante ter em mente a diferenciação entre maiúsculas e minúsculas do seu operador.

Para ver uma lista completa de operadores, consulte a gramática de linguagem.

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 em um nome de campo. Cada ordem é especificada como uma field_name seguida por ASC ou DESC. Se ASC e DESC não forem especificados, a ordem será ASC por padrão. 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 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 por número de impressões e, depois, em ordem decrescente por 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 a serem retornados. Isso é útil se você tiver interesse apenas em um resumo.

Por exemplo, LIMIT pode ser usado para restringir o número total de resultados para a 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
Próxima
Períodos