Structure des requêtes et clauses

Une requête est composée de plusieurs clauses: SELECT, FROM, WHERE, ORDER BY, LIMIT et PARAMETERS.

Les clauses utilisent des noms de champs, des noms de ressources, des opérateurs, des conditions et des ordres qui sont combinés en une seule requête de requête.

Pour créer une requête, vous devez:

• 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 des données de ressources associées.
• Filtrez, triez et limitez vos résultats.

Clause SELECT

La clause SELECT:

• Est une clause obligatoire dans une requête.
• Spécifie un ensemble de champs à extraire dans la requête.
• Prend 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, puis renvoie les valeurs dans la réponse.

Cet exemple de requête vous montre comment sélectionner les 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 présente une seule requête avec une combinaison de:

• Champs de ressource: 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

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

Champ de ressource principal

En règle générale, vous devez inclure le champ de la ressource principale dans la clause SELECT, mais cette opération est facultative (non obligatoire).

Cet exemple de requête utilise un champ de ressource principal (ad_group.status) pour ne filtrer que 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 ayant 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 en utilisant leurs ID.

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

SELECT
  custom_columns.id[12345678]
FROM campaign

Découvrez comment obtenir des ID de colonnes personnalisées.

Champs de 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 la section metrics pour obtenir la liste des champs de métriques que vous pouvez utiliser dans vos requêtes.

Champs de segments

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

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

SELECT segments.device
FROM campaign

Pour obtenir la liste des champs de segment que vous pouvez utiliser dans vos requêtes, consultez la section segments.

Champs interdits

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

• Champs non sélectionnables, c'est-à-dire ceux dont l'attribut de métadonnées Selectable est marqué comme false.
• Champs répétés, c'est-à-dire les champs dont l'attribut de métadonnées Repeated est marqué comme true.
• Champs non disponibles pour la ressource donnée dans la clause FROM. Impossible de sélectionner simultanément les attributs de certaines ressources. Certaines ressources ne mettent à disposition qu'un sous-ensemble de toutes les métriques et tous les segments.
• Segments ou métriques incompatibles. Pour en savoir plus, consultez la page Segmentation.

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

Clause FROM

La clause FROM:

• Clause obligatoire pour les requêtes adressées à SearchAds360Service (méthodes Search et SearchStream)
• Ne doit pas être inclus dans les requêtes destiné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.

Remarque :Sur chaque page de ressource de la section Références, un champ de sélection Oui/Non exclut les champs de ressources, de segments et de métriques qui ne peuvent pas être utilisés lorsqu'une ressource est spécifiée dans la clause FROM.

Ressources attribuées

Si des ressources attribuées sont disponibles, elles sont implicitement associées à 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 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

Remarque :Toutes les ressources ne sont pas attribuées à des ressources. La section Référence inclut des détails sur les ressources attribuées disponibles pour chaque ressource.

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 explicitement sélectionné 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

Remarque :Si la ressource dans la clause FROM répertorie une autre ressource en tant que segment, sélectionner n'importe quel attribut de cette ressource agit comme un segment.

Clause WHERE

La clause WHERE:

• Clause facultative d'une requête.
• Spécifie les conditions de filtrage et de segmentation des données pour la requête. Les conditions suivent le format suivant: FIELD_NAME OPERATOR VALUE (séparées par des espaces).
• Peut inclure plusieurs conditions séparées par le séparateur AND.

Cet exemple de requête montre comment utiliser la clause WHERE pour renvoyer 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

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

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 en fonction d'une 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

Remarque :Le séparateur AND ne peut être utilisé qu'entre des conditions d'opérateur (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), et non au sein d'une même condition d'opérateur (WHERE segments.device != "DESKTOP" AND "MOBILE").

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

Sensibilité à la casse

Lorsque vous filtrez des 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 non sensible à la casse, par exemple:

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

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

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 principaux dans votre clause WHERE pour spécifier une date ou une période.

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 dates principaux.

Filtrage interdit

Le filtrage n'est pas autorisé:

• dans les champs de segments non sélectionnés, à l'exception des segments de dates principaux ;
• Dans les champs de n'importe quel type de message, à l'exception des primitives (par exemple, Int64Value, StringValue, etc.)
• Pour les attributs de champs répétés de tout type de message, à l'exception des primitives (par exemple, Int64Value, StringValue, etc.)

Clause ORDER BY

La clause ORDER BY:

• Clause facultative d'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).
• Autorise deux options: ASC (croissant) ou DESC (décroissant). La valeur par défaut est croissante.

Cet exemple de requête trie les campagnes par nombre de clics dans l'ordre décroissant (du plus élevé au plus bas):

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

Commandes multiples

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 sont classés dans la même séquence que celle que vous spécifiez dans la requête.

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

Commande interdite

Commande non autorisée:

• 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 de champs répétés.

Clause LIMIT

La clause LIMIT:

• Clause facultative d'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 n'êtes intéressé que par un échantillon ou un résumé 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 les brouillons

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

Cet exemple de requête renvoie à la fois des campagnes brouillons et des campagnes standards:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omettre les resource_name non 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 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 pour calculer une métrique incluse dans votre clause SELECT. La devise locale est utilisée par défaut pour le compte. Si vous définissez ce paramètre, vous devez utiliser le code de devise à trois caractères 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

• Grammaire des requêtes