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
etbidding_strategy.name
. - Champs de segment:
segments.device
etsegments.date
. - Champs de métriques:
metrics.impressions
etmetrics.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é commefalse
. - Champs répétés, c'est-à-dire les champs dont l'attribut de métadonnées
Repeated
est marqué commetrue
. - 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éthodesSearch
etSearchStream
) - 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.
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
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
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
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) ouDESC
(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"