Structure des requêtes et clauses

Une requête se compose d'un certain nombre de clauses: SELECT, FROM, WHERE, ORDER BY, LIMIT et PARAMETERS.

Les clauses utilisent des noms de champ, des noms de ressources, des opérateurs, des conditions et des tri qui se combinent dans une seule requête.

En termes simples, pour créer une requête, procédez comme suit:

  • Spécifiez une ressource à partir de laquelle récupérer les données.
  • Ajoutez des champs et des métriques pour définir les données que vous souhaitez renvoyer.
  • Ajoutez des segments pour regrouper vos résultats.
  • Ajoutez des ressources attribuées pour joindre implicitement les données de ressources associées.
  • Filtrez, triez et limitez vos résultats.

Clause SELECT

La clause SELECT:

  • Il s'agit d'une clause obligatoire dans une requête.
  • Spécifie un ensemble de champs à extraire dans la requête.
  • Utilise une liste de champs de ressources, de colonnes personnalisées, de variables Floodlight personnalisées, de champs de segment et de métriques séparés par une virgule, et renvoie les valeurs dans la réponse.

Cet exemple de requête montre comment sélectionner des attributs de la ressource campaign:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Plusieurs types de champs

Vous pouvez demander différents types de champs dans la même requête.

L'exemple de requête ci-dessous montre une seule requête avec une combinaison des éléments suivants:

  • Champs de ressources: campaign.id, campaign.name, bidding_strategy.id et bidding_strategy.name.
  • Champs de segment: segments.device et segments.date.
  • Champs de métriques: metrics.impressions et 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

Consultez Segmentation pour en savoir plus sur la segmentation de vos rapports sur le Réseau de Recherche.

Champ de ressource principal

En règle générale, vous devez inclure votre champ de ressource principal dans la clause SELECT, mais cela est facultatif (pas obligatoire).

Cet exemple de requête utilise un champ de ressource principal (ad_group.status) pour filtrer uniquement les résultats.

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

Variables Floodlight personnalisées

Vous pouvez inclure des variables Floodlight personnalisées dans la clause SELECT à l'aide de leurs ID.

Dans cet exemple, la requête inclut une variable personnalisée avec l'ID 123454321 pour la ressource de campagne.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Colonnes personnalisées

Vous pouvez inclure des colonnes personnalisées dans la clause SELECT à l'aide de leurs ID.

Dans cet exemple, la requête inclut une colonne personnalisée avec l'ID 12345678 pour la ressource de campagne.

SELECT
  custom_columns.id[12345678]
FROM campaign

Découvrez comment obtenir des ID de colonne personnalisés.

Champs des métriques

Vous pouvez sélectionner des champs de métriques pour une ressource donnée sans inclure d'autres champs de la ressource dans la clause SELECT.

Cet exemple de requête sélectionne les métriques impressions et clicks pour la ressource campaign.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Consultez metrics pour obtenir la liste des champs de métriques que vous pouvez utiliser dans vos requêtes.

Champs de segment

Vous pouvez sélectionner des champs de segment sans spécifier les champs de ressources ou les métriques associés dans la clause SELECT.

Cet exemple de requête segmente les résultats par appareil.

SELECT segments.device
FROM campaign

Consultez segments pour obtenir la liste des champs de segments que vous pouvez utiliser dans vos requêtes.

Champs interdits

Vous ne pouvez pas utiliser les champs suivants dans la clause SELECT:

  • Champs non sélectionnables, c'est-à-dire champs dont l'attribut de métadonnées Selectable est marqué comme false.
  • Champs répétés, c'est-à-dire champs dont l'attribut de métadonnées Repeated est marqué comme true.
  • Champs qui ne sont pas disponibles pour la ressource donnée dans la clause FROM. Les attributs de certaines ressources ne peuvent pas être sélectionnés ensemble. Certaines ressources ne rendent disponible qu'un sous-ensemble de toutes les métriques et de tous les segments.
  • Segments ou métriques incompatibles Pour en savoir plus, consultez Segmentation.

