Esta página foi traduzida pela API Cloud Translation.

Visualização JOBS_TIMELINE

A visualização INFORMATION_SCHEMA.JOBS_TIMELINE contém metadados do BigQuery em tempo real por fração de tempo para todos os jobs enviados no projeto atual. Essa visualização contém jobs em execução e concluídos.

Permissões necessárias

Para consultar a visualização INFORMATION_SCHEMA.JOBS_TIMELINE, 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:

Proprietário do projeto
Administrador do BigQuery

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

Esquema

Ao consultar as visualizações INFORMATION_SCHEMA.JOBS_TIMELINE_BY_*, os resultados da consulta terão uma linha para cada segundo de execução de cada job do BigQuery. Cada período começa em um intervalo de segundo inteiro e dura exatamente um segundo.

A visualização INFORMATION_SCHEMA.JOBS_TIMELINE_BY_* tem o seguinte esquema:

Nome da coluna	Tipo de dados	Valor
`period_start`	`TIMESTAMP`	Horário de início deste período.
`period_slot_ms`	`INTEGER`	Milissegundos de slot consumidos neste período.
`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`. Um valor `NULL` indica um job em segundo plano.
`labels`	`RECORD`	Matriz de identificadores aplicados ao job como pares de chave-valor.
`statement_type`	`STRING`	O tipo de instrução de consulta, se for válido. Por exemplo, `SELECT`, `INSERT`, `UPDATE`, ou `DELETE`.
`priority`	`STRING`	A prioridade deste job. Os valores válidos incluem `INTERACTIVE` e `BATCH`.
`parent_job_id`	`STRING`	ID do job pai (se houver).
`job_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.
`job_start_time`	`TIMESTAMP`	Horário de início deste job.
`job_end_time`	`TIMESTAMP`	Horário de término deste job.
`state`	`STRING`	Estado em execução do job no final deste período. Os estados válidos incluem `PENDING`, `RUNNING`, e `DONE`.
`reservation_id`	`STRING`	Nome da reserva principal atribuída a este job no final deste período, se aplicável.
`edition`	`STRING`	A edição associada à reserva atribuída a este job. Para mais informações sobre edições, consulte Introdução às edições do BigQuery.
`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. Esse campo é preenchido apenas para jobs concluídos e contém o número total de bytes cobrados durante toda a duração do job.
`total_bytes_processed`	`INTEGER`	Total de bytes processados pelo job. Esse campo é preenchido apenas para jobs concluídos e contém o número total de bytes processados durante toda a duração do job.
`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.
`period_shuffle_ram_usage_ratio`	`FLOAT`	Proporção de uso do embaralhamento no período selecionado. O valor é `0.0` se o job foi executado com uma reserva que usa escalonamento automático e tem zero slots de valor de referência.
`period_estimated_runnable_units`	`INTEGER`	Unidades de trabalho que podem ser programadas imediatamente nesse período. Os slots adicionais para essas unidades de trabalho aceleram a consulta, contanto que nenhuma outra consulta na reserva precise de slots adicionais.
`transaction_id`	`STRING`	ID da transação em que este job foi executado, se houver.

Para garantir a estabilidade, recomendamos que você liste explicitamente as colunas nas consultas do esquema de informações em vez de usar um caractere curinga (SELECT *). Isso evita que as consultas sejam interrompidas se o esquema subjacente mudar.

Retenção de dados

Essa visualização mostra os jobs em execução e o histórico dos últimos 180 dias. Se um projeto for migrado para uma organização (sem organização ou de outra), as informações de job anteriores à data da migração não poderão ser acessadas no acesso de visualização INFORMATION_SCHEMA.JOBS_TIMELINE, porque ele só retém dados a partir da data da migração.

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_TIMELINE[_BY_PROJECT]	Nível do projeto	`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.

Exemplos

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

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

No exemplo a seguir, calculamos a utilização de slots para cada segundo no último dia:

SELECT
  period_start,
  SUM(period_slot_ms) AS total_slot_ms,
FROM
  `reservation-admin-project.region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE
WHERE
  period_start BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY) AND CURRENT_TIMESTAMP()
GROUP BY
  period_start
ORDER BY
  period_start DESC;

O resultado será semelhante ao seguinte:

+---------------------+---------------+
|    period_start     | total_slot_ms |
+---------------------+---------------+
| 2020-07-29 03:52:14 |     122415176 |
| 2020-07-29 03:52:15 |     141107048 |
| 2020-07-29 03:52:16 |     173335142 |
| 2020-07-28 03:52:17 |     131107048 |
+---------------------+---------------+

Verifique o uso de uma reserva específica com WHERE reservation_id = "…". 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.

Número de jobs `RUNNING` e `PENDING` ao longo do tempo

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

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

O exemplo a seguir calcula o número de jobs RUNNING e PENDING a cada segundo no dia anterior:

SELECT
  period_start,
  SUM(IF(state = "PENDING", 1, 0)) as PENDING,
  SUM(IF(state = "RUNNING", 1, 0)) as RUNNING
FROM
  `reservation-admin-project.region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE
WHERE
  period_start BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY) AND CURRENT_TIMESTAMP()
GROUP BY
  period_start;

O resultado será semelhante ao seguinte:

+---------------------+---------+---------+
|    period_start     | PENDING | RUNNING |
+---------------------+---------+---------+
| 2020-07-29 03:52:14 |       7 |      27 |
| 2020-07-29 03:52:15 |       1 |      21 |
| 2020-07-29 03:52:16 |       5 |      21 |
| 2020-07-29 03:52:17 |       4 |      22 |
+---------------------+---------+---------+

