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
ebidding_strategy.name
. - Campos de segmento:
segments.device
esegments.date
. - Campos de métricas:
metrics.impressions
emetrics.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 comofalse
. - Campos repetidos, ou seja, com o atributo de metadados
Repeated
marcado comotrue
. - 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étodosSearch
eSearchStream
). - 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.
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
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
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
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) ouDESC
(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"