Estrutura da consulta

**Dica**: use o Criador de consultas interativo para criar e validar suas consultas da linguagem de consulta do Google Ads.

As consultas para campos de recursos, segmentos e métricas podem ser enviadas para o GoogleAdsService Search ou SearchStream método. Para criar uma consulta na linguagem de consulta do Google Ads, use a gramática da linguagem. Para uma visão geral da linguagem de consulta do Google Ads, consulte a visão geral da linguagem de consulta do Google Ads. Uma consulta é composta por várias cláusulas:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

As cláusulas usam nomes de campos, nomes de recursos, operadores, condições e ordenações para ajudar você a selecionar os dados corretos. Quando combinadas em uma única consulta, é possível enviar a solicitação para a API Google Ads.

Ponto principal: O GoogleAdsFieldService fornece um catálogo para clientes da linguagem de consulta do Google Ads com metadados sobre todos os campos de recursos, campos de segmentos e métricas, as relações entre eles e a disponibilidade em cada cláusula. Como o conjunto de recursos, campos, segmentos e métricas consultáveis varia entre as principais versões da API, consulte o GoogleAdsFieldService no endpoint da versão da API que você está segmentando. Para mais detalhes, consulte a documentação sobre GoogleAdsField e Diferenças específicas da versão.

Cláusulas

As seções a seguir descrevem a finalidade e a sintaxe de cada cláusula da linguagem de consulta do Google Ads.

SELECT

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

A consulta de exemplo a seguir mostra um exemplo de seleção de atributos para um determinado recurso:

SELECT
  campaign.id,
  campaign.name
FROM campaign

É possível solicitar diferentes tipos de campo em uma única solicitação, por exemplo:

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

• Campos de recursos principais
  • campaign.id
  • campaign.name
• Campos de recursos atribuídos
  • bidding_strategy.id
  • bidding_strategy.name
• Campos de segmentos
  • segments.device
  • segments.date
• Métricas
  • metrics.impressions
  • metrics.clicks

Observação: alguns campos não podem ser selecionados na cláusula SELECT devido às seguintes restrições:

• Consultar campos que não podem ser selecionados. Esses campos têm o atributo de metadados selectable marcado como false.
• Selecionar atributos de campos repetidos. Esses campos têm o atributo de metadados is_repeated marcado como true.
• Selecionar campos que não estão disponíveis para o recurso especificado na cláusula FROM. Os atributos de alguns recursos não podem ser selecionados juntos, e apenas um subconjunto de todas as métricas e segmentos está disponível para o recurso na cláusula FROM.
• Selecionar segmentos ou métricas que não são compatíveis entre si. Para mais informações, consulte Segmentação.

Informações relacionadas às condições anteriores podem ser encontradas na nossa documentação de referência ou no GoogleAdsFieldService.

FROM

A cláusula FROM especifica o recurso principal a ser retornado. O recurso na cláusula FROM define quais campos podem ser usados em todas as outras cláusulas da consulta. Apenas um único recurso pode ser especificado na cláusula FROM. A cláusula FROM é obrigatória em uma consulta para o GoogleAdsService Search ou SearchStream método. No entanto, a cláus0ura FROM deve não ser especificada ao usar GoogleAdsFieldService.

Embora apenas um recurso possa existir na cláusula FROM para uma determinada consulta, os campos de recursos atribuídos também podem estar disponíveis. Esses recursos são unidos implicitamente ao recurso na cláusula FROM. Portanto, basta adicionar os atributos deles à cláusula SELECT para retornar os valores. Nem todos os recursos têm recursos atribuídos. No exemplo a seguir, é possível solicitar o ID do grupo de anúncios e o ID da campanha dos grupos de anúncios:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

O campo resource_name do recurso principal é sempre retornado. No exemplo a seguir, ad_group.resource_name está incluído na resposta, embora não tenha sido selecionado explicitamente na consulta:

SELECT ad_group.id
FROM ad_group

O mesmo vale para recursos atribuídos quando pelo menos um campo é selecionado. Por exemplo, campaign.resource_name está incluído na resposta da consulta a seguir:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Importante: se o recurso na cláusula FROM listar outro recurso como um segment, a seleção de qualquer atributo desse recurso atuará como um segmento.

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, especifique uma ou mais condições separadas por AND. As condições geralmente seguem o padrão field_name Operator value (ou usam BETWEEN value AND value, IS NULL ou IS NOT NULL). A cláusula WHERE é opcional em uma consulta.

