Vista JOBS_BY_FOLDER

A vista INFORMATION_SCHEMA.JOBS_BY_FOLDER contém metadados praticamente em tempo real acerca de todas as tarefas enviadas na pasta principal do projeto atual, incluindo as tarefas nas subpastas abaixo.

Função necessária

Para receber a autorização de que precisa para consultar a vista INFORMATION_SCHEMA.JOBS_BY_FOLDER, peça ao seu administrador para lhe conceder a função de IAM visualizador de recursos do BigQuery (roles/bigquery.resourceViewer) na pasta principal. 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.listAll , que é necessária para consultar a vista INFORMATION_SCHEMA.JOBS_BY_FOLDER.

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 coluna query_info contém informações adicionais sobre as tarefas de consulta.

A vista INFORMATION_SCHEMA.JOBS_BY_FOLDER 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.
folder_numbers	REPEATED INTEGER	Os IDs numéricos das pastas que contêm o projeto, começando pela pasta que contém imediatamente o projeto, seguida da pasta que contém a pasta secundária e assim sucessivamente. Por exemplo, se folder_numbers for [1, 2, 3], a pasta 1 contém imediatamente o projeto, a pasta 2 contém 1 e a pasta 3 contém 2. Esta coluna só é preenchida em JOBS_BY_FOLDER.
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.
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_FOLDER, 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_FOLDER	Pasta que contém o 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`.
  Nota: tem de usar um qualificador de região para consultar as visualizações INFORMATION_SCHEMA. A localização da execução da consulta tem de corresponder à região da vista INFORMATION_SCHEMA.

Nota: quando consultar INFORMATION_SCHEMA.JOBS_BY_FOLDER para encontrar um custo de resumo de tarefas de consulta, deve excluir o tipo de declaração SCRIPT, caso contrário, alguns valores podem ser contabilizados duas vezes. A linha SCRIPT inclui valores de resumo para todas as tarefas secundárias que foram executadas como parte desta tarefa.

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_FOLDER

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_FOLDER.

Veja empregos interativos

A seguinte consulta apresenta o ID da tarefa, a hora de criação e o estado (PENDING, RUNNING ou DONE) de todas as tarefas interativas na pasta do projeto designado:

SELECT
  job_id,
  creation_time,
  state
FROM
  `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_FOLDER
WHERE
  priority = 'INTERACTIVE';

Nota: os nomes das INFORMATION_SCHEMAvistas são sensíveis a maiúsculas e minúsculas.

O resultado é semelhante ao seguinte:

+--------------+---------------------------+---------------------------------+
| job_id       |  creation_time            |  state                          |
+--------------+---------------------------+---------------------------------+
| bquxjob_1    |  2019-10-10 00:00:00 UTC  |  DONE                           |
| bquxjob_4    |  2019-10-10 00:00:03 UTC  |  RUNNING                        |
| bquxjob_5    |  2019-10-10 00:00:04 UTC  |  PENDING                        |
+--------------+---------------------------+---------------------------------+