Pour savoir où trouver ces informations pour chaque ressource, consultez la documentation de référence.

Clause FROM

La clause FROM:

  • Clause obligatoire pour les requêtes envoyées à SearchAds360Service (méthodes Search et SearchStream).
  • Ne doit pas être inclus pour les requêtes envoyées à SearchAds360FieldService.
  • Spécifie la ressource principale renvoyée par la requête.
  • Vous ne pouvez spécifier qu'une seule ressource.
  • Définit les champs que vous pouvez utiliser dans toutes les autres clauses de la requête.

Ressources attribuées

Si des ressources attribuées sont disponibles, elles sont jointes implicitement à la ressource que vous spécifiez dans la clause FROM. Il vous suffit d'ajouter leurs attributs à la clause SELECT pour renvoyer leurs valeurs.

Cet exemple de requête renvoie à la fois l'ID du groupe d'annonces et l'ID de la campagne, car campaign est une ressource attribuée à la ressource ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Champ resource_name

Le champ resource_name de la ressource principale dans la clause FROM est toujours renvoyé.

Dans cet exemple de requête, ad_group.resource_name sera inclus dans la réponse, même s'il n'est pas sélectionné explicitement dans la requête:

SELECT ad_group.id
FROM ad_group

Le champ resource_name d'une ressource attribuée est renvoyé lorsqu'au moins un champ est sélectionné.

Dans cet exemple de requête, campaign.resource_name sera inclus dans la réponse, car campaign.id est sélectionné:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Clause WHERE

La clause WHERE:

  • Il s'agit d'une clause facultative dans une requête.
  • Spécifie les conditions de filtrage et de segmentation des données pour la requête. Les conditions suivent ce modèle: FIELD_NAME OPERATOR VALUE (séparés par des espaces vides).
  • Peut inclure plusieurs conditions séparées par le séparateur AND.

Cet exemple de requête montre comment utiliser la clause WHERE pour afficher des métriques impressions pour une période donnée:

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

Consultez Segmentation pour en savoir plus sur la segmentation de vos rapports sur le Réseau de Recherche.

Pour en savoir plus sur la spécification de plages de dates dans vos requêtes, consultez la section Plages de dates.

Filtrer par champ resource_name

Vous pouvez utiliser le champ resource_name pour filtrer ou trier les données.

Cet exemple de requête utilise le champ campaign.resource_name pour filtrer les résultats par campagne donnée:

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

Conditions multiples

Vous pouvez combiner plusieurs conditions pour filtrer vos données.

Cet exemple de requête demande le nombre de métriques clicks pour toutes les campagnes avec des métriques impressions sur mobile au cours des 30 derniers jours.

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

Pour en savoir plus sur la segmentation de vos rapports, consultez Segmentation.

Sensibilité à la casse

Lorsque vous filtrez sur les valeurs de chaîne, la sensibilité à la casse par défaut de chaque opérateur joue un rôle important pour filtrer correctement vos résultats.

Le tableau suivant indique la sensibilité à la casse par défaut de chaque opérateur.

Sensibilité à la casse par défaut
=/!= Case sensitive
IN/NOT IN Case sensitive
LIKE/NOT LIKE Case insensitive
CONTAINS (...) Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH Case sensitive

Vous pouvez utiliser le modificateur (?i) pour définir la sensibilité par défaut de REGEXP_MATCH et NOT REGEXP_MATCH sur une sensibilité insensible à la casse, par exemple:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

Pour obtenir la liste complète des opérateurs que vous pouvez utiliser pour filtrer vos données, consultez la documentation de référence sur la grammaire des requêtes.

Segments de dates principaux

Les champs de segments suivants sont appelés segments de date principaux : segments.date, segments.week, segments.month, segments.quarter et segments.year.

Vous pouvez utiliser des segments de date de base dans votre clause WHERE pour spécifier une période de date ou d'heure.

Cet exemple de requête spécifie DURING LAST_30_DAYS pour le champ segments.date dans la clause WHERE:

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

Pour en savoir plus sur l'utilisation des segments de date principaux, consultez Segmentation > Segments de date principaux.

