Riferimento alle variabili di sistema

BigQuery supporta le seguenti variabili di sistema per le query multi-istruzione o all'interno delle sessioni. Puoi utilizzare le variabili di sistema per impostare o recuperare informazioni durante l'esecuzione delle query, in modo simile alle variabili del linguaggio procedurale definite dall'utente.

Nome Tipo Lettura e scrittura o sola lettura Descrizione
@@current_job_id STRING Sola lettura ID job del job attualmente in esecuzione. Nel contesto di una query multi-istruzione, restituisce il job responsabile dell'istruzione corrente, non l'intera query multi-istruzione.
@@dataset_id STRING Lettura e scrittura ID del set di dati predefinito nel progetto attuale. Questo ID viene utilizzato quando un set di dati non è specificato per un progetto nella query. Puoi utilizzare l'istruzione SET per assegnare @@dataset_id a un altro ID dataset nel progetto corrente. Le variabili di sistema @@dataset_project_id e @@dataset_id possono essere impostate e utilizzate insieme.
@@dataset_project_id STRING Lettura e scrittura ID del progetto predefinito utilizzato quando non ne viene specificato uno per un set di dati utilizzato nella query. Se @@dataset_project_id non è impostato o se è impostato su NULL, viene utilizzato il progetto di esecuzione delle query (@@project_id). Puoi utilizzare l'istruzione SET per assegnare @@dataset_project_id a un altro ID progetto. Le variabili di sistema @@dataset_project_id e @@dataset_id possono essere impostate e utilizzate insieme.
@@last_job_id STRING Sola lettura ID job dell'ultimo job da eseguire nella query multi-istruzione corrente, escluso quello attuale. Se la query multi-statement contiene CALL istruzioni, questo job potrebbe essere stato creato in una procedura diversa.
@@location STRING Lettura e scrittura La località in cui eseguire la query. @@location può essere impostato solo su un valore letterale stringa con una località valida. Un'istruzione SET @@location deve essere la prima istruzione di una query. Si verifica un errore se non corrisponde @@location a un'altra impostazione della posizione per la query. Puoi migliorare la latenza delle query che impostano @@location utilizzando la modalità di creazione dei job facoltativa. Puoi utilizzare la variabile di sistema @@location all'interno delle UDF SQL e delle funzioni di tabella.
@@max_staleness_override INTERVAL Lettura e scrittura Esegue l'override dell'intervallo di non aggiornamento massimo per tutte le entità applicabili di cui è stata eseguita una query all'interno della sessione o della query multi-istruzione corrente. Le entità applicabili includono tabelle in streaming, tabelle Change Data Capture (CDC) e viste materializzate) di cui è stata eseguita una query all'interno della sessione o della query multi-istruzione corrente.

Per impostazione predefinita, ogni volta che esegui una query, BigQuery restituisce i risultati più aggiornati o rispetta l'opzione max_staleness configurata per l'entità. Puoi utilizzare @@max_staleness_override per personalizzare dinamicamente il comportamento di obsolescenza senza modificare le configurazioni di tabelle o viste:

  • Ridurre la latenza e i costi delle query: per tollerare dati obsoleti, imposta @@max_staleness_override su un intervallo non negativo, ad esempio INTERVAL 10 MINUTE.
  • Garantisci risultati completamente aggiornati:per forzare l'applicazione di modifiche o aggiornamenti in attesa al momento dell'esecuzione della query, imposta @@max_staleness_override su INTERVAL 0 SECOND.
  • Annulla la sostituzione:per ripristinare le impostazioni max_staleness a livello di entità, imposta @@max_staleness_override su NULL.
@@project_id STRING Sola lettura ID del progetto utilizzato per eseguire la query attuale. Nel contesto di una procedura, @@project_id si riferisce al progetto che esegue la query con più istruzioni, non al progetto proprietario della procedura.
@@query_label STRING Lettura e scrittura Etichetta della query da associare ai job di query nella query o nella sessione multi-istruzione corrente. Se impostata in una query, tutte le query successive nel copione o nella sessione avranno questa etichetta. Se non viene impostato in una query, il valore di questa variabile di sistema è NULL. Per un esempio di come impostare questa variabile di sistema, vedi Associare i job di una sessione a un'etichetta.
@@reservation STRING Lettura e scrittura Consente di specificare o sostituire la prenotazione da utilizzare per l'esecuzione delle seguenti istruzioni. Deve essere nel seguente formato: projects/project_id/locations/location/reservations/reservation_id.

Forza la query a utilizzare la fatturazione on demand quando è impostata su 'none'. Per questa operazione è necessario che il progetto o l'organizzazione abbia reservation_override_mode impostato su ALLOW_ANY_OVERRIDE.

