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 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 e bidding_strategy.name.
• Campi dei segmenti: 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

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 come false.
• Campi ripetuti, ovvero campi con l'attributo di 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 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 metodi Search e SearchStream).
• 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.

Nota: c'è un campo di selezione Sì/No su ogni pagina della risorsa nella sezione Riferimento che esclude i campi delle risorse, i campi dei segmenti e i campi delle metriche che non possono essere utilizzati quando si specifica una risorsa nella clausola FROM.

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

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 è 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 agisce come segmento.

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

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

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) o DESC (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"

Scopri di più

• Grammatica delle query