Estrutura e cláusulas de consulta

Uma consulta é composta por uma série de cláusulas: SELECT, FROM, WHERE, ORDER BY, LIMIT e PARAMETERS.

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

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

• Especifique um recurso do qual recuperar 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 mesclar implicitamente dados de recursos relacionados.
• Filtrar, ordenar e limitar seus 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.
• Usa 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.

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

• Campos de recurso: 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, o campo de recurso principal é incluído 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 seus IDs.

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

Você pode incluir colunas personalizadas na cláusula SELECT usando seus IDs.

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.

Nesta consulta de exemplo, as métricas impressions e clicks são selecionadas 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 segmentos sem especificar os campos ou métricas de recursos correspondentes 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 você pode usar nas suas consultas.

Campos proibidos

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

• Campos não selecionáveis, ou seja, com o atributo de metadados Selectable marcado como false.
• Campos repetidos, ou seja, 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 disponibilizam apenas um subconjunto de todas as métricas e segmentos.
• Segmentos ou métricas incompatíveis. Para mais informações, consulte Segmentação.

Consulte a Documentação de referência para ver detalhes sobre onde encontrar essas informações para cada recurso.

Cláusula FROM

A cláusula FROM:

• É uma cláusula obrigatória para consultas a SearchAds360Service (ambos os 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 recurso.
• Define os campos que você pode usar em todas as outras cláusulas na consulta.

Observação :há um campo de seleção Sim/Não em cada página de recursos na seção Referência que filtra campos de recursos, segmentos e métricas que não podem ser usados quando um recurso é especificado na cláusula FROM.

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.

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Observação :nem todos os recursos têm recursos atribuídos. A seção Referência inclui detalhes dos recursos atribuídos disponíveis com cada recurso.

Campo resource_name

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

Nesta consulta de exemplo, ad_group.resource_name será incluído na resposta, mesmo que não esteja explicitamente selecionado 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.

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

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

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.

Esta consulta de exemplo mostra como usar a cláusula WHERE para retornar métricas impressions para 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

É possível usar 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 determinada campanha:

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

Várias condições

Você pode combinar várias condições para filtrar seus dados.

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

Observação :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").

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

Você pode 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 Referência de gramática de consultas para ver uma lista completa dos operadores que podem ser usados para filtrar dados.

Principais segmentos de data

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 principal na cláusula WHERE para especificar uma data ou período.

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 principal para informações detalhadas sobre como usar segmentos de data principais.

Filtragem proibida

A filtragem não é permitida:

• Em campos de segmento não selecionados, exceto nos segmentos de data principal.
• 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 é crescente.

Esta consulta de exemplo 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ários pedidos

É 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 que você especificar na consulta.

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

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

Este exemplo de consulta 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 ordenar os seguintes itens:

• Por atributos de recursos não selecionados.
• Por métricas não selecionadas.
• Por segmentos não selecionados.
• Para esses 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 resumo de resultados.

Nesta consulta de exemplo, o número total de resultados é limitado 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 entidades de rascunho são incluídas nos resultados. O padrão é false. Defina-o como true para incluir entidades de rascunho.

Esta consulta de exemplo retorna campanhas de rascunho e campanhas normais:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omitir resource_name não selecionado

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 solicitar 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

Esta consulta de exemplo retorna o campo campaign.resource_name, porque ele é explicitamente solicitado 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 sua cláusula SELECT. O padrão é usar a moeda local da conta. Se você definir esse parâmetro, precisará usar o código de moeda ISO 4217 de três caracteres. Por exemplo: USD, EUR.

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

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"

Saiba mais

• Gramática das consultas