Vista JOBS_BY_USER

A vista INFORMATION_SCHEMA.JOBS_BY_USER contém metadados praticamente em tempo real sobre as tarefas do BigQuery enviadas pelo utilizador atual no projeto atual.

Função necessária

Para receber a autorização de que precisa para consultar a vista INFORMATION_SCHEMA.JOBS_BY_USER, peça ao seu administrador para lhe conceder a função de utilizador do BigQuery (roles/bigquery.user) do IAM no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém a autorização bigquery.jobs.list , que é necessária para consultar a vista INFORMATION_SCHEMA.JOBS_BY_USER.

Também pode obter esta autorização com funções personalizadas ou outras funções predefinidas.

Para mais informações sobre as autorizações do BigQuery, consulte o artigo Controlo de acesso com a IAM.

Esquema

Os dados subjacentes são particionados pela coluna creation_time e agrupados por project_id e user_email.

A vista INFORMATION_SCHEMA.JOBS_BY_USER tem o seguinte esquema:

Nome da coluna Tipo de dados Valor
bi_engine_statistics RECORD Se o projeto estiver configurado para usar o BI Engine, este campo contém BiEngineStatistics. Caso contrário, NULL.
cache_hit BOOLEAN Se os resultados da consulta deste trabalho foram provenientes de uma cache. Se tiver um trabalho de declaração de várias consultas, cache_hit o ID da consulta principal é NULL.
creation_time TIMESTAMP (Coluna de partição) Hora da criação desta tarefa. A partição baseia-se na data/hora UTC desta data/hora.
destination_table RECORD Tabela de destino para resultados, se existir.
dml_statistics RECORD Se a tarefa for uma consulta com uma declaração DML, o valor é um registo com os seguintes campos:
  • inserted_row_count: o número de linhas que foram inseridas.
  • deleted_row_count: o número de linhas que foram eliminadas.
  • updated_row_count: o número de linhas que foram atualizadas.
Para todos os outros trabalhos, o valor é NULL.
Esta coluna está presente nas vistas INFORMATION_SCHEMA.JOBS_BY_USER e INFORMATION_SCHEMA.JOBS_BY_PROJECT.
end_time TIMESTAMP A hora de fim desta tarefa, em milissegundos desde a época. Este campo representa a hora em que a tarefa entra no estado DONE.
error_result RECORD Detalhes de quaisquer erros como objetos ErrorProto.
job_creation_reason.code STRING Especifica o motivo geral pelo qual foi criado um trabalho.
Os valores possíveis são:
  • REQUESTED: foi pedida a criação de uma tarefa.
  • LONG_RUNNING: o pedido de consulta foi executado para além de um tempo limite definido pelo sistema especificado pelo campo timeoutMs no QueryRequest. Como tal, foi considerada uma operação de execução prolongada para a qual foi criado um trabalho.
  • LARGE_RESULTS: os resultados da consulta não cabem na resposta inline.
  • OTHER: o sistema determinou que a consulta tem de ser executada como uma tarefa.
job_id STRING O ID da tarefa, se tiver sido criada uma tarefa. Caso contrário, o ID da consulta de uma consulta que usa o modo de criação de tarefas opcional. Por exemplo, bquxjob_1234.
job_stages RECORD Fases da consulta da tarefa.

Nota: os valores desta coluna estão vazios para consultas que leem a partir de tabelas com políticas de acesso ao nível das linhas. Para mais informações, consulte as práticas recomendadas para a segurança ao nível da linha no BigQuery.

job_type STRING O tipo de trabalho. Pode ser QUERY, LOAD, EXTRACT, COPY ou NULL. Um valor NULL indica uma tarefa em segundo plano.
labels RECORD Matriz de etiquetas aplicadas à tarefa como pares de chave-valor.
parent_job_id STRING ID da tarefa principal, se existir.
priority STRING A prioridade desta tarefa. Os valores válidos incluem INTERACTIVE e BATCH.
project_id STRING (Coluna de agrupamento) O ID do projeto.
project_number INTEGER O número do projeto.
query STRING Texto da consulta SQL.
referenced_tables RECORD Matriz de tabelas referenciadas pela tarefa. Preenchido apenas para tarefas de consulta que não são resultados da cache.
reservation_id STRING Nome da reserva principal atribuída a esta tarefa, no formato RESERVATION_ADMIN_PROJECT:RESERVATION_LOCATION.RESERVATION_NAME.
Nesta saída:
  • RESERVATION_ADMIN_PROJECT: o nome do projeto do Google Cloud que administra a reserva
  • RESERVATION_LOCATION: a localização da reserva
  • RESERVATION_NAME: o nome da reserva