La località della prenotazione deve corrispondere a quella in cui viene eseguita la query. Se @@reservation è NULL, la prenotazione viene rilevata automaticamente in base alle impostazioni di assegnazione corrispondenti alle proprietà della query.
@@row_count INT64 Sola lettura Se utilizzata in una query con più istruzioni e l'istruzione precedente è DML, specifica il numero di righe inserite, modificate o eliminate a seguito di questa istruzione DML. Se l'istruzione precedente è un'istruzione `MERGE`, @@row_count rappresenta il numero totale combinato di righe inserite, modificate ed eliminate. Questo valore è NULL se non si trova in una query con più istruzioni.
@@script.bytes_billed INT64 Sola lettura Byte totali fatturati finora nel job di query multi-istruzione attualmente in esecuzione. Questo valore è NULL se non è presente nel job.
@@script.bytes_processed INT64 Sola lettura Il numero totale di byte elaborati finora nel job di query <x0A> con più istruzioni attualmente in esecuzione. Questo valore è NULL se non è presente nel job.
@@script.creation_time TIMESTAMP Sola lettura Ora di creazione del job di query con più istruzioni attualmente in esecuzione. Questo valore è NULL se non è presente nel job.
@@script.job_id STRING Sola lettura ID job del job di query multi-istruzione attualmente in esecuzione. Questo valore è NULL se non è presente nel job.
@@script.num_child_jobs INT64 Sola lettura Numero di job secondari attualmente completati. Questo valore è NULL se non è presente nel job.
@@script.slot_ms INT64 Sola lettura Numero di millisecondi di slot utilizzati finora dallo script. Questo valore è NULL se non è presente nel job.
@@session_id STRING Sola lettura L'ID della sessione a cui è associata la query corrente. Puoi utilizzare la variabile di sistema @@session_id all'interno delle funzioni definite dall'utente SQL, delle funzioni di tabella e delle viste logiche. L'utilizzo di questa variabile di sistema nelle viste materializzate non è supportato.
@@time_zone STRING Lettura e scrittura Il fuso orario predefinito da utilizzare nelle funzioni SQL dipendenti dal fuso orario, quando non ne è specificato uno come argomento. @@time_zone può essere modificato utilizzando un'istruzione SET con qualsiasi nome di fuso orario valido. All'inizio di ogni script, @@time_zone inizia come "UTC".

Per la compatibilità con le versioni precedenti, le espressioni utilizzate in una clausola OPTIONS o FOR SYSTEM TIME AS OF vengono impostate per impostazione predefinita sul fuso orario America/Los_Angeles, mentre tutte le altre espressioni di data/ora vengono impostate per impostazione predefinita sul fuso orario UTC. Se @@time_zone è stato impostato in precedenza nella query multi-istruzione, il fuso orario scelto verrà applicato a tutte le espressioni di data/ora, incluse le clausole OPTIONS e FOR SYSTEM TIME AS OF.

Oltre alle variabili di sistema mostrate in precedenza, puoi utilizzare le variabili di sistema EXCEPTION durante l'esecuzione di una query con più istruzioni. Per saperne di più sulle variabili di sistema EXCEPTION, consulta l'istruzione del linguaggio procedurale BEGIN...EXCEPTION.

Esempi

Non crei variabili di sistema, ma puoi sostituire il valore predefinito per alcune di queste:

SET @@dataset_project_id = 'MyProject';

L'esempio seguente esegue l'override dell'intervallo di non aggiornamento massimo per le query successive nella sessione impostandolo su 10 minuti:

SET @@max_staleness_override = INTERVAL 10 MINUTE;

Per forzare le query a restituire i risultati più recenti e aggiornati e applicare le modifiche in attesa al momento dell'esecuzione della query:

SET @@max_staleness_override = INTERVAL 0 SECOND;

Per ripristinare l'override della non aggiornamento alle impostazioni a livello di tabella, imposta @@max_staleness_override su NULL:

SET @@max_staleness_override = NULL;

La seguente query restituisce il fuso orario predefinito:

SELECT @@time_zone AS default_time_zone;

+-------------------+
| default_time_zone |
+-------------------+
| UTC               |
+-------------------+

Puoi utilizzare le variabili di sistema con le query DDL e DML. Ad esempio, ecco alcuni modi per utilizzare la variabile di sistema @@time_zone quando crei e aggiorni una tabella:

BEGIN
  CREATE TEMP TABLE MyTempTable
  AS SELECT @@time_zone AS default_time_zone;
END;

CREATE OR REPLACE TABLE MyDataset.MyTable(default_time_zone STRING)
  OPTIONS (description = @@time_zone);

UPDATE MyDataset.MyTable
SET default_time_zone = @@time_zone
WHERE TRUE;

Esistono alcuni casi in cui le variabili di sistema non possono essere utilizzate nelle query DDL e DML. Ad esempio, non puoi utilizzare una variabile di sistema come nome del progetto, set di dati o tabella. La seguente query genera un errore quando includi la variabile di sistema @@dataset_id in un percorso della tabella:

BEGIN
  CREATE TEMP TABLE @@dataset_id.MyTempTable (id STRING);
END;

Per altri esempi di come utilizzare le variabili di sistema nelle query con più istruzioni, consulta Impostare una variabile.

Per esempi di come utilizzare le variabili di sistema nelle sessioni, consulta Esempio di sessione.