Struttura della query e clausole

Una query è composta da una serie di clausole: SELECT, FROM, WHERE, ORDER BY, LIMIT e PARAMETERS.

Le clausole utilizzano nomi di campi, nomi di risorse, operatori, condizioni e ordinamenti che si combinano in un'unica richiesta di query.

In termini semplici, per creare una query:

• Specifica una risorsa da cui recuperare i dati.
• Aggiungi campi e metriche per definire i dati da restituire.
• Aggiungi segmenti per raggruppare i risultati.
• Aggiungi risorse attribuite per unire implicitamente i dati delle risorse correlate.
• Filtra, ordina e limita i risultati.

SELECT clausola

La clausola SELECT:

• È una clausola obbligatoria in una query.
• Specifica un insieme di campi da recuperare nella richiesta.
• Accetta un elenco separato da virgole di campi delle risorse, colonne personalizzate, variabili Floodlight personalizzate, campi di segmento 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 diversi tipi di campi nella stessa richiesta.

La query di esempio riportata di seguito mostra una singola query con una combinazione di:

• Campi risorsa: campaign.id, campaign.name, bidding_strategy.id e bidding_strategy.name.

• Campi di segmento: segments.device e segments.date.

• Campi delle metriche: metrics.impressions e 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

Consulta la sezione Segmentazione per scoprire di più sulla segmentazione dei report sulla ricerca.

Campo risorsa principale

In genere, il campo della risorsa principale viene incluso nella clausola SELECT, ma è facoltativo (non obbligatorio).

Questa query di esempio utilizza un campo della risorsa 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 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 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 tue query.

Campi dei segmenti

Puoi selezionare i campi dei segmenti senza specificare i campi delle risorse o le metriche di accompagnamento 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 campi con l'attributo dei metadati Selectable contrassegnato come false.

• Campi ripetuti, ovvero campi con l'attributo dei metadati Repeated contrassegnato come true.

• 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 i segmenti.

• Segmenti o metriche incompatibili. Per saperne di più, consulta Segmentazione.

Per informazioni dettagliate su dove trovare queste informazioni per ogni risorsa, consulta la documentazione di riferimento.

Clausola FROM

La clausola FROM:

• È una clausola obbligatoria per le query a SearchAds360Service (metodi Search e SearchStream).

• Non deve essere incluso per le query 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.

Nota: in ogni pagina delle risorse nella sezione Riferimento è presente un campo di selezione Sì/No che filtra i campi delle risorse, i campi dei segmenti e i campi delle metriche che non possono essere utilizzati quando una risorsa è specificata nella clausola FROM.

Risorse attribuite

Se sono disponibili risorse attribuite, queste 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

Nota: non tutte le risorse hanno risorse attribuite. La sezione Riferimento include i dettagli delle risorse attribuite disponibili con ogni risorsa.

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 viene 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

Nota: se la risorsa nella clausola FROM elenca un'altra risorsa come segment, la selezione di qualsiasi attributo di quella risorsa funge da segmento.

Clausola WHERE

La clausola WHERE:

• È una clausola facoltativa in una query.

• Specifica le condizioni per filtrare e segmentare i dati per la richiesta. Le condizioni seguono questo schema: 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

Consulta la sezione Segmentazione per scoprire di più sulla segmentazione dei report sulla ricerca.

Consulta Intervalli di date per scoprire di più su come specificare gli intervalli di date nelle query.

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 dispositivo mobile 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

Nota: il separatore AND può essere utilizzato solo tra le condizioni degli operatori (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") e non all'interno di una singola condizione dell'operatore (WHERE segments.device != "DESKTOP" AND "MOBILE").

Per saperne di più sulla segmentazione dei report, consulta la sezione Segmentazione.

Distinzione tra maiuscole e minuscole

Quando filtri in base ai valori stringa, la distinzione tra maiuscole e minuscole predefinita di ogni operatore svolge un ruolo importante nel filtrare correttamente i risultati.

La tabella seguente mostra la distinzione tra maiuscole e minuscole predefinita di ogni operatore.

Sensibilità alle maiuscole predefinita
=/!=	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 modificare la sensibilità predefinita per REGEXP_MATCH e NOT REGEXP_MATCH in modo che non faccia distinzione tra maiuscole e minuscole, ad esempio:

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

Consulta Riferimento alla sintassi delle query per un elenco completo degli operatori che puoi utilizzare per filtrare i dati.

Segmenti di date principali

I seguenti campi dei segmenti sono noti come segmenti di date principali: segments.date, segments.week, segments.month, segments.quarter e segments.year.

Puoi utilizzare i segmenti di date principali nella clausola WHERE per specificare un periodo di tempo o una data.

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 date principali per informazioni dettagliate sull'utilizzo dei segmenti di date principali.

Filtro vietato

Il filtro non è consentito:

• Nei campi dei segmenti non selezionati, ad eccezione dei segmenti di date principali.

• Nei campi di qualsiasi tipo di messaggio, ad eccezione dei primitivi (ad esempio Int64Value, StringValue e così via).

• Sugli attributi dei campi ripetuti di qualsiasi tipo di messaggio, ad eccezione dei primitivi (ad esempio Int64Value, StringValue e così via).

Clausola ORDER BY

La 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 (separati da uno spazio vuoto).
• Consente due opzioni: ASC (crescente) o DESC (decrescente). Il valore predefinito è crescente.

Questa query di esempio ordina le campagne 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

Più ordinazioni

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 in base al numero di impressioni e poi 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 ordinamento e 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

Ordini vietati

L'ordinazione non è consentita:

• In base agli attributi delle risorse non selezionate.
• In base alle metriche non selezionate.
• Dai segmenti non selezionati.
• Per questi tipi di campi:
  • MESSAGE
  • Campi ripetuti
  • Attributi dei campi ripetuti.

Clausola LIMIT

La 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 campione o un riepilogo dei risultati.

Questa query di esempio limita il numero totale di risultati 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 metadati per la richiesta.

Includi bozze

Il parametro include_drafts controlla se le entità bozza sono incluse nei risultati. Il valore predefinito è false. Imposta il valore su true per includere le entità bozza.

Questa query di esempio restituisce sia le bozze delle campagne sia le campagne standard:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Ometti resource_name non selezionati

Il parametro omit_unselected_resource_names ti consente di escludere il campo resource_name di tutte le risorse non 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 di tutte le 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

Modificare la valuta utilizzata nelle metriche

Il parametro metrics_currency ti consente di specificare la valuta da utilizzare per calcolare una metrica inclusa nella clausola SELECT. Il valore predefinito è l'utilizzo della valuta dell'account specificato da customer_id. 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 dell'account specificata da customer_id.

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"

Attivare l'espansione dell'account Centro clienti

Il parametro enable_mcc_expansion, se impostato su true, ti consente di includere metriche, campi e segmenti di tutti gli account con radice in customer_id, per la risorsa nella clausola FROM. La risposta utilizzerà la valuta di customer_id, a meno che non sia specificata esplicitamente nel parametro metrics_currency.

Nota: il parametro enable_mcc_expansion è compatibile solo con bidding_strategy. L'API includerà risorse aggiuntive nel tempo.

Questa query di esempio restituisce bidding_strategy.name, bidding_strategy.type e metrics.cost_micros da tutti gli account nella gerarchia dell'account con radice in customer_id, perché il parametro enable_mcc_expansion è impostato su true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

Scopri di più

• Grammatica delle query