Riferimento alle variabili di sistema

BigQuery supporta le seguenti variabili di sistema per le query con più istruzioni 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 con più istruzioni, restituisce il job responsabile dell'istruzione corrente, non l'intera query con più istruzioni.
@@dataset_id STRING Lettura e scrittura ID del set di dati predefinito nel progetto corrente. Questo ID viene utilizzato quando non viene specificato un set di dati per un progetto nella query. Puoi utilizzare l'istruzione SET per assegnare @@dataset_id a un altro ID set di dati 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 del job più recente da eseguire nella query con più istruzioni corrente, escluso quello corrente. Se la query con più istruzioni contiene istruzioni CALL, questo job potrebbe avere avuto origine 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 esiste una mancata corrispondenza tra @@location e un'altra impostazione di localizzazione per la query. Puoi migliorare la latenza delle query che impostano @@location utilizzando la modalità di creazione 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 inattività massimo per tutte le entità applicabili interrogate all'interno della query o della sessione con più istruzioni corrente. Le entità applicabili includono tabelle in streaming, tabelle Change Data Capture (CDC) e viste materializzate) interrogate all'interno della query o della sessione con più istruzioni corrente.

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

  • Riduci la latenza e i costi delle query: per tollerare i dati obsoleti, imposta @@max_staleness_override su un intervallo non negativo, ad esempio INTERVAL 10 MINUTE.
  • Assicurati di ottenere 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.
  • Cancella l'override: 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 corrente. 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 di query da associare ai job di query nella query o nella sessione con più istruzioni corrente. Se impostata in una query, tutti i job di query successivi nello script 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, consulta Associa i job di una sessione a un'etichetta.
@@reservation STRING Lettura e scrittura Consente di specificare o eseguire l'override della prenotazione da utilizzare per l'esecuzione delle istruzioni seguenti. Deve essere nel seguente formato: projects/project_id/locations/location/reservations/reservation_id.

Forza la query a utilizzare la fatturazione on demand se impostato su 'none'. Ciò richiede che il progetto o l'organizzazione abbia reservation_override_mode impostato su ALLOW_ANY_OVERRIDE. Questo valore può essere impostato utilizzando le istruzioni ALTER PROJECT SET OPTIONS o ALTER ORGANIZATION SET OPTIONS. In caso di problemi, richiedi assistenza.

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 in seguito all'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 con più istruzioni attualmente in esecuzione. Questo valore è NULL se non è presente nel job.
@@script.bytes_processed INT64 Sola lettura Byte totali elaborati finora nel job di query 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 con più istruzioni 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 ID della sessione a cui è associata la query corrente. Puoi utilizzare la variabile di sistema @@session_id all'interno di funzioni definite dall'utente SQL, funzioni di tabella e 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 utilizzano per impostazione predefinita il fuso orario America/Los_Angeles, mentre tutte le altre espressioni di data/ora utilizzano per impostazione predefinita il fuso orario UTC. Se @@time_zone è stato impostato in precedenza nella query con più istruzioni, 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

Le variabili di sistema non vengono create da te, ma puoi sostituire il valore predefinito per alcune di queste:

SET @@dataset_project_id = 'MyProject';

L'esempio seguente esegue l'override dell'intervallo di inattività 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 completamente aggiornati e applicare le modifiche in attesa al momento dell'esecuzione della query:

SET @@max_staleness_override = INTERVAL 0 SECOND;

Per ripristinare l'override dell'obsolescenza alle impostazioni a livello di tabella, imposta @@max_staleness_override su NULL:

SET @@max_staleness_override = NULL;

La query seguente 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 durante la creazione e l'aggiornamento di 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 punti 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 di un progetto, di un set di dati o di una 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 Imposta una variabile.

Per esempi di come utilizzare le variabili di sistema nelle sessioni, consulta Sessione di esempio.