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 campos, nombres de recursos, operadores, condiciones y ordenamientos que se combinan en una sola solicitud de consulta.

En términos básicos, para crear una consulta, debes hacer lo siguiente:

• Especifica un recurso desde el que recuperar datos.
• Agrega campos y métricas para definir los datos que deseas mostrar.
• Agrega segmentos para agrupar tus resultados.
• Agrega recursos atribuidos para unir implícitamente 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 personalizadas de Floodlight, 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.

En la siguiente consulta de ejemplo, se 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 de 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 cómo segmentar tus informes de búsqueda.

Campo de recurso principal

Por lo general, incluirías tu 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 recurso 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 con sus IDs.

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 con 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 ver una lista de los campos de métricas que puedes usar en tus consultas.

Campos de segmentos

Puedes seleccionar campos de segmentos sin especificar campos de recursos o métricas que los acompañen en la cláusula SELECT.

En este ejemplo, la consulta segmenta 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 marcado como false
• Campos repetidos, es decir, campos con el atributo de metadatos Repeated marcados como true
• Son los campos que no están disponibles para el recurso determinado en la cláusula FROM. Los atributos de algunos recursos no se pueden seleccionar juntos. Algunos recursos solo hacen disponible un subconjunto de todas las métricas y segmentos.
• Métricas o segmentos 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 las consultas a SearchAds360Service (métodos Search y SearchStream).
• No se debe incluir para las consultas a SearchAds360FieldService.
• Especifica el recurso principal que muestra la consulta.
• Solo se puede especificar un solo recurso.
• Define los campos que puedes usar en todas las demás cláusulas de la consulta.

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

Recursos atribuidos

Si los recursos atribuidos están disponibles, se unen de forma implícita con el recurso que especificas en la cláusula FROM. Solo debes 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, ya que 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. La sección Referencia incluye 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 se seleccione 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 se seleccionó campaign.id:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Nota: Si el recurso en la cláusula FROM enumera otro recurso como un 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 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 cómo segmentar 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 filtrar o ordenar 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.

En esta consulta de ejemplo, se 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 condiciones de operador (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") y no dentro de una sola condición de 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 se filtran valores de cadena, la distinción entre mayúsculas y minúsculas predeterminada de cada operador juega un papel importante en filtrar correctamente los resultados.

En la siguiente tabla, se muestra la distinción mayúsculas/minúsculas predeterminada 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 mayúsculas y minúsculas, por ejemplo:

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

Consulta la referencia de la gramática de consultas para obtener una lista completa de los operadores que puedes usar para filtrar tus datos.

Segmentos de fecha principales

Los siguientes campos de segmentos se conocen como segmentos de fecha principales: segments.date, segments.week, segments.month, segments.quarter y segments.year.

Puedes usar segmentos de fecha principales en tu 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 fecha principales para obtener información detallada sobre el uso de los segmentos de fecha principales.

Filtrado prohibido

No se permite filtrar lo siguiente:

• En los campos de segmentos no seleccionados, excepto en los segmentos de fecha principales.
• En campos de cualquier tipo de mensaje, excepto primitivos (por ejemplo, Int64Value, StringValue, etcétera).
• En los atributos de campos repetidos de cualquier tipo de mensaje, excepto los primitivos (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 que se muestran los resultados. El orden sigue este patrón: FIELD_NAME ORDERING_OPTION (separado por un espacio en blanco).
• Permite dos opciones: ASC (ascendente) o DESC (descendente). El valor predeterminado es ascendente.

En esta consulta de ejemplo, se ordenan las campañas por cantidad de clics en orden descendente (de la más alta a la más baja):

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Varios pedidos

Puedes especificar varios campos en la cláusula ORDER BY con una lista separada por comas. Los resultados se ordenarán en la misma secuencia que especifiques en la consulta.

En esta consulta de ejemplo, se seleccionan los datos del grupo de anuncios y se ordenan los resultados en orden ascendente por nombre de campaña, luego en orden descendente por cantidad de impresiones y, luego, en orden descendente por 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

Combina el orden y el límite

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 las impresiones más altas 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 el ordenamiento:

• 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 un muestreo 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.

Cómo incluir borradores

El parámetro include_drafts controla si se incluyen entidades de borrador en los resultados. El valor predeterminado es false. Establece el valor en true para incluir entidades de borrador.

Esta consulta de ejemplo muestra tanto las campañas de borrador como las campañas normales:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omite resource_name sin seleccionar

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 tu cláusula SELECT. El valor predeterminado es false. Si configuras este parámetro en true, te recomendamos que solicites de forma explícita el nombre del recurso principal y cualquier recurso atribuido en tu cláusula SELECT.

Esta consulta de ejemplo no muestra el campo campaign.resource_name ni customer.resource_name, ya que no se incluyen 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, ya que 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

Cambia 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 tu cláusula SELECT. La opción predeterminada es usar la moneda local de la cuenta. Si configuras este parámetro, debes usar el código de moneda de 3 caracteres ISO 4217. 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"

Habilita la expansión de MCC

El parámetro enable_mcc_expansion, cuando se establece en verdadero, te permite incluir métricas, campos y segmentos de login_customer_id y todas las cuentas de publicación debajo, para el recurso en la cláusula FROM. La respuesta usará la moneda de login_customer_id, a menos que se especifique de forma explícita en el parámetro metrics_currency.

Nota: El parámetro enable_mcc_expansion solo es compatible con bidding_strategy. Con el tiempo, la API incluirá recursos adicionales.

Esta consulta de ejemplo muestra bidding_strategy.name, bidding_strategy.type y metrics.cost_micros de login_customer_id y todas las cuentas de publicación debajo, porque el parámetro enable_mcc_expansion está configurado como true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

Más información

• Gramática de consulta