O exemplo a seguir usa WHERE para retornar métricas de um determinado período:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

É possível combinar várias condições para filtrar os dados. Este exemplo solicita o número de cliques de todas as campanhas com impressões em dispositivos móveis nos últimos 30 dias:

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = 'MOBILE'
  AND segments.date DURING LAST_30_DAYS

Os segmentos na cláusula WHERE também precisam estar na cláusula SELECT, exceto para os seguintes segmentos de data, chamados de segmentos de data principais:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

Na consulta a seguir, segments.date é selecionado. Como esse segmento é um segmento de data principal, é necessário fornecer um período finito na cláusula WHEREcomposta por segmentos de data principais:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Todos os segmentos que atendem à condição anterior são segments.date, segments.week, segments.month, segments.quarter e segments.year. Se algum desses segmentos for selecionado, pelo menos um deles precisará ser usado na cláusula WHERE.

Para mais detalhes sobre a filtragem de datas, consulte Períodos.

Importante: o separador AND só pode ser usado entre condições de operador (WHERE segments.device != 'DESKTOP' AND segments.device != 'MOBILE') e não em uma única condição de operador (WHERE segments.device != 'DESKTOP' AND 'MOBILE').

Ao filtrar, tenha em mente a diferenciação de maiúsculas e minúsculas do operador. Para mais informações, consulte Diferenciação de maiúsculas e minúsculas.

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

ORDER BY

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

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

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
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 ocorre na mesma sequência especificada na consulta. Por exemplo, nesta consulta que seleciona dados do grupo de anúncios, os resultados são classificados em ordem crescente pelo nome da campanha, depois em ordem decrescente pelo número de impressões e, por fim, em ordem decrescente pelo número de cliques:

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  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ê precisar apenas de um subconjunto de resultados.

Por exemplo, LIMIT pode restringir o número total de resultados da consulta a seguir:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Importante: LIMIT permite truncar os resultados. Para recuperar grandes conjuntos de resultados sem truncar, use GoogleAdsService.SearchStream para transmitir linhas ou paginar com GoogleAdsService.Search.

PARAMETERS

A cláusula PARAMETERS permite especificar parâmetros de metadados para a solicitação. Esses parâmetros podem afetar os tipos de linhas retornadas.

Os seguintes parâmetros de metadados são aceitos:

include_drafts

Defina include_drafts como true para retornar entidades de rascunho. O padrão é false.

Por exemplo, a consulta a seguir busca campanhas de rascunho e campanhas normais:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts = true

omit_unselected_resource_names

Defina omit_unselected_resource_names como true para omitir o nome do recurso de cada tipo de recurso na resposta, a menos que seja solicitado explicitamente na cláusula SELECT. O padrão é false.

Observação: se você planeja usar algum dos objetos retornados para operações de atualização ou remoção, recomendamos definir essa opção como false porque recursos sem nomes de recursos não podem ser usados em operações de mutação. Se você definir essa opção como true, solicite explicitamente os nomes de recursos do recurso principal e de todos os recursos atribuídos que você busca usando a consulta.

Consulta	Recursos retornados
SELECT campaign.name, customer.id FROM campaign	campaign.resource_name customer.resource_name omit_unselected_resource_names é definido como false por padrão. Portanto, todos os campos resource_name são retornados.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Nenhum omit_unselected_resource_names é especificado como true, e nem campaign.resource_name nem customer.resource_name fazem parte da cláusula SELECT.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	campaign.resource_name omit_unselected_resource_names é especificado como true, e campaign.resource_name é solicitado como parte da cláusula SELECT.

Outras regras de linguagem

Além dos exemplos de cada cláusula, a linguagem de consulta do Google Ads oferece suporte aos seguintes comportamentos:

• O campo de recurso principal não é obrigatório na cláusula SELECT de uma consulta. Por exemplo, é possível usar um ou mais campos de recursos principais para filtrar dados sem selecioná-los:

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = 'PAUSED'
  

• As métricas podem ser selecionadas exclusivamente para um determinado recurso. Nenhum outro campo do recurso é obrigatório na consulta:

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  

• Os campos de segmentação podem ser selecionados sem campos de recursos ou métricas:

  SELECT segments.device FROM campaign
  

• O campo resource_name (campaign.resource_name, por exemplo) pode ser usado para filtrar ou ordenar dados:

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'