Estrutura da consulta

As consultas dos 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, você precisa primeiro redigir a consulta usando a gramática da linguagem. Uma consulta é composta por uma série de 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. Uma vez combinada em uma única consulta, é possível fazer uma solicitação usando a Google Content API for Shopping. 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.

Aqui está um exemplo de consulta que seleciona métricas de clique 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’

  • Segmentar campos

    • 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 em que 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 em questão. Apenas uma tabela pode ser especificada na cláusula FROM. No momento, somente a tabela MerchantPerformanceView é compatível. A cláusula FROM é obrigatória em uma consulta para o 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, 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 serem usados na cláusula WHERE. A cláusula WHERE é obrigatória em uma consulta porque você precisa sempre especificar o período em que quer que seus dados de desempenho sejam retornados.

Veja 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 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 a seguir, você vai notar que segments.date foi selecionado. Independentemente de você selecionar segments.date, um período finito na cláusula WHERE sempre precisará ser fornecido para recuperar os dados de performance.

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

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

ORDER BY

Com a cláusula ORDER BY, você 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 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 pelo número de impressões e, por fim, 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 a serem retornados. Isso é útil se você estiver interessado 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