Visualização JOBS_BY_FOLDER

A visualização INFORMATION_SCHEMA.JOBS_BY_FOLDER contém os metadados quase em tempo real sobre todos os jobs enviados na pasta pai do projeto atual, incluindo os jobs em subpastas abaixo dele.

Papel necessário

Para ter a permissão de que você precisa para consultar a visualização INFORMATION_SCHEMA.JOBS_BY_FOLDER, peça para seu administrador conceder a você o papel do IAM de Visualizador de recursos do BigQuery (roles/bigquery.resourceViewer) na pasta principal. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém a permissão bigquery.jobs.listAll, que é necessária para consultar a visualização INFORMATION_SCHEMA.JOBS_BY_FOLDER.

Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre as permissões do BigQuery, consulte Controle de acesso com o IAM.

Schema

Os dados subjacentes são particionados pela coluna creation_time e agrupados por project_id e user_email. A coluna query_info contém mais informações sobre os jobs de consulta.

A visualização INFORMATION_SCHEMA.JOBS_BY_FOLDER tem o seguinte esquema:

Nome da coluna	Tipo de dado	Valor
bi_engine_statistics	RECORD	Se o projeto estiver configurado para usar a BI Engine SQL Interface, este campo conterá BiEngineStatistics. Se esse não for seu caso, NULL.
cache_hit	BOOLEAN	Se os resultados da consulta deste job eram de um cache. Se você tiver um job de instrução de várias consultas, o cache_hit da consulta mãe será NULL.
creation_time	TIMESTAMP	(Coluna de particionamento) horário da criação do job. O particionamento é baseado no horário UTC desse carimbo de data/hora.
destination_table	RECORD	Tabela de destino dos resultados (se houver).
end_time	TIMESTAMP	O horário de término do job, em milissegundos, desde o período. Esse campo representa o momento em que o job entra no estado DONE.
error_result	RECORD	Detalhes dos erros como objetos ErrorProto.
folder_numbers	REPEATED INTEGER	IDs de número das pastas que contêm o projeto, começando com a pasta que contém o projeto imediatamente, seguido pela pasta que contém a pasta filho e assim por diante. Por exemplo, se folder_numbers for [1, 2, 3], a pasta 1 conterá imediatamente o projeto, a pasta 2 conterá 1, e a pasta 3 conterá 2. Essa coluna é preenchida apenas em JOBS_BY_FOLDER.
job_id	STRING	O ID do job. Por exemplo, bquxjob_1234.
job_stages	RECORD	Estágios de consulta do job. Observação: os valores desta coluna estão vazios para consultas lidas em tabelas com políticas de acesso no nível da linha. Para mais informações, consulte práticas recomendadas para segurança no nível da linha no BigQuery.
job_type	STRING	O tipo de job. Pode ser QUERY, LOAD, EXTRACT, COPY ou NULL. Um valor NULL indica um job interno, como uma avaliação de instrução de job de script ou uma atualização de visualização materializada.
labels	RECORD	Matriz de identificadores aplicados ao job como pares de chave-valor.
parent_job_id	STRING	ID do job pai (se houver).
priority	STRING	A prioridade deste job. Os valores válidos incluem INTERACTIVE e BATCH.
project_id	STRING	(Coluna de clustering) é o ID do projeto.
project_number	INTEGER	O número do projeto.
query	STRING	Texto da consulta SQL. Apenas a visualização JOBS_BY_PROJECT tem a coluna de consulta.
referenced_tables	RECORD	Matriz de tabelas referenciadas pelo job. Preenchido apenas para jobs de consulta que não são ocorrências em cache.
reservation_id	STRING	Nome da reserva principal atribuída a este job, 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: o local da reserva RESERVATION_NAME: o nome da reserva
session_info	RECORD	Detalhes sobre a sessão em que este job foi executado, se houver. (Visualização)
start_time	TIMESTAMP	Horário de início do job, em milissegundos, desde o período. Esse campo representa o momento em que o job faz a transição do estado PENDING para RUNNING ou DONE.
state	STRING	Estado em execução do job. Os estados válidos incluem PENDING, RUNNING e DONE.
statement_type	STRING	O tipo de instrução de consulta. Por exemplo, DELETE, INSERT, SCRIPT, SELECT ou UPDATE. Consulte QueryStatementType para acessar uma lista de valores válidos.
timeline	RECORD	Cronograma de consulta do job. Contém snapshots de execução de consulta.
total_bytes_billed	INTEGER	Se o projeto estiver configurado para usar preços sob demanda, então esse campo conterá o total de bytes cobrados pelo job. Se o projeto estiver configurado para usar preços fixos, então você não será cobrado por bytes, e esse campo será apenas informativo. Observação: os valores desta coluna estão vazios para consultas lidas em tabelas com políticas de acesso no nível da linha. Para mais informações, consulte práticas recomendadas para segurança no nível da linha no BigQuery.
total_bytes_processed	INTEGER	Total de bytes processados pelo job. Observação: os valores desta coluna estão vazios para consultas lidas em tabelas com políticas de acesso no nível da linha. Para mais informações, consulte práticas recomendadas para segurança no nível da linha no BigQuery.
total_modified_partitions	INTEGER	Número total de partições do job modificado. Esse campo é preenchido para jobs LOAD e QUERY.
total_slot_ms	INTEGER	Milissegundos de slot para o job durante toda a duração no estado RUNNING, incluindo novas tentativas.
transaction_id	STRING	ID da transação em que este job foi executado, se houver. (Visualização)
user_email	STRING	(Coluna de clustering) endereço de e-mail ou conta de serviço do usuário que executou o job.
query_info.resource_warning	STRING	A mensagem de aviso que aparece quando o uso de recursos durante o processamento da consulta está acima do limite interno do sistema. Um job de consulta bem-sucedido pode ter o campo resource_warning preenchido. Com o resource_warning, você ganha mais pontos de dados para otimizar suas consultas e configurar o monitoramento das tendências de desempenho de um conjunto equivalente de consultas usando query_hashes.
query_info.query_hashes.normalized_literals	STRING	Contém os hashes da consulta. normalized_literals é um hash STRING hexadecimal que ignora comentários, valores de parâmetros, UDFs e literais. Esse campo aparece para consultas bem-sucedidas do GoogleSQL que não são ocorrências em cache.
query_info.performance_insights	RECORD	Insights de desempenho para o job.
query_info.optimization_details	STRUCT	As otimizações baseadas em histórico do job.
transferred_bytes	INTEGER	Total de bytes transferidos para consultas entre nuvens, como jobs de transferência entre nuvens do BigQuery Omni.
materialized_view_statistics	RECORD	Estatísticas de visualizações materializadas consideradas em um job de consulta. (Visualização)

