GAQL et Claude : écrire des requêtes Google Ads

Sur le serveur MCP Google Ads officiel, un seul des trois outils fait le travail d'analyse : search, qui exécute des requêtes GAQL (Google Ads Query Language). Claude écrit ces requêtes à partir de votre question. À notre avis, savoir les lire sépare une réponse à laquelle on peut se fier d'une réponse à refaire. Cet article reprend la documentation de Google sur le langage, relue le 19 octobre 2026, puis propose une façon de cadrer Claude. L'installation du serveur est détaillée dans notre setup du MCP Google Ads.

Ce que le serveur expose

D'après la page de Google sur son serveur MCP (mise à jour le 16 octobre 2026), trois outils sont disponibles : list_accessible_customers (identifiants et noms des comptes accessibles), search (requêtes GAQL pour obtenir métriques, budgets et statuts) et get_resource_metadata (métadonnées d'un type de ressource, par exemple « campaign », utiles pour connaître les champs disponibles). La même page écrit que l'implémentation est strictement en lecture seule : elle ne peut ni modifier des enchères, ni mettre des campagnes en pause, ni créer de nouveaux assets. Une requête GAQL envoyée par ce chemin ne fait donc que lire.

Les clauses d'une requête

Une requête GAQL se compose de six clauses possibles : SELECT, FROM, WHERE, ORDER BY, LIMIT et PARAMETERS. Avec GoogleAdsService, SELECT et FROM sont obligatoires, les autres facultatives.

Quand on ajoute un segment au SELECT avec des métriques, les métriques sont ventilées par segment : la réponse contient une ligne par couple ressource-segment. Les champs d'une ressource liée (ressource « attribuée ») se sélectionnent sans jointure explicite. En demandant bidding_strategy.name depuis la ressource campaign, on obtient le nom de la stratégie d'enchères de portefeuille utilisée par la campagne. La référence v26 de campaign distingue cette stratégie de portefeuille, liée par le champ campaign.bidding_strategy, de la stratégie standard réglée sur la campagne elle-même ; le type de stratégie de chaque campagne se lit dans campaign.bidding_strategy_type.

Deux requêtes de départ

Premier exemple, construit à partir de ceux de la documentation (plage prédéfinie, « top N » par LIMIT) : les dix campagnes qui ont le plus dépensé sur 30 jours.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC
LIMIT 10

La référence v26 décrit metrics.cost_micros comme la somme des coûts CPC et CPM de la période. À notre avis, le suffixe « micros » signale une unité monétaire exprimée en millionièmes : vérifiez la définition dans la référence avant de convertir un montant.

Second exemple : l'évolution jour par jour des conversions, avec une plage saisie au format ISO.

SELECT
  campaign.name,
  segments.date,
  metrics.conversions,
  metrics.conversions_value
FROM campaign
WHERE segments.date BETWEEN '2026-10-01' AND '2026-10-14'
ORDER BY segments.date

Chaque ligne représente un couple campagne-jour. Sur un compte de plusieurs dizaines de campagnes, la réponse grossit vite. La documentation recommande de ne sélectionner que les champs nécessaires, d'utiliser LIMIT pendant les tests et de filtrer dans WHERE pour réduire les données transférées. À notre avis, on restreint à une campagne ou à un statut avant d'élargir.

Les dates, première source d'erreurs

• Plage saisie : format ISO 8601, étendu (YYYY-MM-DD, celui que Google recommande) ou basique (YYYYMMDD), avec BETWEEN ou les opérateurs de comparaison.
• Plage prédéfinie : opérateur DURING avec un littéral comme LAST_7_DAYS ou LAST_30_DAYS. DURING n'accepte que des plages prédéfinies, pas des dates saisies.
• LAST_7_DAYS et LAST_30_DAYS ne comptent pas la journée en cours.
• Les plages sont évaluées dans le fuseau horaire du compte, pas en UTC.
• Pour filtrer segments.week, segments.month ou segments.quarter avec des dates saisies, il faut donner le premier jour de la période (un lundi pour la semaine). Sinon l'API renvoie l'erreur QueryError.MISALIGNED_DATE_FOR_FILTER.
• Historique : jusqu'à 37 mois en granularité jour, semaine ou heure ; jusqu'à 11 ans en mois, trimestre, année ou sans segment de date. Au-delà de 37 mois, la plage du WHERE doit commencer le premier jour d'un mois et finir le dernier jour d'un mois (ou filtrer sur segments.month, segments.quarter ou segments.year).

À notre avis, la consigne qui en découle est simple : demander à Claude d'indiquer, dans chaque réponse, la plage exacte utilisée et le fuseau du compte. Une comparaison entre deux périodes qui ne reposent pas sur la même définition de « 30 jours » se lit mal.

Pourquoi une requête échoue

La documentation décrit plusieurs cas où un champ ne peut pas figurer dans une clause :

• dans SELECT : un champ dont l'attribut selectable vaut false, un attribut d'un champ répété (is_repeated à true), un champ indisponible pour la ressource du FROM, ou des segments et métriques incompatibles entre eux ;
• dans ORDER BY : un tri sur une métrique, un segment ou une ressource qui ne figurent pas dans le SELECT ;
• dans WHERE : un filtre sur un segment absent du SELECT, sauf les segments de date (segments.date, week, month, quarter et year).

Le catalogue des ressources, segments et métriques varie selon la version majeure de l'API. La page de Google cite les versions v23, v24, v25 et v26, dont la syntaxe est identique, et recommande d'interroger GoogleAdsFieldService au point d'accès de la version visée. La page du serveur MCP ne dit pas quelle version il utilise. À notre avis, un champ refusé alors qu'il figure dans la référence la plus récente est d'abord une question de version.

Faire valider avant de lancer

Les pages relues citent notamment trois aides côté Google :

• l'outil get_resource_metadata du serveur, qui renvoie les métadonnées d'un type de ressource ;
• le Query Builder interactif, que la page GAQL présente comme un moyen de construire et valider ses requêtes ;
• le Google Ads API Developer Assistant, un plugin pour Antigravity et Claude Code dont la page du serveur dit qu'il fournit, entre autres, une validation programmatique des requêtes GAQL.

La page du serveur propose aussi, en option, d'associer à celui-ci des « agent skills » de Google pour aider l'agent à construire des requêtes valides.

Une consigne pour le CLAUDE.md du client

Voici une consigne que nous placerions dans le fichier de contexte du client (voir notre guide de Claude Code pour Google Ads). Cette consigne est notre recommandation.

## Requêtes Google Ads
- Avant une requête GAQL sur un champ que tu ne connais pas, interroge get_resource_metadata.
- Ajoute LIMIT à chaque requête exploratoire.
- Écris la requête GAQL dans ta réponse, avec la plage de dates utilisée.
- Si la requête échoue, montre l'erreur. N'invente aucun chiffre.

Par où commencer

1. Lancez la première requête de cet article sur un compte de test ou sur un compte que vous connaissez, et comparez les dix campagnes à l'interface.
2. Demandez à Claude d'expliquer chaque clause de la requête qu'il a écrite. Une clause qu'il ne sait pas justifier est à revoir.
3. Ajoutez les quatre lignes de consigne au CLAUDE.md, puis relancez la même question.

Questions fréquentes

Sources consultées le 19 octobre 2026

• Google : serveur MCP Google Ads (mise à jour du 16 octobre 2026)
• Google : Google Ads Query Language (mise à jour du 14 octobre 2026)
• Google : structure d'une requête, plages de dates, tri et limite
• Google : référence des métriques v26, référence de la ressource campaign v26