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 di base, per creare una query devi:

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

Clausola SELECT

La clausola SELECT:

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

Campo della risorsa principale

In genere, è consigliabile includere il campo della risorsa principale nella clausola SELECT, ma questo è 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 colonna personalizzati.

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 Segmenti

Puoi selezionare i campi dei segmenti senza specificare i campi o le metriche delle risorse aggiuntive 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 ulteriori informazioni, consulta la sezione 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 (entrambi i 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.

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 visualizzato.

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

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

Consulta la sezione Segmentazione per scoprire di più sulla segmentazione dei report sulla rete di 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 sui 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

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

Distinzione tra maiuscole e minuscole

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

La tabella seguente mostra la sensibilità alle maiuscole predefinita di ciascun 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 sia insensibile alle maiuscole, ad esempio:

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

Consulta la documentazione di riferimento sulla grammatica 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 di base nella clausola WHERE per specificare un periodo di data o ora.

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

Per informazioni dettagliate sull'utilizzo dei segmenti di date principali, consulta Segmentazione > Segmenti di date principali.

Filtri vietati

Non è consentito filtrare:

  • 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 es. Int64Value, StringValue e così via).
  • Negli attributi dei campi ripetuti di qualsiasi tipo di messaggio, ad eccezione di quelli primitivi (ad es. 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 schema: 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ù ordini

Puoi specificare più campi nella clausola ORDER BY utilizzando un elenco delimitato 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 per nome della campagna, in ordine decrescente per numero di impressioni e in ordine decrescente per 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

Combinare 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

Non è consentito ordinare:

  • In base agli attributi delle risorse non selezionate.
  • Per le metriche non selezionate.
  • Per i 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 metaparametri per la richiesta.

Includi bozze

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

Questa query di esempio restituisce sia le campagne di bozza che quelle standard:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Ometti elementi non selezionati: resource_name

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 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é viene 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 il calcolo di una metrica inclusa nella clausola SELECT. Il valore predefinito è 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ù