edition STRING A edição associada à reserva atribuída a esta tarefa. Para mais informações sobre as edições, consulte o artigo Introdução às edições do BigQuery.
session_info RECORD Detalhes sobre a sessão em que esta tarefa foi executada, se aplicável.
start_time TIMESTAMP A hora de início desta tarefa, em milissegundos desde a época. Este campo representa a hora em que a tarefa passa do estado PENDING para RUNNING ou DONE.
state STRING Estado de execução da tarefa. Os estados válidos incluem PENDING, RUNNING e DONE.
statement_type STRING O tipo de declaração de consulta. Por exemplo, DELETE, INSERT, SCRIPT, SELECT ou UPDATE. Consulte QueryStatementType para ver a lista de valores válidos.
timeline RECORD Linha cronológica da consulta da tarefa. Contém instantâneos da execução de consultas.
total_bytes_billed INTEGER Se o projeto estiver configurado para usar preços a pedido, este campo contém o total de bytes faturados para a tarefa. Se o projeto estiver configurado para usar preços de taxa fixa, não lhe é faturado o número de bytes, e este campo é apenas informativo.

Nota: os valores desta coluna estão vazios para consultas que leem a partir de tabelas com políticas de acesso ao nível das linhas. Para mais informações, consulte as práticas recomendadas para a segurança ao nível da linha no BigQuery.

total_bytes_processed INTEGER

Total de bytes processados pela tarefa.

Nota: os valores desta coluna estão vazios para consultas que leem a partir de tabelas com políticas de acesso ao nível das linhas. Para mais informações, consulte as práticas recomendadas para a segurança ao nível da linha no BigQuery.

total_modified_partitions INTEGER O número total de partições que a tarefa modificou. Este campo é preenchido para trabalhos de LOAD e QUERY.
total_slot_ms INTEGER Slot milliseconds for the job over its entire duration in the RUNNING state, including retries.
total_services_sku_slot_ms INTEGER Total de milissegundos de espaço para a tarefa executada em serviços externos e faturada no SKU de serviços. Este campo só é preenchido para tarefas que têm custos de serviço externos e é o total da utilização para custos cujo método de faturação é "SERVICES_SKU".
transaction_id STRING ID da transação em que esta tarefa foi executada, se existir.
user_email STRING (Coluna de agrupamento) Endereço de email ou conta de serviço do utilizador que executou a tarefa.
query_info.resource_warning STRING A mensagem de aviso que é apresentada se a utilização de recursos durante o processamento de consultas estiver acima do limite interno do sistema.
Um trabalho de consulta bem-sucedido pode ter o campo resource_warning preenchido. Com o resource_warning, recebe pontos de dados adicionais para otimizar as suas consultas e configurar a monitorização das tendências de desempenho de um conjunto equivalente de consultas através do query_hashes.
query_info.query_hashes.normalized_literals STRING Contém o valor hash da consulta. normalized_literals é um hash hexadecimal STRING que ignora comentários, valores de parâmetros, funções definidas pelo utilizador e literais. O valor hash difere quando as vistas subjacentes mudam ou se a consulta faz referência implícita a colunas, como SELECT *, e o esquema da tabela muda.
Este campo é apresentado para consultas GoogleSQL bem-sucedidas que não são resultados da cache.
query_info.performance_insights RECORD Estatísticas de desempenho para a tarefa.
query_info.optimization_details STRUCT As otimizações baseadas no histórico para a tarefa. Apenas a vista JOBS_BY_PROJECT tem esta coluna.
transferred_bytes INTEGER Total de bytes transferidos para consultas entre nuvens, como tarefas de transferência entre nuvens do BigQuery Omni.
materialized_view_statistics RECORD Estatísticas das vistas materializadas consideradas numa tarefa de consulta. (Pré-visualização)
metadata_cache_statistics RECORD Estatísticas de utilização do índice da coluna de metadados para tabelas referenciadas numa tarefa de consulta.
search_statistics RECORD Estatísticas de uma consulta de pesquisa.
query_dialect STRING Este campo vai estar disponível em maio de 2025. O dialeto de consulta usado para a tarefa. Os valores válidos incluem:
  • GOOGLE_SQL: o trabalho foi pedido para usar o GoogleSQL.
  • LEGACY_SQL: foi pedido que a tarefa usasse SQL antigo.
  • DEFAULT_LEGACY_SQL: não foi especificado nenhum dialeto de consulta no pedido de tarefa. O BigQuery usou o valor predefinido do SQL antigo.
  • DEFAULT_GOOGLE_SQL: não foi especificado nenhum dialeto de consulta no pedido de tarefa. O BigQuery usou o valor predefinido do GoogleSQL.

