Visualização JOBS

A visualização INFORMATION_SCHEMA.JOBS contém os metadados em tempo real sobre todos os jobs do BigQuery no projeto atual.

Permissão necessária

Para consultar a visualização INFORMATION_SCHEMA.JOBS, você precisa da permissão bigquery.jobs.listAll Identity and Access Management (IAM) do projeto. Cada um dos seguintes papéis predefinidos do IAM inclui a permissão necessária:

  • Administrador do BigQuery
  • Administrador de recursos do BigQuery
  • Editor de recursos do BigQuery
  • Leitor de recursos do BigQuery

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 visualização INFORMATION_SCHEMA.JOBS tem o seguinte esquema:

Nome da coluna Tipo de dados Valor
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.
project_id STRING (Coluna de clustering) ID do projeto.
project_number INTEGER Número do projeto.
user_email STRING (Coluna de clustering) endereço de e-mail ou conta de serviço do usuário que executou o job.
job_id STRING ID do job. Por exemplo, bquxjob_1234.
job_type STRING O tipo de job. Pode ser QUERY, LOAD, EXTRACT, COPY, ou null. O tipo de job null indica um job interno, como avaliação da instrução do job de script ou atualização da visualização materializada.
statement_type STRING O tipo de instrução de consulta, se for válido. Por exemplo, SELECT, INSERT, UPDATE, DELETE, ou SCRIPT. Consulte QueryStatementType para ver uma lista de valores válidos.
priority STRING A prioridade deste job. Os valores válidos incluem INTERACTIVE e BATCH.
start_time TIMESTAMP Horário de início deste job.
end_time TIMESTAMP Horário de término deste job.
query STRING Texto da consulta SQL. Observação: apenas a visualização JOBS_BY_PROJECT tem a coluna query.
state STRING Estado em execução do job. Os estados válidos incluem PENDING, RUNNING, e DONE.
reservation_id STRING Nome da principal reserva atribuída a este job, se aplicável. Se o job for executado em um projeto atribuído a uma reserva, ele terá o seguinte 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
total_bytes_processed INTEGER Total de bytes processados pelo job.
total_slot_ms INTEGER Milissegundos de slot do job ao longo de sua duração.
error_result RECORD Detalhes do erro (se houver), como um ErrorProto.
cache_hit BOOLEAN Se os resultados da consulta deste job eram de um cache.
destination_table RECORD Tabela de destino dos resultados (se houver).
referenced_tables RECORD Matriz de tabelas referenciadas pelo job. Preenchido apenas para jobs de consulta.
labels RECORD Matriz de rótulos aplicados ao job como strings key e value.
timeline RECORD Cronograma de consulta do job. Contém snapshots de execução de consulta.
job_stages RECORD Estágios de consulta do job.
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.
parent_job_id STRING ID do job pai (se houver).
transaction_id STRING ID da transação em que este job foi executado, se houver. (Visualização)
session_info RECORD Detalhes sobre a sessão em que este job foi executado, se houver. (Visualização)
dml_statistics RECORD

Se o job for uma consulta com uma instrução DML, o valor será um registro 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 excluídas.
  • updated_row_count: o número de linhas que foram atualizadas.

Para todos os outros jobs, o valor é NULL.

Essa coluna está presente nas visualizações INFORMATION_SCHEMA.JOBS_BY_USER e INFORMATION_SCHEMA.JOBS_BY_PROJECT.

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.
total_modified_partitions INTEGER Número total de partições do job modificado. Esse campo é preenchido para jobs LOAD e QUERY.

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. Se você não especificar um qualificador regional, os metadados serão recuperados de todas as regiões. 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_PROJECT] Nível do projeto REGION
Substitua:

  • Opcional: PROJECT_ID: o ID do seu projeto do 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.

Ao consultar INFORMATION_SCHEMA.JOBS 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.

Examples

Para executar a consulta em um projeto diferente do projeto padrão, adicione o ID do projeto no seguinte formato:

`PROJECT_ID`.`region-REGION_NAME`.INFORMATION_SCHEMA.JOBS
Substitua:

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

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

O exemplo a seguir calcula a utilização média de slots para todas as consultas nos últimos sete dias de um determinado projeto. Esse cálculo é mais preciso para projetos que têm uso de slot consistente ao longo da semana. Se o projeto não tiver uso de slot consistente, esse número poderá ser menor do que o esperado.

Para executar a consulta, faça o seguinte:

SELECT
  SUM(total_slot_ms) / (1000 * 60 * 60 * 24 * 7) AS avg_slots
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS
WHERE
  -- Filter by the partition column first to limit the amount of data scanned.
  -- Eight days allows for jobs created before the 7 day end_time filter.
  creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 8 DAY) AND CURRENT_TIMESTAMP()
  AND job_type = 'QUERY'
  AND end_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) AND CURRENT_TIMESTAMP();

O resultado será semelhante ao seguinte:

+------------+
| avg_slots  |
+------------+
| 3879.1534  |
+------------+

Verifique o uso de uma reserva específica com WHERE reservation_id = "…". Isso pode ser útil para determinar o percentual de uso de uma reserva durante um período. Para jobs de script, o job pai também informa o uso total de slots dos jobs filhos. Para evitar a contagem duplicada, use WHERE statement_type != "SCRIPT" para excluir o job pai.

Se você quiser verificar a utilização média de slots de jobs individuais, use total_slot_ms / TIMESTAMP_DIFF(end_time, start_time, MILLISECOND)

Exemplo: carregar histórico do job

O exemplo a seguir lista todos os usuários ou contas de serviço que enviaram um job de carregamento em lote de um determinado projeto. Como nenhum limite de tempo é especificado, esta consulta examina todo o histórico disponível (por exemplo, os últimos 30 dias).

SELECT
  DISTINCT(user_email) AS user
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS
WHERE
  job_type = 'LOAD';

O resultado será semelhante ao seguinte:

+--------------+
| user         |
+--------------+
| abc@xyz.com  |
+--------------+
| def@xyz.com  |
+--------------+

Exemplo: bytes processados por identidade do usuário

O exemplo a seguir mostra o total de bytes cobrados para jobs de consulta por usuário.

SELECT
  user_email,
  SUM(total_bytes_billed) AS bytes_billed
FROM
  `region-us.INFORMATION_SCHEMA.JOBS`
WHERE
  job_type = 'QUERY'
  AND statement_type != 'SCRIPT'
GROUP BY
  user_email;

Os resultados vão ter a aparência abaixo:

+---------------------+--------------+
| user_email          | bytes_billed |
+---------------------+--------------+
| bob@example.com     | 2847932416   |
| alice@example.com   | 1184890880   |
| charles@example.com | 10485760     |
+---------------------+--------------+

Exemplo: detalhamento por hora de bytes processados

O exemplo a seguir mostra o total de bytes cobrados para jobs de consulta em intervalos por hora.

SELECT
  TIMESTAMP_TRUNC(end_time, HOUR) AS time_window,
  SUM(total_bytes_billed) AS bytes_billed
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS
WHERE
  job_type = 'QUERY'
  AND statement_type != 'SCRIPT'
GROUP BY
  time_window
ORDER BY
  time_window DESC

O resultado será semelhante ao seguinte:

+-------------------------+--------------+
| time_window             | bytes_billed |
+-------------------------+--------------+
| 2022-05-17 20:00:00 UTC | 1967128576   |
| 2022-05-10 21:00:00 UTC | 0            |
| 2022-04-15 20:00:00 UTC | 10485760     |
| 2022-04-15 17:00:00 UTC | 41943040     |
+-------------------------+--------------+