Estructura de una consulta

Sugerencia: Usa el Compilador de consultas interactivo para crear y validar tus consultas en el lenguaje de consulta de Google Ads.

Las consultas de campos de recursos, segmentos y métricas se pueden enviar al método GoogleAdsService Search o SearchStream. Para crear una consulta en el lenguaje de consulta de Google Ads, usa la gramática del lenguaje. Para obtener una descripción general del lenguaje de consulta de Google Ads, consulta la descripción general del lenguaje de consulta de Google Ads. Una consulta se compone de varias cláusulas:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

Las cláusulas usan nombres de campos, nombres de recursos, operadores, condiciones y ordenamientos para ayudarte a seleccionar los datos correctos. Cuando se combinan en una sola consulta, puedes enviar la solicitud a la API de Google Ads.

Punto clave: El GoogleAdsFieldService proporciona un catálogo para los clientes del lenguaje de consulta de Google Ads con metadatos sobre todos los campos de recursos, los campos de segmentos y las métricas, sus relaciones entre sí y su disponibilidad en cada cláusula. Debido a que el conjunto de recursos, campos, segmentos y métricas que se pueden consultar varía entre las versiones principales de la API, consulta GoogleAdsFieldService en el extremo de la versión de la API a la que te orientas. Para obtener más detalles, consulta la documentación de GoogleAdsField y Diferencias específicas de la versión.

modelo de la UE

En las siguientes secciones, se describe el propósito y la sintaxis de cada cláusula del lenguaje de consulta de Google Ads.

SELECT

La cláusula SELECT especifica un conjunto de campos que se recuperarán en la solicitud. SELECT toma una lista separada por comas de campos de recursos, campos de segmentos y métricas, y devuelve los valores en la respuesta. La cláusula SELECT es obligatoria en una consulta.

En la siguiente consulta de ejemplo, se muestra cómo seleccionar atributos para un recurso determinado:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Puedes solicitar diferentes tipos de campos en una sola solicitud, por ejemplo:

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

• Campos de recursos principales
  • campaign.id
  • campaign.name
• Campos de recursos atribuidos
  • bidding_strategy.id
  • bidding_strategy.name
• Campos de segmento
  • segments.device
  • segments.date
• Métricas
  • metrics.impressions
  • metrics.clicks

Nota: Algunos campos no se pueden seleccionar en la cláusula SELECT debido a las siguientes restricciones:

• Consultar campos que no se pueden seleccionar Estos campos tienen su atributo de metadatos selectable marcado como false.
• Selecciona atributos de campos repetidos. Estos campos tienen su atributo de metadatos is_repeated marcado como true.
• Seleccionar 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, y solo un subconjunto de todas las métricas y los segmentos está disponible para el recurso en la cláusula FROM.
• Seleccionar segmentos o métricas que no son compatibles entre sí Para obtener más información, consulta Segmentación.

La información relacionada con las condiciones anteriores se puede encontrar en nuestra documentación de referencia o en GoogleAdsFieldService.

FROM

La cláusula FROM especifica el recurso principal que se devolverá. El recurso en la cláusula FROM define qué campos se pueden usar en todas las demás cláusulas para la consulta determinada. Solo se puede especificar un recurso en la cláusula FROM. La cláusula FROM es obligatoria en una consulta al método GoogleAdsService Search o SearchStream. Sin embargo, la cláusula FROM no debe especificarse cuando se usa GoogleAdsFieldService.

Si bien solo puede existir un recurso en la cláusula FROM para una consulta determinada, los campos de los recursos atribuidos también pueden estar disponibles. Estos recursos se unen de forma implícita al recurso en la cláusula FROM, por lo que solo necesitas agregar sus atributos a la cláusula SELECT para devolver sus valores. No todos los recursos tienen recursos atribuidos. En el siguiente ejemplo, puedes solicitar el ID del grupo de anuncios y el ID de la campaña de los grupos de anuncios:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Siempre se devuelve el campo resource_name del recurso principal. En el siguiente ejemplo, ad_group.resource_name se incluye en la respuesta, a pesar de que no se selecciona de forma explícita en la consulta:

SELECT ad_group.id
FROM ad_group

Lo mismo ocurre con los recursos atribuidos cuando se selecciona al menos un campo. Por ejemplo, campaign.resource_name se incluye en la respuesta de la siguiente consulta:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

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

WHERE

La cláusula WHERE especifica las condiciones que se deben aplicar cuando se filtran los datos de la solicitud. Cuando uses la cláusula WHERE, especifica una o más condiciones separadas por AND. Por lo general, las condiciones siguen el patrón field_name Operator value (o usan BETWEEN value AND value, IS NULL o IS NOT NULL). La cláusula WHERE es opcional en una consulta.

