Estructura de la consulta

Las consultas para los campos de recursos, segmentos y métricas se pueden enviar a los métodos GoogleAdsService Search o SearchStream. Para crear una consulta en el lenguaje de consulta de Google Ads, deberás hacerlo con la gramática del lenguaje. Una consulta consta de varias cláusulas:

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

Las cláusulas usan nombres de campo, nombres de recursos, operadores, condiciones y ordenamientos para ayudarte a seleccionar los datos correctos. Una vez que se combina en una sola consulta, se puede realizar la solicitud mediante la API de Google Ads.

Cláusulas

ondemand_videoVideo: compatibilidad con campos de GAQL

SELECCIONAR

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

La consulta de muestra que aparece a continuación muestra un ejemplo de cómo seleccionar atributos para un recurso determinado:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Puedes solicitar diferentes tipos de campo 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

  • campaign.id
  • campaign.name

• Campos de recursos

  • bidding_strategy.id
  • bidding_strategy.name

• Segmentar campos

  • segments.device
  • segments.date

• Métricas

  • metrics.impressions
  • metrics.clicks

Es posible que no se permitan algunos campos en la cláusula SELECT debido a las siguientes restricciones:

• Consulta campos que no se pueden seleccionar Estos campos tendrán el atributo de metadatos Selectable marcado como false.
• Selección de atributos de campos repetidos Estos campos tendrán el atributo de metadatos isRepeated marcado como true.
• Selecciona campos que no están disponibles para el recurso dado en la cláusula FROM. Los atributos de algunos recursos no se pueden seleccionar juntos, y solo un subconjunto de todas las métricas y segmentos estará 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 sobre este tema, consulta la sección de segmentación.

Puedes encontrar información relacionada con las condiciones anteriores en nuestros documentos de referencia o en GoogleAdsFieldService.

FROM

La cláusula FROM especifica el recurso principal que se mostrará. El recurso en la cláusula FROM define qué campos se pueden usar en todas las otras cláusulas para una consulta determinada. Solo se puede especificar un solo recurso en la cláusula FROM. La cláusula FROM es obligatoria en una consulta a los métodos GoogleAdsService Search o SearchStream. Sin embargo, no se debe especificar cuando se usa GoogleAdsFieldService.

Si bien solo puede haber 1 recurso en la cláusula FROM para una consulta determinada, los campos de Recursos atribuidos también pueden estar disponibles. Estos recursos se unen de forma implícita con el recurso en la cláusula FROM, por lo que solo debes agregar sus atributos a la cláusula SELECT para mostrar sus valores. No todos los recursos tienen recursos atribuidos. En el siguiente ejemplo, puede 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 muestra el campo resource_name del recurso principal. En el siguiente ejemplo, ad_group.resource_name se incluirá en la respuesta a pesar de que no se haya seleccionado de forma explícita en la consulta:

SELECT ad_group.id
FROM ad_group

Lo mismo sucede con otros recursos cuando se selecciona al menos un campo. Por ejemplo, campaign.resource_name se incluirá en la respuesta de la siguiente consulta:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

La cláusula WHERE especifica las condiciones que se aplicarán cuando se filtren los datos para la solicitud. Cuando usas la cláusula WHERE, se pueden especificar una o más condiciones mediante AND para separarlas. Cada condición debe seguir el patrón field_name Operator value. La cláusula WHERE es opcional en una consulta.

El siguiente es un ejemplo del uso de WHERE para mostrar 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 solicitará la cantidad de clics para 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 en la cláusula WHERE deben estar en la cláusula SELECT, con los siguientes segmentos de fecha, que se conocen como segmentos de fecha principales, con excepción de los siguientes:

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

En la siguiente consulta, ten en cuenta que segments.date está seleccionado. Debido a que este segmento es un segmento de fecha principal, requiere que se proporcione un período finito compuesto por segmentos de fecha principales en la cláusula WHERE.

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

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

Cuando filtras, es importante tener en cuenta la distinción entre mayúsculas y minúsculas del operador. Consulta Distinción entre mayúsculas y minúsculas para obtener más detalles.

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

ORDER BY

La cláusula ORDER BY especifica el orden en el que se deben mostrar 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 mostradas según la cantidad de clics del más alto al más bajo:

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

Puedes especificar varios campos en la cláusula ORDER BY mediante una lista separada por comas. El orden se realizará en la misma secuencia que se especificó en la consulta. Por ejemplo, si en esta consulta se seleccionan los datos del grupo de anuncios, los resultados se ordenarán de forma ascendente por nombre de campaña, luego en orden descendente según la 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

LIMIT

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

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

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

PARÁMETROS

La cláusula PARAMETERS te permite especificar los parámetros meta para la solicitud. Estos parámetros pueden afectar el tipo de filas que se muestran.

Actualmente, se admiten los siguientes metadatos:

Incluir borradores

Configura include_drafts como true para permitir que se muestren los borradores de entidades. La configuración predeterminada es false.

Por ejemplo, la siguiente consulta recupera borradores de campaña junto con campañas normales:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omite_unselected_resource_names

Configura omit_unselected_resource_names como true para evitar que se muestre el nombre del recurso de cada tipo de recurso en la respuesta, a menos que se solicite de manera explícita en la cláusula SELECT. La configuración predeterminada es false.

SELECT
  campaign.name,
  customer.id
FROM campaign

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Reglas de idioma adicionales

Además de los ejemplos para cada cláusula, el lenguaje de consulta de Google Ads tiene los siguientes comportamientos que se pueden utilizar:

• No es obligatorio que el campo principal del recurso esté en la cláusula SELECT para una consulta. Por ejemplo, es posible que desees usar solo uno o más campos de recursos principales para filtrar datos:

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

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

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

• Los campos de segmentación se pueden seleccionar sin ningún campo de recurso o métrica complementario:

  SELECT segments.device FROM campaign
  

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

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