Estrutura e cláusulas de consulta

Uma consulta é composta por várias cláusulas: SELECT, FROM, WHERE, ORDER BY, LIMIT e PARAMETERS.

As cláusulas usam nomes de campos, nomes de recursos, operadores, condições e ordenações que se combinam em uma única solicitação de consulta.

Em termos básicos, para criar uma consulta, você precisa:

  • Especifique um recurso de onde recuperar os dados.
  • Adicione campos e métricas para definir os dados que você quer retornar.
  • Adicione segmentos para agrupar seus resultados.
  • Adicione recursos atribuídos para unir implicitamente dados de recursos relacionados.
  • Filtre, ordene e limite os resultados.

Cláusula SELECT

A cláusula SELECT:

  • É uma cláusula obrigatória em uma consulta.
  • Especifica um conjunto de campos a serem buscados na solicitação.
  • Recebe uma lista separada por vírgulas de campos de recursos, colunas personalizadas, variáveis personalizadas do Floodlight, campos de segmento e métricas e retorna os valores na resposta.

Esta consulta de exemplo mostra como selecionar atributos do recurso campaign:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Vários tipos de campo

É possível solicitar diferentes tipos de campo na mesma solicitação.

A consulta de exemplo abaixo mostra uma única consulta com uma combinação de:

  • Campos de recursos: campaign.id, campaign.name, bidding_strategy.id e bidding_strategy.name.

  • Campos de segmento: segments.device e segments.date.

  • Campos de métricas: metrics.impressions e metrics.clicks.

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

Consulte Segmentação para saber mais sobre como segmentar seus relatórios de pesquisa.

Campo de recurso principal

Normalmente, você inclui o campo de recurso principal na cláusula SELECT, mas isso é opcional (não obrigatório).

Esta consulta de exemplo usa um campo de recurso principal (ad_group.status) para filtrar apenas os resultados.

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

Variáveis personalizadas do Floodlight

É possível incluir variáveis personalizadas do Floodlight na cláusula SELECT usando os IDs delas.

Neste exemplo, a consulta inclui uma variável personalizada com o ID 123454321 para o recurso de campanha.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Colunas personalizadas

É possível incluir colunas personalizadas na cláusula SELECT usando os IDs delas.

Neste exemplo, a consulta inclui uma coluna personalizada com o ID 12345678 para o recurso de campanha.

SELECT
  custom_columns.id[12345678]
FROM campaign

Saiba como conseguir IDs de colunas personalizadas.

Campos de métricas

É possível selecionar campos de métricas para um determinado recurso sem incluir outros campos do recurso na cláusula SELECT.

Esta consulta de exemplo seleciona as métricas impressions e clicks para o recurso campaign.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Consulte metrics para ver uma lista de campos de métricas que podem ser usados nas consultas.

Campos de segmentos

É possível selecionar campos de segmento sem especificar campos de recursos ou métricas acompanhantes na cláusula SELECT.

Esta consulta de exemplo segmenta os resultados por dispositivo.

SELECT segments.device
FROM campaign

Consulte segments para ver uma lista de campos de segmento que podem ser usados nas consultas.

Campos proibidos

Não é possível usar os seguintes campos na cláusula SELECT:

  • Campos não selecionáveis, ou seja, campos com o atributo de metadados Selectable marcado como false.

  • Campos repetidos, ou seja, campos com o atributo de metadados Repeated marcado como true.

  • Campos que não estão disponíveis para o recurso especificado na cláusula FROM. Não é possível selecionar atributos de alguns recursos juntos. Alguns recursos disponibilizam apenas um subconjunto de todas as métricas e segmentos.

  • Segmentos ou métricas incompatíveis. Consulte Segmentação para mais informações.

Consulte a documentação de referência para saber onde encontrar essas informações de cada recurso.

Cláusula FROM

