Estructura de consultas y cláusulas

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 y bidding_strategy.name.
• Campos del segmento: segments.device y segments.date
• Campos de métricas: metrics.impressions y 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

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 como false.
• Campos repetidos, es decir, campos con el atributo de metadatos Repeated marcados como true
• 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étodos Search y SearchStream).
• 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.

Nota: Hay un campo de selección Sí/No en cada página de recursos de la sección Referencia que filtra los campos de recursos, de segmentos y de métricas que no se pueden usar cuando se especifica un recurso en la cláusula FROM.

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

Nota: No todos los recursos tienen recursos atribuidos. En la sección Referencia, se incluyen detalles de los recursos atribuidos disponibles con cada recurso.

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

Nota: Si el recurso en la cláusula FROM enumera otro recurso como segment, seleccionar cualquier atributo de ese recurso actúa como un segmento.

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

Nota: El separador AND solo se puede usar entre las condiciones del operador (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") y no dentro de una sola condición del operador (WHERE segments.device != "DESKTOP" AND "MOBILE").

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) o DESC (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"

Más información

• Gramática de consulta