Una consulta se compone de varias cláusulas: SELECT
, FROM
, WHERE
, ORDER BY
, LIMIT
y PARAMETERS
.
Las cláusulas usan nombres de campo, nombres de recursos, operadores, condiciones y ordenes que se combinan en una única solicitud de consulta.
En términos básicos, para crear una consulta debes hacer lo siguiente:
- Especifica un recurso desde el cual recuperar datos.
- Agrega campos y métricas para definir los datos que deseas mostrar.
- Agregue segmentos para agrupar sus resultados.
- Agrega recursos atribuidos para unir de manera implícita los datos de recursos relacionados.
- Filtra, ordena y limita los resultados.
Cláusula SELECT
La cláusula SELECT
:
- Es una cláusula obligatoria en una consulta.
- Especifica un conjunto de campos para recuperar en la solicitud.
- Toma una lista separada por comas de campos de recursos, columnas personalizadas, variables de Floodlight personalizadas, campos de segmentos y métricas, y muestra los valores en la respuesta.
En esta consulta de ejemplo, se muestra cómo seleccionar atributos del recurso campaign
:
SELECT
campaign.id,
campaign.name
FROM campaign
Varios tipos de campos
Puedes solicitar diferentes tipos de campos en la misma solicitud.
La consulta de ejemplo a continuación muestra una sola consulta con una combinación de lo siguiente:
- Campos de recursos:
campaign.id
,campaign.name
,bidding_strategy.id
ybidding_strategy.name
. - Campos del segmento:
segments.device
ysegments.date
- Campos de métricas:
metrics.impressions
ymetrics.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
Consulta Segmentación para obtener más información sobre la segmentación de tus informes de búsqueda.
Campo de recursos principal
Por lo general, incluirías el campo de recursos principal en la cláusula SELECT
, pero esto es opcional (no obligatorio).
En esta consulta de ejemplo, se usa un campo de recursos principal (ad_group.status
) para filtrar solo los resultados.
SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED
Variables personalizadas de Floodlight
Puedes incluir variables personalizadas de Floodlight en la cláusula SELECT mediante sus ID.
En este ejemplo, la consulta incluye una variable personalizada con el ID 123454321 para el recurso de la campaña.
SELECT
conversion_custom_metrics.id[123454321]
FROM campaign
SELECT
conversion_custom_dimensions.id[123454321]
FROM campaign
Columnas personalizadas
Puedes incluir columnas personalizadas en la cláusula SELECT mediante sus IDs.
En este ejemplo, la consulta incluye una columna personalizada con el ID 12345678 para el recurso de la campaña.
SELECT
custom_columns.id[12345678]
FROM campaign
Consulta cómo obtener IDs de columnas personalizadas.
Campos de métricas
Puedes seleccionar campos de métricas para un recurso determinado sin incluir ningún otro campo del recurso en la cláusula SELECT
.
En esta consulta de ejemplo, se seleccionan las métricas impressions
y clicks
para el recurso campaign
.
SELECT
metrics.impressions,
metrics.clicks
FROM campaign
Consulta metrics
para obtener una lista de los campos de métricas que puedes usar en tus consultas.
Campos de segmentos
Puedes seleccionar campos de segmentos sin especificar los campos de recursos o las métricas que los acompañan en la cláusula SELECT
.
En esta consulta de ejemplo, se segmentan los resultados por dispositivo.
SELECT segments.device
FROM campaign
Consulta segments
para obtener una
lista de los campos de segmentos que puedes usar en tus consultas.
Campos prohibidos
No puedes usar los siguientes campos en la cláusula SELECT
:
- Campos no seleccionables, es decir, campos con el atributo de metadatos
Selectable
marcados comofalse
. - Campos repetidos, es decir, campos con el atributo de metadatos
Repeated
marcados comotrue
- Campos que no están disponibles para el recurso dado en la cláusula
FROM
. No se pueden seleccionar juntos los atributos de algunos recursos. Algunos recursos solo hacen que un subconjunto de todas las métricas y segmentos estén disponibles. - Segmentos o métricas incompatibles Consulta Segmentación para obtener más información.
Consulta la documentación de referencia para obtener detalles sobre dónde encontrar esta información para cada recurso.
Cláusula FROM
La cláusula FROM
:
- Es una cláusula obligatoria para consultas a
SearchAds360Service
(métodosSearch
ySearchStream
). - No se debe incluir en las consultas de
SearchAds360FieldService
. - Especifica el recurso principal que muestra la consulta.
- Solo se puede especificar un recurso.
- Define los campos que puedes usar en todas las demás cláusulas de la consulta.
Recursos atribuidos
Si hay recursos atribuidos disponibles, se unen de forma implícita con el recurso que especifiques en la cláusula FROM
. Solo necesitas agregar sus atributos a la cláusula SELECT
para mostrar sus valores.
Esta consulta de ejemplo muestra el ID del grupo de anuncios y el ID de la campaña, porque campaign
es un recurso atribuido del recurso ad_group
.
SELECT
campaign.id,
ad_group.id
FROM ad_group
Campo resource_name
Siempre se muestra el campo resource_name
del recurso principal en la cláusula FROM
.
En esta consulta de ejemplo, ad_group.resource_name
se incluirá en la respuesta, aunque no esté seleccionado de forma explícita en la consulta:
SELECT ad_group.id
FROM ad_group
El campo resource_name
de un recurso atribuido se muestra cuando se selecciona al menos un campo.
En esta consulta de ejemplo, campaign.resource_name
se incluirá en la respuesta porque campaign.id
está seleccionado:
SELECT
campaign.id,
ad_group.id
FROM ad_group
Cláusula WHERE
La cláusula WHERE
:
- Es una cláusula opcional en una consulta.
- Especifica las condiciones para filtrar y segmentar los datos de la solicitud.
Las condiciones siguen este patrón:
FIELD_NAME
OPERATOR
VALUE
(separadas por espacios en blanco). - Puede incluir varias condiciones separadas por el separador
AND
.
En esta consulta de ejemplo, se muestra cómo usar la cláusula WHERE
para mostrar las métricas impressions
durante un período determinado:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Consulta Segmentación para obtener más información sobre la segmentación de tus informes de búsqueda.
Consulta Períodos para obtener más información sobre cómo especificar períodos en tus consultas.
Filtrar por campo resource_name
Puedes usar el campo resource_name
para ordenar o filtrar los datos.
En esta consulta de ejemplo, se usa el campo campaign.resource_name
para filtrar los resultados por una campaña determinada:
SELECT
campaign.id,
campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
Varias condiciones
Puedes combinar varias condiciones para filtrar tus datos.
Esta consulta de ejemplo solicita la cantidad de métricas clicks
para todas las campañas con métricas impressions
en dispositivos móviles durante los últimos 30 días.
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
Consulta Segmentación para obtener más información sobre cómo segmentar tus informes.
Distinción entre mayúsculas y minúsculas
Cuando filtras por valores de cadena, la distinción entre mayúsculas y minúsculas predeterminada de cada operador desempeña un papel importante a la hora de filtrar correctamente los resultados.
En la siguiente tabla, se muestra la distinción predeterminada entre mayúsculas y minúsculas de cada operador.
Distinción entre mayúsculas y minúsculas predeterminada | |
---|---|
=/!= |
Case sensitive |
IN/NOT IN |
Case sensitive |
LIKE/NOT LIKE |
Case insensitive |
CONTAINS (...) |
Case sensitive |
REGEXP_MATCH/NOT REGEXP_MATCH |
Case sensitive |
Puedes usar el modificador (?i)
para cambiar la sensibilidad predeterminada de REGEXP_MATCH
y NOT REGEXP_MATCH
a fin de que no distinga mayúsculas de minúsculas, por ejemplo:
SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"
Consulta la Referencia de la gramática de consulta a fin de obtener una lista completa de los operadores que puedes usar para filtrar los datos.
Segmentos principales de fechas
Los siguientes campos de segmentos se conocen como segmentos de fechas principales: segments.date
, segments.week
, segments.month
, segments.quarter
y segments.year
.
Puedes usar segmentos de fechas principales en la cláusula WHERE
para especificar una fecha o un período.
En esta consulta de ejemplo, se especifica DURING LAST_30_DAYS
para el campo segments.date
en la cláusula WHERE
:
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Consulta Segmentación > Segmentos de fechas principales para obtener información detallada sobre el uso de los segmentos de fechas principales.
Filtrado prohibido
No se permite filtrar:
- En campos de segmentos no seleccionados, excepto para segmentos de fecha principal
- En los campos de cualquier tipo de mensaje, excepto las primitivas (por ejemplo,
Int64Value
,StringValue
, etcétera) - En los atributos de campos repetidos de cualquier tipo de mensaje, excepto las primitivas (por ejemplo,
Int64Value
,StringValue
, etcétera)
Cláusula ORDER BY
La cláusula ORDER BY
:
- Es una cláusula opcional en una consulta.
- Especifica el orden en el que se muestran los resultados. El orden sigue este patrón:
FIELD_NAME
ORDERING_OPTION
(separados por un espacio en blanco). - Permite dos opciones:
ASC
(ascendente) oDESC
(orden descendente). El valor predeterminado es ascendente.
En esta consulta de ejemplo, se ordenan las campañas por cantidad de clics, en orden descendente (de mayor a menor):
SELECT
campaign.name,
metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC
Pedidos múltiples
Puedes especificar varios campos en la cláusula ORDER BY
mediante una lista separada por comas. Los resultados se ordenarán en la misma secuencia que especifiques en la
consulta.
Esta consulta de ejemplo selecciona los datos del grupo de anuncios y ordena los resultados de forma ascendente por nombre de campaña, luego en orden descendente por cantidad de impresiones y, luego, en orden descendente según la cantidad de clics:
SELECT
campaign.name,
ad_group.name,
metrics.impressions,
metrics.clicks
FROM ad_group
ORDER BY
campaign.name,
metrics.impressions DESC,
metrics.clicks DESC
Orden y límite de combinación
Puedes usar la cláusula ORDER BY
en combinación con la cláusula LIMIT
para definir mejor tus resultados.
Esta consulta de ejemplo muestra las cinco campañas con la mayor cantidad de impresiones en los últimos 30 días:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5
Pedidos prohibidos
No se permite ordenar en los siguientes lugares:
- Por atributos de recursos no seleccionados
- Por métricas no seleccionadas.
- Por segmentos no seleccionados
- Para estos tipos de campos:
MESSAGE
- Campos repetidos
- Atributos de campos repetidos.
Cláusula LIMIT
La cláusula LIMIT
:
- Es una cláusula opcional en una consulta.
- Te permite limitar la cantidad de resultados que muestra la consulta.
Esta cláusula es útil, por ejemplo, si solo te interesa una muestra o un resumen de los resultados.
Esta consulta de ejemplo limita la cantidad 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
La cláusula PARAMETERS
te permite especificar metaparámetros para la solicitud.
Incluir borradores
El parámetro include_drafts
controla si se incluyen las entidades de borrador en los resultados. El valor predeterminado es false
. Configúrala en true
para incluir entidades de borrador.
Esta consulta de ejemplo muestra borradores de campañas y campañas normales:
SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true
Omitir la selección de resource_name
El parámetro omit_unselected_resource_names
te permite excluir el campo resource_name
de todos los recursos que no se solicitan de forma explícita en la cláusula SELECT
. El valor predeterminado es false
. Si configuras este parámetro como true
, te recomendamos que solicites de forma explícita el nombre del recurso principal y cualquier recurso atribuido en la cláusula SELECT
.
Esta consulta de ejemplo no muestra los campos campaign.resource_name
ni customer.resource_name
, ya que no están incluidos en la cláusula SELECT
:
SELECT
campaign.name,
customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true
Esta consulta de ejemplo muestra el campo campaign.resource_name
porque se solicita de forma explícita en la cláusula SELECT
:
SELECT
campaign.name,
campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
Cómo cambiar la moneda que se usa en las métricas
El parámetro metrics_currency
te permite especificar la moneda que se usará cuando se calcule una métrica incluida en la cláusula SELECT
.
La configuración predeterminada es utilizar la moneda local de la cuenta. Si estableces este parámetro, debes usar el código de moneda ISO 4217 de 3 caracteres.
Por ejemplo: USD o EUR.
Esta consulta de ejemplo muestra la métrica cost_micros en la moneda local de la cuenta.
SELECT
campaign.name,
metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
Esta consulta de ejemplo muestra la métrica cost_micros en 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"