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 Código da tarefa 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 código da tarefa 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 uma string literal com um local válido. Uma instrução SET @@location precisa ser a primeira em uma consulta. Ocorre um erro se houver uma incompatibilidade entre @@location e outra configurações de localização para a consulta. É possível melhorar a latência das consultas que definem @@location usando o modo opcional de criação de jobs. É possível usar a variável de sistema @@location em UDFs SQL e funções de tabela.
@@max_staleness_override INTERVAL Leitura e gravação Substitui o intervalo máximo de inatividade de todas as entidades aplicáveis consultadas na sessão ou consulta de várias instruções atual. As entidades aplicáveis incluem tabelas transmitidas, tabelas de captura de dados alterados (CDC) e visualizações materializadas) consultadas na consulta ou sessão de várias instruções atual.

Por padrão, sempre que você executa uma consulta, o BigQuery retorna os resultados mais atualizados ou respeita a opção max_staleness configurada da entidade. É possível usar @@max_staleness_override para personalizar dinamicamente o comportamento de desatualização sem alterar as configurações de tabela ou visualização:

  • Reduzir a latência e os custos da consulta: para tolerar dados desatualizados, defina @@max_staleness_override como um intervalo não negativo, por exemplo, INTERVAL 10 MINUTE.
  • Garantir resultados totalmente atualizados: para forçar a aplicação de modificações ou atualizações pendentes no momento da execução da consulta, defina @@max_staleness_override como INTERVAL 0 SECOND.
  • Limpar a substituição: para reverter para as configurações de max_staleness no nível da entidade, defina @@max_staleness_override como NULL.
@@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.

Força a consulta a usar o faturamento sob demanda quando definido como 'none'. Para isso, o projeto ou a organização precisa ter reservation_override_mode definido como ALLOW_ANY_OVERRIDE. Esse valor pode ser definido usando as instruções ALTER PROJECT SET OPTIONS ou ALTER ORGANIZATION SET OPTIONS. Em caso de problemas, peça suporte.

O local da reserva precisa corresponder ao local em que a consulta está sendo executada. Se @@reservation for NULL, a reserva será detectada automaticamente com base nas configurações de atribuição que correspondem às propriedades da consulta.
@@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, alteradas ou excluídas, como resultados dessa instrução DML. Se a instrução anterior for "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 código da tarefa 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. É possível 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';

O exemplo a seguir substitui o intervalo máximo de desatualização para consultas subsequentes na sessão para 10 minutos:

SET @@max_staleness_override = INTERVAL 10 MINUTE;

Para forçar as consultas a retornar os resultados mais recentes e totalmente atualizados e aplicar modificações pendentes no momento da execução da consulta:

SET @@max_staleness_override = INTERVAL 0 SECOND;

Para redefinir a substituição de desatualização para as configurações no nível da tabela, defina @@max_staleness_override como NULL:

SET @@max_staleness_override = NULL;

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 ver mais exemplos de como usar as 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.