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 campo, nomes de recurso, 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ê:

  • Especifique um recurso para extrair dados.
  • Adicione campos e métricas para definir os dados que você quer retornar.
  • Adicione segmentos para agrupar os resultados.
  • Adicione recursos atribuídos para mesclar 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.

Este exemplo de consulta 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.

O 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 segmentos: 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ê incluiria o campo de recurso principal na cláusula SELECT, mas isso é opcional (não obrigatório).

Este exemplo de consulta 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 da 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 da 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.

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

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

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

Campos de segmentos

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

Este exemplo de consulta segmenta os resultados por dispositivo.

SELECT segments.device
FROM campaign

Consulte segments para ver uma lista de campos de segmentos 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. Os atributos de alguns recursos não podem ser selecionados juntos. Alguns recursos só disponibilizam 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 para 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 em consultas para SearchAds360FieldService.
  • Especifica o recurso principal retornado pela consulta.
  • 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 implicitamente associados ao recurso especificado na cláusula FROM. Basta adicionar os atributos à cláusula SELECT para retornar os valores.

Este exemplo de consulta 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 seja 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 (separados por espaços em branco).
  • Pode incluir várias condições separadas pelo separador AND.

Este exemplo de consulta mostra como usar a cláusula WHERE para retornar métricas impressions por 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 Intervalos de datas para saber mais sobre como especificar intervalos de datas nas consultas.

Filtrar por campo resource_name

Use o campo resource_name para filtrar ou ordenar dados.

Este exemplo de consulta usa o campo campaign.resource_name para filtrar os resultados por uma determinada campanha:

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 os dados.

Este exemplo de consulta solicita o número de métricas clicks para todas as campanhas com métricas 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 diferenciação entre maiúsculas e minúsculas padrão de cada operador desempenha um papel importante na filtragem correta dos resultados.

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

Diferenciação entre 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

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

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

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

Segmentos de data principais

Os campos de segmentos a seguir 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.

Este exemplo de consulta 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 os segmentos de data principais.

Filtragem proibida

A filtragem não é permitida:

  • Em campos de segmentos não selecionados, exceto segmentos de datas 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 ordenação 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 é ascendente.

Este exemplo de consulta ordena as campanhas por número de cliques em ordem decrescente (do maior para o 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.

Este exemplo de consulta seleciona dados do grupo de anúncios e organiza os resultados 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

Combinar ordenação e limite

É possível usar a cláusula ORDER BY em combinação com a cláusula LIMIT para refinar seus resultados.

Este exemplo de consulta retorna as cinco campanhas com as maiores 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

Pedido proibido

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ê só tem interesse em uma amostra ou um resumo dos resultados.

Este exemplo de consulta 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.

Este exemplo de consulta retorna campanhas normais e de rascunho:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omitir resource_name desmarcado

O parâmetro omit_unselected_resource_names permite excluir o campo resource_name de todos os recursos que não são solicitados explicitamente 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 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

Este exemplo de consulta 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

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

Este exemplo de consulta retorna a métrica cost_micros na moeda local da conta.

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

Este exemplo de consulta 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"

Saiba mais