En el siguiente ejemplo, se usa WHERE para devolver métricas de un período determinado:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Puedes combinar varias condiciones para filtrar los datos. En este ejemplo, se solicita la cantidad de clics de todas las campañas con impresiones en dispositivos móviles en 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

Los segmentos de la cláusula WHERE también deben estar en la cláusula SELECT, excepto los siguientes segmentos de fecha, que se denominan segmentos de fecha principales:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

En la siguiente consulta, se selecciona segments.date. Debido a que este segmento es un segmento de fecha principal, debes proporcionar un período finito en la cláusula WHERE compuesta por segmentos de fecha principales:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Todos los segmentos que cumplen con la condición anterior son segments.date, segments.week, segments.month, segments.quarter y segments.year. Si se selecciona alguno de estos segmentos, se debe usar al menos uno de ellos en la cláusula WHERE.

Para obtener más detalles sobre el filtrado por fecha, consulta Períodos.

Punto clave: 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').

Cuando filtres, ten en cuenta la distinción entre mayúsculas y minúsculas de tu operador. Para obtener más información, consulta Distinción entre mayúsculas y minúsculas.

Para obtener una lista completa de los operadores, consulta la gramática del lenguaje.

ORDER BY

La cláusula ORDER BY especifica el orden en que se devuelven los resultados. Esto te permite organizar los datos en orden ascendente o descendente según el nombre de un campo. Cada orden se especifica como un field_name seguido de ASC o DESC. Si no se especifica ASC ni DESC, el orden predeterminado es ASC. La cláusula ORDER BY es opcional en una consulta.

La siguiente consulta ordena las campañas devueltas por la cantidad de clics, de mayor a menor:

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

Puedes especificar varios campos en la cláusula ORDER BY con una lista separada por comas. El orden se produce en la misma secuencia que se especifica en la consulta. Por ejemplo, en esta consulta que selecciona datos del grupo de anuncios, los resultados se ordenan de forma ascendente por nombre de campaña, luego de forma descendente por cantidad de impresiones y, por último, de forma 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

LIMIT

La cláusula LIMIT te permite especificar la cantidad de resultados que se mostrarán. Esto es útil si solo necesitas un subconjunto de resultados.

Por ejemplo, LIMIT puede restringir la cantidad total de resultados para la siguiente consulta:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Punto clave: LIMIT te permite truncar los resultados. Para recuperar conjuntos de resultados grandes sin truncar, usa GoogleAdsService.SearchStream para transmitir filas o paginar con GoogleAdsService.Search.

PARÁMETROS

La cláusula PARAMETERS te permite especificar metaparámetros para la solicitud. Estos parámetros pueden afectar los tipos de filas que se devuelven.

Se admiten los siguientes metaparámetros:

include_drafts

Establece include_drafts en true para devolver entidades de borrador. La configuración predeterminada es false.

Por ejemplo, la siguiente consulta recupera las campañas de borrador junto con las campañas normales:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts = true

omit_unselected_resource_names

Establece omit_unselected_resource_names en true para omitir el nombre de cada tipo de recurso en la respuesta, a menos que se solicite de forma explícita en la cláusula SELECT. La configuración predeterminada es false.

Nota: Si planeas usar cualquiera de los objetos mostrados para operaciones de actualización o eliminación, te recomendamos que establezcas esta opción en false, ya que los recursos sin nombres de recursos no se pueden usar en operaciones de mutación. Si configuras esta opción como true, asegúrate de solicitar de forma explícita los nombres de los recursos tanto del recurso principal como de los recursos atribuidos que recuperes con la consulta.

Consulta	Recursos devueltos
SELECT campaign.name, customer.id FROM campaign	campaign.resource_name customer.resource_name omit_unselected_resource_names se establece de forma predeterminada en false, por lo que se devuelven todos los campos resource_name.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Ninguno omit_unselected_resource_names se especifica como true, y ni campaign.resource_name ni customer.resource_name forman parte de la cláusula SELECT.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	campaign.resource_name omit_unselected_resource_names se especifica como true, y campaign.resource_name se solicita como parte de la cláusula SELECT.

Reglas de idioma adicionales

Además de los ejemplos de cada cláusula, el lenguaje de consulta de Google Ads admite los siguientes comportamientos:

• El campo de recurso principal no es obligatorio en la cláusula SELECT para una consulta. Por ejemplo, puedes usar uno o más campos de recursos principales para filtrar datos sin seleccionarlos:

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = 'PAUSED'
  

• Las métricas se pueden seleccionar exclusivamente para un recurso determinado; no se requieren otros campos del recurso en la consulta:

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  

• Los campos de segmentación se pueden seleccionar sin ningún campo de recurso o métrica que los acompañe:

  SELECT segments.device FROM campaign
  

• El campo resource_name (campaign.resource_name, por ejemplo) se puede usar para filtrar o ordenar datos:

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