Uso de recursos por jobs em um momento específico

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

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

O exemplo a seguir retorna o job_id de todos os jobs em execução em um momento específico junto com o uso de recursos durante esse período de um segundo:

SELECT
  job_id,
  period_slot_ms
FROM
  `reservation-admin-project.region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE_BY_PROJECT
WHERE
  period_start = '2020-07-29 03:52:14'
  AND (statement_type != 'SCRIPT' OR statement_type IS NULL);

O resultado será semelhante ao seguinte:

+------------------+
| job_id | slot_ms |
+------------------+
| job_1  | 2415176 |
| job_2  | 4417245 |
| job_3  |  427416 |
| job_4  | 1458122 |
+------------------+

Corresponder o comportamento de uso de slots dos gráficos de recursos administrativos

É possível usar gráficos de recursos administrativos para monitorar a integridade da organização, o uso de slots e o desempenho dos jobs do BigQuery ao longo do tempo. O exemplo a seguir consulta a visualização INFORMATION_SCHEMA.JOBS_TIMELINE para uma linha do tempo de uso de slots em intervalos de uma hora, semelhante às informações disponíveis nos gráficos de recursos administrativos.

DECLARE
  start_time timestamp DEFAULT TIMESTAMP(START_TIME);
DECLARE
  end_time timestamp DEFAULT TIMESTAMP(END_TIME);

WITH
  snapshot_data AS (
  SELECT
    UNIX_MILLIS(period_start) AS period_start,
    IFNULL(SUM(period_slot_ms), 0) AS period_slot_ms,
    DIV(UNIX_MILLIS(period_start), 3600000 * 1) * 3600000 * 1 AS time_ms
  FROM (
    SELECT
      *
    FROM
      `PROJECT_ID.region-US`.INFORMATION_SCHEMA.JOBS_TIMELINE_BY_PROJECT
    WHERE
      ((job_creation_time >= TIMESTAMP_SUB(start_time, INTERVAL 1200 MINUTE)
          AND job_creation_time < TIMESTAMP(end_time))
        AND period_start >= TIMESTAMP(start_time)
        AND period_start < TIMESTAMP(end_time))
      AND (statement_type != "SCRIPT"
        OR statement_type IS NULL)
      AND REGEXP_CONTAINS(reservation_id, "^PROJECT_ID:") )
  GROUP BY
    period_start,
    time_ms ),
  converted_percentiles_data AS (
  SELECT
    time_ms,
    100 - CAST(SAFE_DIVIDE(3600000 * 1 * 1 / 1000, COUNT(*)) AS INT64) AS converted_percentiles,
  FROM
    snapshot_data
  GROUP BY
    time_ms ),
  data_by_time AS (
  SELECT
    time_ms,
  IF
    (converted_percentiles <= 0, 0, APPROX_QUANTILES(period_slot_ms, 100)[SAFE_OFFSET(converted_percentiles)] / 1000) AS p99_slots,
    SUM(period_slot_ms) / (3600000 * 1) AS avg_slots
  FROM
    snapshot_data
  JOIN
    converted_percentiles_data AS c
  USING
    (time_ms)
  GROUP BY
    time_ms,
    converted_percentiles )
SELECT
  time_ms,
  TIMESTAMP_MILLIS(time_ms) AS time_stamp,
  IFNULL(avg_slots, 0) AS avg_slots,
  IFNULL(p99_slots, 0) AS p99_slots,
FROM (
  SELECT
    time_ms * 3600000 * 1 AS time_ms
  FROM
    UNNEST(GENERATE_ARRAY(DIV(UNIX_MILLIS(start_time), 3600000 * 1), DIV(UNIX_MILLIS(end_time), 3600000 * 1) - 1, 1)) AS time_ms )
LEFT JOIN
  data_by_time
USING
  (time_ms)
ORDER BY
  time_ms DESC;

Calcular a porcentagem do tempo de execução que tinha trabalho pendente

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

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

O exemplo a seguir retorna um valor de ponto flutuante que representa a porcentagem da duração total da execução do job em que o valor de period_estimated_runnable_units era diferente de zero, o que significa que o job estava solicitando mais slots. Um valor grande indica que o job sofreu disputa de slots, enquanto um valor pequeno indica que o job não estava solicitando slots durante a maior parte do tempo de execução, o que significa que houve pouca ou nenhuma disputa de slots.

Se o valor resultante for grande, tente adicionar mais slots para ver o impacto e entender se a disputa de slots é o único gargalo.

SELECT ROUND(COUNTIF(period_estimated_runnable_units > 0) / COUNT(*) * 100, 1) as execution_duration_percentage
FROM `myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE
WHERE job_id = 'my_job_id'
GROUP BY job_id

Se você souber a data da execução da consulta, adicione uma cláusula DATE(period_start) = 'YYYY-MM-DD' para reduzir a quantidade de bytes processados e acelerar a execução. Por exemplo, DATE(period_start) = '2025-08-22'.

O resultado será semelhante ao seguinte:

+-------------------------------+
| execution_duration_percentage |
+-------------------------------+
|                          96.7 |
+-------------------------------+

Visualização JOBS_TIMELINE

Permissões necessárias

Esquema

Retenção de dados

Escopo e sintaxe

Exemplos

Número de jobs RUNNING e PENDING ao longo do tempo

Uso de recursos por jobs em um momento específico

Corresponder o comportamento de uso de slots dos gráficos de recursos administrativos

Calcular a porcentagem do tempo de execução que tinha trabalho pendente

Número de jobs `RUNNING` e `PENDING` ao longo do tempo