Este campo só é preenchido para tarefas de consulta. A seleção predefinida do dialeto de consulta pode ser controlada pelas definições de configuração.
continuous BOOLEAN Se o trabalho é uma consulta contínua.
continuous_query_info.output_watermark TIMESTAMP Representa o ponto até ao qual a consulta contínua processou dados com êxito.
vector_search_statistics RECORD Estatísticas para uma consulta de pesquisa vetorial.

Para garantir a estabilidade, recomendamos que liste explicitamente as colunas nas suas consultas de esquema de informações em vez de usar um caráter universal (SELECT *). A listagem explícita de colunas impede que as consultas sejam interrompidas se o esquema subjacente for alterado.

Retenção de dados

Esta vista apresenta as tarefas em execução, juntamente com o histórico de tarefas dos últimos 180 dias. Se um projeto for migrado para uma organização (quer não tenha nenhuma organização ou seja migrado de uma organização diferente), as informações de tarefas anteriores à data de migração não são acessíveis através da visualização INFORMATION_SCHEMA.JOBS_BY_USER, uma vez que a visualização apenas retém dados a partir da data de migração.

Âmbito e sintaxe

As consultas nesta vista têm de incluir um qualificador de região. A tabela seguinte explica o âmbito da região para esta vista:

Nome da visualização de propriedade Âmbito do recurso Âmbito da região
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.JOBS_BY_USER Tarefas enviadas pelo utilizador atual no projeto especificado. REGION
Substitua o seguinte:
  • Opcional: PROJECT_ID: o ID do seu projeto do Google Cloud Google Cloud. Se não for especificado, é usado o projeto predefinido.
  • REGION: qualquer nome da região do conjunto de dados. Por exemplo, `region-us`.

Exemplos

Para executar a consulta num projeto que não seja o seu projeto predefinido, adicione o ID do projeto no seguinte formato: 

`PROJECT_ID`.`region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_USER
 Substitua o seguinte:

  • PROJECT_ID: o ID do projeto
  • REGION_NAME: a região do seu projeto

Por exemplo, `myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_BY_USER.

Veja tarefas pendentes ou em execução

A consulta seguinte apresenta o ID da tarefa, a hora de criação e a consulta de todas as tarefas pendentes ou em execução enviadas pelo utilizador atual no projeto designado:

SELECT
  job_id,
  creation_time,
  query
FROM
  `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_USER
WHERE
  state != 'DONE';

O resultado é semelhante ao seguinte:

+--------------+---------------------------+---------------------------------+
| job_id       |  creation_time            |  query                          |
+--------------+---------------------------+---------------------------------+
| bquxjob_1    |  2019-10-10 00:00:00 UTC  |  SELECT ... FROM dataset.table1 |
| bquxjob_2    |  2019-10-10 00:00:01 UTC  |  SELECT ... FROM dataset.table2 |
| bquxjob_3    |  2019-10-10 00:00:02 UTC  |  SELECT ... FROM dataset.table3 |
+--------------+---------------------------+---------------------------------+