Una query è composta da una serie di clausole: SELECT
,
FROM
,
WHERE
,
ORDER BY
,
LIMIT
e PARAMETERS
.
Le clausole utilizzano nomi di campo, nomi di risorse, operatori, condizioni e ordini che si combinano in un'unica richiesta di query.
In termini di base, per creare una query:
- Specifica una risorsa da cui recuperare i dati.
- Aggiungi campi e metriche per definire i dati che vuoi restituire.
- Aggiungi segmenti per raggruppare i risultati.
- Aggiungi risorse attribuite per unire implicitamente i dati delle risorse correlati.
- Filtra, ordina e limita i risultati.
Clausola SELECT
Clausola SELECT
:
- È una clausola required in una query.
- Specifica un insieme di campi da recuperare nella richiesta.
- Prende un elenco separato da virgole di campi risorsa, colonne personalizzate, variabili Floodlight personalizzate, campi di segmenti e metriche, e restituisce i valori nella risposta.
Questa query di esempio mostra come selezionare gli attributi della risorsa campaign
:
SELECT
campaign.id,
campaign.name
FROM campaign
Più tipi di campi
Puoi richiedere tipi di campi diversi nella stessa richiesta.
La query di esempio riportata di seguito mostra una singola query con una combinazione di:
- Campi delle risorse:
campaign.id
,campaign.name
,bidding_strategy.id
ebidding_strategy.name
. - Campi dei segmenti:
segments.device
esegments.date
. - Campi delle metriche:
metrics.impressions
emetrics.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
Per ulteriori informazioni sulla segmentazione dei rapporti di ricerca, consulta Segmentazione.
Campo delle risorse principale
In genere, includi il campo delle risorse principale nella clausola SELECT
, ma è facoltativo (non obbligatorio).
Questa query di esempio utilizza un campo di risorse principale (ad_group.status
) per filtrare solo i risultati.
SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED
Variabili Floodlight personalizzate
Puoi includere variabili Floodlight personalizzate nella clausola SELECT utilizzando i relativi ID.
In questo esempio, la query include una variabile personalizzata con ID 123454321 per la risorsa della campagna.
SELECT
conversion_custom_metrics.id[123454321]
FROM campaign
SELECT
conversion_custom_dimensions.id[123454321]
FROM campaign
Colonne personalizzate
Puoi includere colonne personalizzate nella clausola SELECT utilizzando i relativi ID.
In questo esempio, la query include una colonna personalizzata con ID 12345678 per la risorsa della campagna.
SELECT
custom_columns.id[12345678]
FROM campaign
Scopri come ottenere gli ID delle colonne personalizzate.
Campi delle metriche
Puoi selezionare i campi delle metriche per una determinata risorsa senza includere altri campi della risorsa nella clausola SELECT
.
Questa query di esempio seleziona le metriche impressions
e clicks
per la risorsa campaign
.
SELECT
metrics.impressions,
metrics.clicks
FROM campaign
Consulta metrics
per un
elenco dei campi delle metriche che puoi utilizzare nelle query.
Campi dei segmenti
Puoi selezionare i campi dei segmenti senza specificare i campi delle risorse o le metriche associati nella clausola SELECT
.
Questa query di esempio segmenta i risultati per dispositivo.
SELECT segments.device
FROM campaign
Consulta segments
per un
elenco dei campi dei segmenti che puoi utilizzare nelle query.
Campi vietati
Non puoi utilizzare i seguenti campi nella clausola SELECT
:
- Campi non selezionabili, ovvero i campi con l'attributo di metadati
Selectable
contrassegnato comefalse
. - Campi ripetuti, ovvero campi con l'attributo di metadati
Repeated
contrassegnato cometrue
. - Campi non disponibili per la risorsa specificata nella clausola
FROM
. Gli attributi di alcune risorse non possono essere selezionati insieme. Alcune risorse rendono disponibile solo un sottoinsieme di tutte le metriche e tutti i segmenti. - Segmenti o metriche incompatibili. Per ulteriori informazioni, consulta Segmentazione.
Consulta la documentazione di riferimento per i dettagli su dove trovare queste informazioni per ogni risorsa.
Clausola FROM
Clausola FROM
:
- È una clausola obbligatoria per le query rivolte a
SearchAds360Service
(entrambi i metodiSearch
eSearchStream
). - Non deve essere incluso per le query indirizzate a
SearchAds360FieldService
. - Specifica la risorsa principale restituita dalla query.
- Può specificare una sola risorsa.
- Definisce i campi che puoi utilizzare in tutte le altre clausole della query.
Risorse attribuite
Se sono disponibili risorse attribuite, vengono unite implicitamente alla risorsa specificata nella clausola FROM
. Devi solo aggiungere i relativi attributi alla clausola SELECT
per restituirne i valori.
Questa query di esempio restituisce sia l'ID gruppo di annunci sia l'ID campagna, perché campaign
è una risorsa attribuita della risorsa ad_group
.
SELECT
campaign.id,
ad_group.id
FROM ad_group
Campo resource_name
Il campo resource_name
della risorsa principale nella clausola FROM
viene sempre
restituito.
In questa query di esempio, ad_group.resource_name
verrà incluso nella risposta
anche se non è selezionato esplicitamente nella query:
SELECT ad_group.id
FROM ad_group
Il campo resource_name
di una risorsa attribuita viene restituito quando è selezionato almeno un campo.
In questa query di esempio, campaign.resource_name
verrà incluso nella
risposta perché è selezionato campaign.id
:
SELECT
campaign.id,
ad_group.id
FROM ad_group
Clausola WHERE
Clausola WHERE
:
- È una clausola facoltativa in una query.
- Specifica le condizioni per filtrare e segmentare i dati per la richiesta.
Le condizioni seguono questo pattern:
FIELD_NAME
OPERATOR
VALUE
(separate da spazi vuoti). - Può includere più condizioni separate dal separatore
AND
.
Questa query di esempio mostra come utilizzare la clausola WHERE
per restituire le metriche impressions
per un determinato periodo di tempo:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Per ulteriori informazioni sulla segmentazione dei rapporti di ricerca, consulta Segmentazione.
Per scoprire di più su come specificare gli intervalli di date nelle query, consulta Intervalli di date.
Filtra per campo resource_name
Puoi utilizzare il campo resource_name
per filtrare o ordinare i dati.
Questa query di esempio utilizza il campo campaign.resource_name
per filtrare i risultati in base a una determinata campagna:
SELECT
campaign.id,
campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
Più condizioni
Puoi combinare più condizioni per filtrare i dati.
Questa query di esempio richiede il numero di metriche clicks
per tutte le campagne
con metriche impressions
su dispositivi mobili negli ultimi 30 giorni.
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
Per ulteriori informazioni sulla segmentazione dei report, consulta Segmentazione.
Distinzione tra maiuscole e minuscole
Quando filtri i valori in base alle stringhe, la sensibilità predefinita di maiuscole e minuscole di ciascun operatore svolge un ruolo importante nel filtrare correttamente i risultati.
La tabella seguente mostra la sensibilità predefinita alle maiuscole di ciascun operatore.
Sensibilità predefinita alle maiuscole | |
---|---|
=/!= |
Case sensitive |
IN/NOT IN |
Case sensitive |
LIKE/NOT LIKE |
Case insensitive |
CONTAINS (...) |
Case sensitive |
REGEXP_MATCH/NOT REGEXP_MATCH |
Case sensitive |
Puoi utilizzare il modificatore (?i)
per cambiare la sensibilità predefinita per REGEXP_MATCH
e NOT REGEXP_MATCH
impostandola su senza distinzione tra maiuscole e minuscole, ad esempio:
SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"
Consulta Riferimento grammaticale delle query per un elenco completo degli operatori che puoi utilizzare per filtrare i dati.
Segmenti di data principali
I seguenti campi di segmenti sono noti come segmenti di data principali:
segments.date
, segments.week
, segments.month
, segments.quarter
e
segments.year
.
Puoi utilizzare i segmenti di data principali nella clausola WHERE
per specificare una data o un periodo di tempo.
Questa query di esempio specifica DURING LAST_30_DAYS
per il campo segments.date
nella clausola WHERE
:
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Consulta Segmentazione > Segmenti di data principali per informazioni dettagliate sull'utilizzo dei segmenti di data principali.
Filtri vietati
Filtri non consentiti:
- Nei campi dei segmenti non selezionati, ad eccezione dei segmenti di data principali.
- Sui campi di qualsiasi tipo di messaggio, tranne le primitive (ad esempio
Int64Value
,StringValue
e così via). - Per gli attributi dei campi ripetuti di qualsiasi tipo di messaggio, tranne le primitive (ad es.
Int64Value
,StringValue
e così via).
Clausola ORDER BY
Clausola ORDER BY
:
- È una clausola facoltativa in una query.
- Specifica l'ordine in cui vengono restituiti i risultati. L'ordinamento segue questo
pattern:
FIELD_NAME
ORDERING_OPTION
(separato da uno spazio vuoto). - Consente due opzioni:
ASC
(ordine crescente) oDESC
(ordine decrescente). Il valore predefinito è crescente.
In questa query di esempio le campagne vengono ordinate in base al numero di clic in ordine decrescente (dal più alto al più basso):
SELECT
campaign.name,
metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC
Ordini multipli
Puoi specificare più campi nella clausola ORDER BY
utilizzando un elenco separato da virgole. I risultati verranno ordinati nella stessa sequenza specificata nella query.
Questa query di esempio seleziona i dati dei gruppi di annunci e ordina i risultati in ordine crescente in base al nome della campagna, poi in ordine decrescente per numero di impressioni e in ordine decrescente in base al numero di clic:
SELECT
campaign.name,
ad_group.name,
metrics.impressions,
metrics.clicks
FROM ad_group
ORDER BY
campaign.name,
metrics.impressions DESC,
metrics.clicks DESC
Combina l'ordinamento e il limite
Puoi utilizzare la clausola ORDER BY
in combinazione con la clausola LIMIT
per
perfezionare i risultati.
Questa query di esempio restituisce le cinque campagne con il maggior numero di impressioni negli ultimi 30 giorni:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5
Ordine vietato
Non è consentito effettuare ordini:
- In base agli attributi delle risorse non selezionate.
- In base a metriche non selezionate.
- Per segmenti non selezionati.
- Per questi tipi di campi:
MESSAGE
- Campi ripetuti
- Attributi dei campi ripetuti.
Clausola LIMIT
Clausola LIMIT
:
- È una clausola facoltativa in una query.
- Consente di limitare il numero di risultati restituiti dalla query.
Questa clausola è utile, ad esempio, se ti interessa solo un esempio o un riepilogo dei risultati.
In questa query di esempio il numero totale di risultati è limitato a 50:
SELECT
campaign.name,
ad_group.name,
segments.device,
metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50
Clausola PARAMETERS
La clausola PARAMETERS
consente di specificare i meta-parametri per la richiesta.
Includi bozze
Il parametro include_drafts
controlla se le entità in stato di bozza sono incluse
nei risultati. Il valore predefinito è false
. Impostalo su true
per includere le entità in stato di bozza.
Questa query di esempio restituisce sia campagne in bozza sia campagne standard:
SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true
Ometti resource_name
deselezionato
Il parametro omit_unselected_resource_names
ti consente di escludere il campo resource_name
di tutte le risorse che non sono richieste esplicitamente nella clausola SELECT
. Il valore predefinito è false
. Se imposti questo parametro su true
, ti consigliamo di richiedere esplicitamente il nome della risorsa principale e le eventuali risorse attribuite nella clausola SELECT
.
Questa query di esempio non restituisce né il campo campaign.resource_name
né il campo customer.resource_name
, perché non sono inclusi nella clausola SELECT
:
SELECT
campaign.name,
customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true
Questa query di esempio restituisce il campo campaign.resource_name
perché è richiesto esplicitamente nella clausola SELECT
:
SELECT
campaign.name,
campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
Cambia la valuta utilizzata nelle metriche
Il parametro metrics_currency
consente di specificare la valuta da utilizzare
per il calcolo di una metrica inclusa nella clausola SELECT
.
Per impostazione predefinita viene utilizzata la valuta locale dell'account. Se imposti questo parametro, devi utilizzare il codice valuta di tre caratteri ISO 4217.
Ad esempio: USD, EUR.
Questa query di esempio restituisce la metrica cost_micros nella valuta locale dell'account.
SELECT
campaign.name,
metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
Questa query di esempio restituisce la metrica cost_micros in pesos cileni (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"