Filtrage interdit

Le filtrage n'est pas autorisé:

  • Sur les champs de segment non sélectionnés, à l'exception des segments de date principaux.
  • Sur les champs de n'importe quel type de message, sauf les primitifs (par exemple, Int64Value, StringValue, etc.).
  • Sur les attributs des champs répétés de n'importe quel type de message, à l'exception des primitifs (par exemple, Int64Value, StringValue, etc.).

Clause ORDER BY

La clause ORDER BY:

  • Il s'agit d'une clause facultative dans une requête.
  • Spécifie l'ordre dans lequel les résultats sont renvoyés. L'ordre suit ce modèle: FIELD_NAME ORDERING_OPTION (séparés par un espace vide).
  • Permet deux options: ASC (croissant) ou DESC (décroissant). L'ordre par défaut est croissant.

Cet exemple de requête trie les campagnes par nombre de clics, par ordre décroissant (du plus élevé au plus faible):

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

Plusieurs ordres

Vous pouvez spécifier plusieurs champs dans la clause ORDER BY à l'aide d'une liste d'éléments séparés par une virgule. Les résultats seront triés dans l'ordre que vous spécifiez dans la requête.

Cet exemple de requête sélectionne les données des groupes d'annonces et trie les résultats par ordre croissant en fonction du nom de la campagne, puis par ordre décroissant en fonction du nombre d'impressions, puis par ordre décroissant en fonction du nombre 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

Combiner le tri et la limite

Vous pouvez utiliser la clause ORDER BY avec la clause LIMIT pour affiner vos résultats.

Cet exemple de requête renvoie les cinq campagnes ayant enregistré le plus d'impressions au cours des 30 derniers jours:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Commandes interdites

L'ordre n'est pas autorisé:

  • Par attributs des ressources non sélectionnées.
  • Par métriques non sélectionnées.
  • Par segments non sélectionnés.
  • Pour ces types de champs :
    • MESSAGE
    • Champs répétés
    • Attributs des champs répétés.

Clause LIMIT

La clause LIMIT:

  • Il s'agit d'une clause facultative dans une requête.
  • Permet de limiter le nombre de résultats renvoyés par la requête.

Cette clause est utile, par exemple, si vous ne vous intéressez qu'à un échantillon ou à un récapitulatif des résultats.

Cet exemple de requête limite le nombre total de résultats à 50:

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

Clause PARAMETERS

La clause PARAMETERS vous permet de spécifier des métaparamètres pour la requête.

Inclure brouillons

Le paramètre include_drafts détermine si les entités provisoires sont incluses dans les résultats. La valeur par défaut est false. Définissez-le sur true pour inclure les entités de brouillon.

Cet exemple de requête renvoie à la fois des campagnes d'ébauche et des campagnes standards:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omettez les resource_name désélectionnés.

Le paramètre omit_unselected_resource_names vous permet d'exclure le champ resource_name de toutes les ressources qui ne sont pas explicitement demandées dans votre clause SELECT. La valeur par défaut est false. Si vous définissez ce paramètre sur true, nous vous recommandons de demander explicitement le nom de la ressource de la ressource principale et de toutes les ressources attribuées dans votre clause SELECT.

Cet exemple de requête ne renvoie ni le champ campaign.resource_name ni le champ customer.resource_name, car ils ne sont pas inclus dans la clause SELECT:

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

Cet exemple de requête renvoie le champ campaign.resource_name, car il est explicitement demandé dans la clause SELECT:

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

Modifier la devise utilisée dans les métriques

Le paramètre metrics_currency vous permet de spécifier la devise à utiliser lors du calcul d'une métrique incluse dans votre clause SELECT. Par défaut, la devise locale du compte est utilisée. Si vous définissez ce paramètre, vous devez utiliser le code de devise à trois lettres ISO 4217. (par exemple, USD, EUR)

Cet exemple de requête renvoie la métrique "cost_micros" dans la devise locale du compte.

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

Cet exemple de requête renvoie la métrique "cost_micros" en pesos chiliens (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"

En savoir plus