A cláusula FROM:

  • É uma cláusula obrigatória para consultas a SearchAds360Service (métodos Search e SearchStream).

  • Não deve ser incluído para consultas em SearchAds360FieldService.

  • Especifica o recurso principal que a consulta retorna.

  • Só é possível especificar um único recurso.

  • Define os campos que podem ser usados em todas as outras cláusulas da consulta.

Recursos atribuídos

Se os recursos atribuídos estiverem disponíveis, eles serão unidos implicitamente com o recurso especificado na cláusula FROM. Basta adicionar os atributos deles à cláusula SELECT para retornar os valores.

Essa consulta de exemplo retorna o ID do grupo de anúncios e da campanha porque campaign é um recurso atribuído do recurso ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Campo resource_name

O campo resource_name do recurso principal na cláusula FROM é sempre retornado.

Neste exemplo de consulta, ad_group.resource_name será incluído na resposta mesmo que não esteja selecionado explicitamente na consulta:

SELECT ad_group.id
FROM ad_group

O campo resource_name de um recurso atribuído é retornado quando pelo menos um campo é selecionado.

Neste exemplo de consulta, campaign.resource_name será incluído na resposta porque campaign.id está selecionado:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Cláusula WHERE

A cláusula WHERE:

  • É uma cláusula opcional em uma consulta.

  • Especifica condições para filtrar e segmentar os dados da solicitação. As condições seguem este padrão: FIELD_NAME OPERATOR VALUE (separadas por espaços em branco).

  • Pode incluir várias condições separadas pelo separador AND.

Esta consulta de exemplo mostra como usar a cláusula WHERE para retornar métricas de impressions em um determinado período:

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

Consulte Segmentação para saber mais sobre como segmentar seus relatórios de pesquisa.

Consulte Períodos para saber mais sobre como especificar períodos nas consultas.

Filtrar por campo resource_name

Use o campo resource_name para filtrar ou ordenar dados.

Esta consulta de exemplo usa o campo campaign.resource_name para filtrar os resultados por uma campanha específica:

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

Várias condições

É possível combinar várias condições para filtrar seus dados.

Este exemplo de consulta solicita o número de métricas de clicks para todas as campanhas com métricas de impressions 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

Consulte Segmentação para saber mais sobre como segmentar seus relatórios.

Diferenciação entre maiúsculas e minúsculas

Ao filtrar valores de string, a sensibilidade a maiúsculas e minúsculas padrão de cada operador é importante para filtrar os resultados corretamente.

A tabela a seguir mostra a sensibilidade a maiúsculas e minúsculas padrão de cada operador.

Diferenciação de maiúsculas e minúsculas padrão
=/!= Case sensitive
IN/NOT IN Case sensitive
LIKE/NOT LIKE Case insensitive
CONTAINS (...) Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH Case sensitive

Use o modificador (?i) para mudar a sensibilidade padrão de REGEXP_MATCH e NOT REGEXP_MATCH para não sensível a maiúsculas e minúsculas, por exemplo:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

Consulte Referência da gramática de consulta para ver uma lista completa de operadores que podem ser usados para filtrar seus dados.

Segmentos de data principais

Os seguintes campos de segmentos são conhecidos como segmentos de data principais: segments.date, segments.week, segments.month, segments.quarter e segments.year.

É possível usar segmentos de data principais na cláusula WHERE para especificar um período de data ou hora.

Esta consulta de exemplo especifica DURING LAST_30_DAYS para o campo segments.date na cláusula WHERE:

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

Consulte Segmentação > Segmentos de data principais para informações detalhadas sobre como usar esses segmentos.

Filtragem proibida

Não é permitido filtrar:

  • Em campos de segmento não selecionados, exceto segmentos de data principais.

  • Em campos de qualquer tipo de mensagem, exceto primitivos (por exemplo, Int64Value, StringValue etc.).

  • Em atributos de campos repetidos de qualquer tipo de mensagem, exceto primitivos (por exemplo, Int64Value, StringValue etc.).

