Estructura de consultas y cláusulas

Una búsqueda 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 búsqueda.

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

• Especifica un recurso del que se recuperarán los datos.
• Agrega campos y métricas para definir los datos que deseas mostrar.
• Agrega segmentos para agrupar tus resultados.
• Agrega recursos atribuidos para unir de forma 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 búsqueda.
• 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 devuelve los valores en la respuesta.

En este ejemplo de consulta, 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 los siguientes elementos:

• Campos de recursos: campaign.id, campaign.name, bidding_strategy.id y bidding_strategy.name.

• Campos de segmentación: 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 del recurso principal

Por lo general, incluirías tu campo de recursos principal en la cláusula SELECT, pero esto es opcional (no obligatorio).

En este ejemplo de consulta, 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 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 este ejemplo de consulta, 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 campos de recursos o métricas acompañantes en la cláusula SELECT.

En este ejemplo de consulta, los resultados se segmentan 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 marcado como true.

• Son los campos que no están disponibles para el recurso determinado en la cláusula FROM. No se pueden seleccionar juntos los atributos de algunos recursos. Algunos recursos solo ponen a disposición un subconjunto de todas las métricas y segmentos.

• 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 las búsquedas en SearchAds360Service (métodos Search y SearchStream).

• No se debe incluir para las búsquedas en SearchAds360FieldService.

• Especifica el recurso principal que devuelve la búsqueda.

• Solo se puede especificar un recurso.

• Define los campos que puedes usar en todas las demás cláusulas de la consulta.

Nota: En la sección Referencia de cada página de recursos, 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 hay recursos atribuidos 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 devolver sus valores.

Esta consulta de ejemplo devuelve 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 devuelve el campo resource_name del recurso principal en la cláusula FROM.

En esta consulta de ejemplo, se incluirá ad_group.resource_name en la respuesta, aunque no se haya seleccionado de forma explícita en la consulta:

SELECT ad_group.id
FROM ad_group

El campo resource_name de un recurso atribuido se devuelve cuando se selecciona al menos un campo.

En esta consulta de ejemplo, se incluirá campaign.resource_name en la respuesta porque se seleccionó campaign.id:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

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

Cláusula WHERE

La cláusula WHERE:

• Es una cláusula opcional en una búsqueda.

• 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 este ejemplo de consulta, se muestra cómo usar la cláusula WHERE para devolver métricas de impressions para 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 u ordenar datos.

En esta consulta de ejemplo, se usa el campo campaign.resource_name para filtrar los resultados según una campaña determinada:

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

Múltiples condiciones

Puedes combinar varias condiciones para filtrar tus datos.

Esta consulta de ejemplo solicita la cantidad de métricas de clicks para todas las campañas con métricas de 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 filtras por valores de cadena, la distinción entre mayúsculas y minúsculas predeterminada de cada operador desempeña un papel importante en el filtrado correcto de tus resultados.

En la siguiente tabla, se muestra la configuración predeterminada de distinción 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 que no distingan 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 consultas para obtener una lista completa de los operadores que puedes usar para filtrar tus datos.

Segmentos de fechas 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 un período o una fecha.

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 el filtrado:

• En los campos de segmentos no seleccionados, excepto los segmentos de fecha principales.

• En campos de cualquier tipo de mensaje, excepto los primitivos (por ejemplo, Int64Value, StringValue, etcétera)

• En 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 búsqueda.
• Especifica el orden en 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 (descendente). El valor predeterminado es ascendente.

En este ejemplo de consulta, 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

Múltiples ordenamientos

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 búsqueda.

En este ejemplo de consulta, se seleccionan datos de grupos de anuncios y se ordenan los resultados en orden ascendente por nombre de la campaña, luego en orden descendente por cantidad de impresiones y, por último, 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 ordenamiento 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 devuelve 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 lo siguiente:

• Por atributos de recursos no seleccionados
• Según las métricas no seleccionadas
• Por segmentos no seleccionados
• Para estos tipos de campos:
  • MESSAGE
  • Campos repetidos
  • Son los atributos de los campos repetidos.

Cláusula LIMIT

La cláusula LIMIT:

• Es una cláusula opcional en una búsqueda.
• Te permite limitar la cantidad de resultados que devuelve la búsqueda.

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 parámetros de metadatos para la solicitud.

Incluir borradores

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

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

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omitir 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 como 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 devuelve el campo campaign.resource_name ni el campo 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 devuelve el campo campaign.resource_name, ya que se solicitó 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 tu cláusula SELECT. El valor predeterminado es usar la moneda de la cuenta especificada por customer_id. Si configuras este parámetro, debes usar el código de moneda de 3 caracteres de ISO 4217. Por ejemplo, USD o EUR.

Esta consulta de ejemplo devuelve la métrica cost_micros en la moneda de la cuenta especificada por customer_id.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

Esta consulta de ejemplo devuelve 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 como verdadero, te permite incluir métricas, campos y segmentos de todas las cuentas raíz en customer_id para el recurso en la cláusula FROM. La respuesta usará la moneda de customer_id, a menos que se especifique explícitamente 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 devuelve bidding_strategy.name, bidding_strategy.type y metrics.cost_micros de todas las cuentas de la jerarquía de cuentas cuya raíz es customer_id, ya que el parámetro enable_mcc_expansion está establecido en 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