Referência de variáveis do sistema
O BigQuery é compatível com as variáveis de sistema a seguir para consultas de várias instruções ou em sessões. É possível usar variáveis do sistema para definir ou recuperar informações durante a execução da consulta, de maneira semelhante às variáveis de linguagem processuais definidas pelo usuário.
| Nome | Tipo | Leitura e gravação ou somente leitura | Descrição |
|---|---|---|---|
@@current_job_id |
STRING |
Somente leitura | ID do job em execução no momento. No contexto de uma consulta de várias instruções, isso retorna o job responsável pela instrução atual, e não a consulta inteira. |
@@dataset_id |
STRING |
Leitura e gravação |
ID do conjunto de dados padrão no projeto atual. Esse ID é usado quando um conjunto de dados não é especificado para um projeto na consulta. Use a instrução SET para atribuir @@dataset_id a outro ID de conjunto de dados no projeto atual. As variáveis de sistema @@dataset_project_id e @@dataset_id podem ser definidas e usadas em conjunto.
|
@@dataset_project_id |
STRING |
Leitura e gravação |
O ID do projeto padrão usado quando não é especificado um para o conjunto de dados usado na consulta. Se @@dataset_project_id não estiver definido ou se estiver definido como NULL, o projeto de execução de consulta (@@project_id) será usado. Use a instrução SET para atribuir @@dataset_project_id a outro ID do projeto. As variáveis de sistema @@dataset_project_id e @@dataset_id podem ser definidas e usadas em conjunto.
|
@@last_job_id |
STRING |
Somente leitura |
O ID do job mais recente a ser executado na consulta atual
de várias instruções, exceto o atual. Se a
consulta de várias instruções contiver instruções CALL,
esse job pode ter vindo de um procedimento diferente.
|
@@location |
STRING |
Leitura e gravação |
O local em que a consulta será executada. @@location só pode ser definido como um literal de string com um local válido.
Uma instrução SET @@location precisa ser a primeira instrução em uma
consulta. Ocorre um erro se houver uma incompatibilidade entre
@@location e outra
configuração de local
para a consulta. É possível melhorar a latência de consultas que definem
@@location usando
o modo de criação de job opcional. Você pode usar a variável de sistema @@location dentro de UDFs SQL e funções de tabela.
|
@@project_id |
STRING |
Somente leitura |
ID do projeto usado para executar a consulta atual. No
contexto de um procedimento, @@project_id se refere ao projeto
que está executando a consulta de várias instruções, e não ao projeto proprietário do procedimento.
|
@@query_label |
STRING |
Leitura e gravação |
Rótulo de consulta a ser associado a jobs de consulta na sessão ou consulta
de várias instruções atual. Se definido em uma consulta, todos os jobs de consulta subsequentes no script ou na sessão terão esse rótulo.
Se não for definido em uma consulta, o valor desta variável do sistema será
NULL. Para ver um exemplo de como definir essa variável do sistema,
consulte
Associar jobs em uma sessão a um rótulo.
|
@@reservation |
STRING |
Leitura e gravação |
Permite especificar ou substituir a reserva a ser usada para executar as instruções a seguir.
Precisa estar no seguinte formato:
projects/project_id/locations/location/reservations/reservation_id.
Para forçar a consulta a usar o faturamento sob demanda, defina essa variável como
O local da reserva precisa corresponder ao local em que a consulta
está sendo executada. Se |
@@row_count |
INT64 |
Somente leitura |
Se usado em uma consulta de várias instruções e a instrução anterior for DML, especifica o número de linhas inseridas, modificadas ou excluídas, como resultados dessa instrução DML. Se a instrução anterior for
uma instrução `MERGE`, @@row_count vai representar o número total combinado
de linhas inseridas, modificadas e excluídas. Esse valor será
NULL se não estiver em uma consulta de várias instruções.
|
@@script.bytes_billed |
INT64 |
Somente leitura |
Total de bytes faturados até o momento no job de consulta de várias instruções em execução no momento. Esse valor será NULL
se não estiver no job.
|
@@script.bytes_processed |
INT64 |
Somente leitura |
Total de bytes processados até o momento no job de consulta de várias instruções
em execução no momento. Esse valor será NULL
se não estiver no job.
|
@@script.creation_time |
TIMESTAMP |
Somente leitura |
Hora da criação do job de consulta de várias instruções
em execução no momento.
Esse valor será NULL se não estiver no job.
|
@@script.job_id |
STRING |
Somente leitura |
ID do job de consulta de várias instruções
em execução no momento. Esse valor será
NULL se não estiver no job.
|
@@script.num_child_jobs |
INT64 |
Somente leitura |
Número de jobs filhos concluídos no momento. Esse valor será
NULL se não estiver no job.
|
@@script.slot_ms |
INT64 |
Somente leitura |
Número de milissegundos de slot usados até o momento pelo script.
Esse valor será NULL se não estiver no job.
|
@@session_id |
STRING |
Somente leitura |
ID da sessão a que a consulta atual está associada. Você pode usar
a variável de sistema @@session_id em
funções definidas pelo usuário do
SQL,
funções de tabela e
visualizações lógicas. O uso dessa variável de sistema
em visualizações materializadas não é compatível.
|
@@time_zone |
STRING |
Leitura e gravação |
O fuso horário padrão a ser usado em funções SQL dependentes de fuso horário, quando um fuso horário explícito não é especificado como um argumento.
@@time_zone pode ser modificado usando uma instrução SET para qualquer nome de fuso horário válido.
No início de cada script, @@time_zone começa como
"UTC".
|
Para oferecer compatibilidade com versões anteriores, as expressões usadas em uma cláusula OPTIONS ou FOR SYSTEM TIME AS OF são padronizadas com o fuso horário America/Los_Angeles, enquanto todas as outras expressões de data e hora usam o fuso horário UTC. Se @@time_zone tiver sido definido na consulta de várias instruções, o fuso horário escolhido será aplicado a todas as expressões de data e hora, incluindo as cláusulas OPTIONS e FOR SYSTEM TIME AS OF.
Além das variáveis de sistema mostradas anteriormente, é possível usar variáveis de sistema EXCEPTION durante a execução de uma consulta de várias instruções. Saiba mais sobre as variáveis de sistema EXCEPTION na instrução de linguagem processual
BEGIN...EXCEPTION.
Exemplos
Não é possível criar variáveis do sistema, mas você pode modificar o valor padrão para algumas delas:
SET @@dataset_project_id = 'MyProject';
A seguinte consulta devolve o fuso horário padrão:
SELECT @@time_zone AS default_time_zone;
+-------------------+
| default_time_zone |
+-------------------+
| UTC |
+-------------------+
É possível usar variáveis do sistema com consultas em DDL e DML.
Por exemplo, confira a seguir algumas maneiras de usar a variável de sistema @@time_zone ao criar e atualizar uma tabela:
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;
Há alguns lugares em que as variáveis do sistema não podem ser usadas em consultas em DDL e DML. Por exemplo, não é possível usar uma variável do sistema como um nome de projeto, conjunto de dados ou nome de tabela. A consulta a seguir produz um erro quando você inclui a variável de sistema @@dataset_id em um caminho de tabela:
BEGIN
CREATE TEMP TABLE @@dataset_id.MyTempTable (id STRING);
END;
Para mais exemplos de como usar variáveis do sistema em consultas de várias instruções, consulte Definir uma variável.
Para ver exemplos de como usar as variáveis do sistema em sessões, consulte Exemplo de sessão.