Cláusula ORDER BY

A cláusula ORDER BY:

  • É uma cláusula opcional em uma consulta.
  • Especifica a ordem em que os resultados são retornados. A ordem segue este padrão: FIELD_NAME ORDERING_OPTION (separados por um espaço em branco).
  • Permite duas opções: ASC (crescente) ou DESC (decrescente). O padrão é crescente.

Este exemplo de consulta ordena as campanhas por número de cliques em ordem decrescente (maior para menor):

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Várias ordenações

É possível especificar vários campos na cláusula ORDER BY usando uma lista separada por vírgulas. Os resultados serão ordenados na mesma sequência especificada na consulta.

Esta consulta de exemplo seleciona dados de grupo de anúncios e ordena os resultados em ordem crescente por nome da campanha, depois em ordem decrescente por número de impressões e, por fim, em ordem decrescente por 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

Combinar ordenação e limite

É possível usar a cláusula ORDER BY com a cláusula LIMIT para refinar os resultados.

Esta consulta de exemplo retorna as cinco campanhas com o maior número de impressões nos últimos 30 dias:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Pedidos proibidos

Não é permitido:

  • Por atributos de recursos não selecionados.
  • Por métricas não selecionadas.
  • Por segmentos não selecionados.
  • Para estes tipos de campo:
    • MESSAGE
    • Campos repetidos
    • Atributos de campos repetidos.

Cláusula LIMIT

A cláusula LIMIT:

  • É uma cláusula opcional em uma consulta.
  • Permite limitar o número de resultados retornados pela consulta.

Essa cláusula é útil, por exemplo, se você tiver interesse apenas em uma amostra ou um resumo dos resultados.

Esta consulta de exemplo limita o número total de resultados a 50:

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

Cláusula PARAMETERS

A cláusula PARAMETERS permite especificar metaparâmetros para a solicitação.

Incluir rascunhos

O parâmetro include_drafts controla se as entidades de rascunho são incluídas nos resultados. O padrão é false. Defina como true para incluir entidades de rascunho.

Esta consulta de exemplo retorna campanhas de rascunho e normais:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omitir resource_name não selecionados

O parâmetro omit_unselected_resource_names permite excluir o campo resource_name de todos os recursos que não são explicitamente solicitados na cláusula SELECT. O padrão é false. Se você definir esse parâmetro como true, recomendamos que solicite explicitamente o nome do recurso principal e de todos os recursos atribuídos na cláusula SELECT.

Esta consulta de exemplo não retorna o campo campaign.resource_name nem o customer.resource_name porque eles não estão incluídos na cláusula SELECT:

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Esta consulta de exemplo retorna o campo campaign.resource_name porque ele é solicitado explicitamente na cláusula SELECT:

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Mudar a moeda usada nas métricas

Com o parâmetro metrics_currency, é possível especificar a moeda a ser usada ao calcular uma métrica incluída na cláusula SELECT. O padrão é usar a moeda da conta especificada por customer_id. Se você definir esse parâmetro, use o código de moeda de três caracteres ISO 4217. Por exemplo: USD, EUR.

Esta consulta de exemplo retorna a métrica "cost_micros" na moeda da conta especificada pelo customer_id.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

Esta consulta de exemplo retorna a métrica "cost_micros" em pesos chilenos (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

Ativar a expansão da MCC

Quando definido como "true", o parâmetro enable_mcc_expansion permite incluir métricas, campos e segmentos de todas as contas com raiz em customer_id para o recurso na cláusula FROM. A resposta vai usar a moeda do customer_id, a menos que seja especificada explicitamente no parâmetro metrics_currency.

Esta consulta de exemplo retorna bidding_strategy.name, bidding_strategy.type e metrics.cost_micros de todas as contas na hierarquia de contas com raiz em customer_id, porque o parâmetro enable_mcc_expansion está definido como true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

Saiba mais