Retenção de dados

Essa visualização contém os jobs em execução e o histórico dos últimos 180 dias.

Escopo e sintaxe

As consultas nessa visualização precisam incluir um qualificador de região. A tabela a seguir explica o escopo da região dessa visualização:

Nome da visualização	Escopo do recurso	Escopo da região
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.JOBS_BY_FOLDER	Pasta que contém o projeto especificado	REGION

Substitua:

• Opcional: PROJECT_ID: o ID do seu projeto do Google Cloud. Se não for especificado, o projeto padrão será usado.
• REGION: qualquer nome da região do conjunto de dados. Por exemplo, region-us.

Observação: é necessário usar um qualificador de região para consultar visualizações INFORMATION_SCHEMA. O local de execução da consulta precisa corresponder à região da visualização INFORMATION_SCHEMA.

Observação: ao consultar INFORMATION_SCHEMA.JOBS_BY_FOLDER para encontrar um custo de resumo dos jobs de consulta, exclua o tipo de instrução SCRIPT. Caso contrário, alguns valores poderão ser contados duas vezes. A linha SCRIPT inclui valores de resumo para todos os jobs filhos que foram executados como parte desse job.

Exemplo

A consulta a seguir exibe o ID do job, a hora da criação e o estado (PENDING, RUNNING ou DONE) de todos os jobs interativos na pasta do projeto designada:

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

Observação: os nomes da visualização INFORMATION_SCHEMA diferenciam maiúsculas e minúsculas.

O resultado será semelhante ao seguinte:

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

Receber bytes processados por jobs de exportação

O exemplo a seguir calcula o valor total_processed_bytes para tipos de job EXTRACT. Para informações sobre cotas para jobs de exportação, consulte Política de cotas para jobs de exportação. O total de bytes processados pode ser usado para monitorar o uso agregado e garantir que os jobs de exportação permaneçam abaixo do limite de 50 TB por dia:

SELECT
    DATE(creation_time) as day,
    project_id as source_project_id,
    SUM(total_bytes_processed) AS total_bytes_processed
 FROM
   region-us.INFORMATION_SCHEMA.JOBS_BY_PROJECT
 WHERE
    creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 8 DAY) AND CURRENT_TIMESTAMP()
    AND job_type = "EXTRACT"
GROUP BY
    day,
    source_project_id
ORDER BY
    day DESC

Usar jobs de cópia

Para informações sobre jobs de cópia, consulte Copiar uma tabela. O exemplo a seguir fornece o uso de jobs de cópia:

SELECT
    DATE(creation_time) as day,
    project_id as source_project_id,
CONCAT(destination_table.project_id,":",destination_table.dataset_id,".",destination_table.table_id) as destination_table,
    COUNT(job_id) AS copy_job_count
 FROM
   region-us.INFORMATION_SCHEMA.JOBS_BY_PROJECT
 WHERE
    creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 8 DAY) AND CURRENT_TIMESTAMP()
    AND job_type = "COPY"
GROUP BY
    day,
    source_project_id,
    destination_table
ORDER BY
    day DESC

Conferir insights de desempenho para consultas

O exemplo a seguir retorna todos os jobs de consulta que têm insights de desempenho da pasta do projeto designado nos últimos 30 dias, com um URL que leva ao gráfico de execução da consulta no console do Google Cloud.

SELECT
  `bigquery-public-data`.persistent_udfs.job_url(
    project_id || ':us.' || job_id) AS job_url,
  query_info.performance_insights
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS_BY_FOLDER
WHERE
  DATE(creation_time) >= CURRENT_DATE - 30 -- scan 30 days of query history
  AND job_type = 'QUERY'
  AND state = 'DONE'
  AND error_result IS NULL
  AND statement_type != 'SCRIPT'
  AND EXISTS ( -- Only include queries which had performance insights
    SELECT 1
    FROM UNNEST(
      query_info.performance_insights.stage_performance_standalone_insights
    )
    WHERE slot_contention OR insufficient_shuffle_quota
    UNION ALL
    SELECT 1
    FROM UNNEST(
      query_info.performance_insights.stage_performance_change_insights
    )
    WHERE input_data_change.records_read_diff_percentage IS NOT NULL
  );