Anatomía de una consulta GAQL: cláusulas, operadores, fechas, micros y las reglas que te rechazan

Formación Avanzada · Módulo 8 — GAQL y la API — leer lo que la interfaz no enseña

En corto: una consulta GAQL tiene seis cláusulas y solo dos obligatorias: SELECT y FROM. Las trampas que explican casi todos los errores son cinco: lo que filtras tiene que estar seleccionado, un solo recurso por consulta, las fechas necesitan rango, no todo es compatible entre sí, y los segmentos multiplican filas. Los importes vienen en micros: divide entre un millón.

Una consulta GAQL tiene seis cláusulas, de las que dos son obligatorias. Esta lección las desmonta con una consulta real comentada y las reglas que el validador aplica — para que entiendas por qué una consulta funciona o devuelve error.

Una consulta GAQL comentada línea a línea

SELECT
  campaign.id,                          -- atributo: el ID (clave estable)
  campaign.name,                        -- atributo: el nombre (solo para mostrar)
  segments.date,                        -- segmento: una fila por día
  metrics.cost_micros,                  -- métrica: coste en micros (÷ 1.000.000)
  metrics.conversions,                  -- métrica: conversiones principales
  metrics.search_budget_lost_impression_share   -- métrica: IS perdido por presupuesto
FROM campaign                           -- recurso: la tabla de campañas
WHERE
  campaign.status = 'ENABLED'           -- enum: entre comillas, en mayúsculas
  AND campaign.advertising_channel_type = 'SEARCH'
  AND segments.date DURING LAST_30_DAYS -- rango de fechas obligatorio al segmentar por fecha
  AND metrics.clicks > 0                -- filtro por métrica
ORDER BY metrics.cost_micros DESC       -- orden
LIMIT 500                               -- tope de filas

¿Qué cláusulas tiene una consulta GAQL?

Cláusula	Obligatoria	Qué hace
`SELECT`	Sí	Lista de atributos, métricas y segmentos que quieres
`FROM`	Sí	Un único recurso (tabla)
`WHERE`	No	Condiciones unidas con `AND` (no hay `OR` entre condiciones distintas; se usa `IN`)
`ORDER BY`	No	Campo `ASC`/`DESC`
`LIMIT`	No	Máximo de filas
`PARAMETERS`	No	Opciones (p. ej. incluir borradores)

¿Qué operadores admite el WHERE?

Tipo	Operadores	Ejemplo
Comparación	`=`, `!=`, `>`, `>=`, `<`, `<=`	`metrics.clicks > 100`
Conjunto	`IN (...)`, `NOT IN (...)`	`campaign.id IN (123, 456)`
Texto	`LIKE`, `NOT LIKE` (con `%`), `CONTAINS ANY/ALL/NONE`	`campaign.name LIKE '%Marca%'`
Rango	`BETWEEN ... AND ...`	`segments.date BETWEEN '2026-07-01' AND '2026-07-31'`
Fecha	`DURING`	`segments.date DURING LAST_7_DAYS`
Nulos	`IS NULL`, `IS NOT NULL`	`ad_group_criterion.keyword.text IS NOT NULL`
Regex	`REGEXP_MATCH`	`campaign.name REGEXP_MATCH '^SEARCH.*'`

¿Cómo se filtran las fechas en GAQL?

Rangos predefinidos: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, LAST_BUSINESS_WEEK, THIS_WEEK_SUN_TODAY…
Rangos explícitos: BETWEEN '2026-07-01' AND '2026-07-31' (formato ISO).
Regla: si seleccionas segments.date (o semana, mes…), tiene que haber un filtro de fecha en el WHERE.

¿Por qué los importes salen multiplicados por un millón?

Los importes vienen en micros: cost_micros = 1.234.560.000 equivale a 1.234,56 €. Siempre se divide por un millón.
Los estados y tipos son enums: 'ENABLED', 'PAUSED', 'REMOVED'; 'SEARCH', 'SHOPPING', 'PERFORMANCE_MAX', 'DEMAND_GEN'; entre comillas simples y en mayúsculas.
Los porcentajes (IS, CTR) vienen como fracción (0,35 = 35 %).
Los IDs son números grandes: trátalos como texto al guardarlos en una hoja (Sheets los redondea).

¿Por qué falla mi consulta GAQL?

Lo que filtras, lo seleccionas: un campo en WHERE (en particular segmentos como segments.conversion_action_name) debe estar en SELECT.
Un recurso por consulta: no hay JOIN; cada recurso ya incorpora los atributos de sus "padres" (desde keyword_view puedes pedir campaign.name).
Segmentar por fecha exige rango de fecha.
Segmentos y métricas compatibles: no todos los segmentos valen con todas las métricas en todos los recursos (el validador lo dice).
Nombres de campo vigentes: Google renombra campos de vez en cuando; una consulta con un nombre antiguo puede ser rechazada o, peor, devolver una tabla vacía sin error visible. Si una consulta que funcionaba deja de traer filas, revisa los nombres de campo en la documentación.
Cada segmento multiplica las filas: segments.date + segments.device = una fila por campaña, día y dispositivo. Pide solo los segmentos que necesitas.

¿Cómo aprender GAQL sin programar?

El constructor de consultas de Google: eliges el recurso, marcas campos y métricas, añades filtros y te da la consulta. El validador te dice si es correcta. Y en un script, AdsApp.search(query) devuelve las filas para escribirlas en una hoja. Con eso, cualquier pregunta de la formación ("términos con conversiones que no son palabras clave", "IS perdido por presupuesto por campaña y día") se convierte en una consulta de diez líneas.

💡 Truco ninja: dos detalles de la práctica de la suite: las consultas se hacen con ventanas de fechas congeladas (se calculan una vez y se guardan) para que las descargas incrementales de varios días cuadren entre sí; y las cuentas grandes se consultan por tandas (LIMIT + filtros por campaña o por fecha) para no chocar con el límite de 30 minutos de los scripts.

Qué debes recordar

SELECT + FROM obligatorios; WHERE con AND, IN, LIKE, BETWEEN, DURING; ORDER BY, LIMIT.
Importes en micros (÷ 1.000.000); estados como enums entre comillas; porcentajes como fracción; IDs como texto en hojas.
Reglas: lo filtrado se selecciona, un recurso, fecha con rango, compatibilidad, segmentos multiplican filas.
Constructor + validador para aprender; AdsApp.search para ejecutar.