Vista JOBS_TIMELINE

La vista INFORMATION_SCHEMA.JOBS_TIMELINE contiene i metadati BigQuery quasi in tempo reale per intervallo di tempo per tutti i job inviati nel progetto corrente. Questa visualizzazione contiene i job attualmente in esecuzione e completati.

Autorizzazioni obbligatorie

Per eseguire query sulla vista INFORMATION_SCHEMA.JOBS_TIMELINE, devi disporre dell'autorizzazione Identity and Access Management (IAM) bigquery.jobs.listAll per il progetto. Ognuno dei seguenti ruoli IAM predefiniti include l'autorizzazione richiesta:

  • Proprietario progetto
  • Amministratore BigQuery

Per saperne di più sulle autorizzazioni di BigQuery, consulta Controllo dell'accesso con IAM.

Schema

Quando esegui una query sulle viste INFORMATION_SCHEMA.JOBS_TIMELINE_BY_*, i risultati della query contengono una riga per ogni secondo di esecuzione di ogni job BigQuery. Ogni periodo inizia con un intervallo di un secondo intero e dura esattamente un secondo.

La vista INFORMATION_SCHEMA.JOBS_TIMELINE_BY_* ha il seguente schema:

Nome colonna Tipo di dati Valore
period_start TIMESTAMP Ora di inizio di questo periodo.
period_slot_ms INTEGER Millisecondi slot utilizzati in questo periodo.
project_id STRING (Colonna di clustering) ID del progetto.
project_number INTEGER Numero del progetto.
user_email STRING (Colonna di clustering) Indirizzo email o account di servizio dell'utente che ha eseguito il job.
principal_subject STRING Una rappresentazione di stringa dell'identità dell'entità che ha eseguito il job.
job_id STRING ID del job. Ad esempio, bquxjob_1234.
job_type STRING Il tipo di job. Può essere QUERY, LOAD, EXTRACT, COPY o NULL. Un valore NULL indica un job in background.
labels RECORD Array di etichette applicate al job come coppie chiave-valore.
statement_type STRING Il tipo di istruzione di query, se valido. Ad esempio, SELECT, INSERT, UPDATE o DELETE.
priority STRING La priorità di questo job. I valori validi includono INTERACTIVE e BATCH.
parent_job_id STRING ID del job principale, se presente.
job_creation_time TIMESTAMP (Colonna di partizionamento) Ora di creazione del job. Il partizionamento si basa sull'ora UTC di questo timestamp.
job_start_time TIMESTAMP Ora di inizio del job.
job_end_time TIMESTAMP Ora di fine del job.
state STRING Stato di esecuzione del job alla fine di questo periodo. Gli stati validi includono PENDING, RUNNING e DONE.
reservation_id STRING Nome della prenotazione principale assegnata a questo job alla fine di questo periodo, se applicabile.
reservation_group_path ARRAY<STRING> Il gruppo di prenotazioni a cui è collegata la prenotazione. Ad esempio, se la prenotazione è collegata al gruppo my-group, il campo reservation_group_path contiene un elenco come: [my-group].
edition STRING La versione associata alla prenotazione assegnata a questo job. Per saperne di più sulle versioni, consulta Introduzione alle versioni di BigQuery.
total_bytes_billed INTEGER Se il progetto è configurato per l'utilizzo dei prezzi on demand, questo campo contiene i byte totali fatturati per il job. Se il progetto è configurato per l'utilizzo dei prezzi con costo fisso, non ti vengono addebitati i byte e questo campo è solo a scopo informativo. Questo campo viene compilato solo per i job completati e contiene il numero totale di byte fatturati per l'intera durata del job.
total_bytes_processed INTEGER Byte totali elaborati dal job. Questo campo viene compilato solo per i job completati e contiene il numero totale di byte elaborati per l'intera durata del job.
error_result RECORD Dettagli dell'errore (se presente) come ErrorProto.
cache_hit BOOLEAN Indica se i risultati della query di questo job provengono da una cache.
period_shuffle_ram_usage_ratio FLOAT Rapporto di utilizzo shuffling nel periodo di tempo selezionato. Il valore è 0.0 se il job è stato eseguito con una prenotazione che utilizza la scalabilità automatica e non ha slot di riferimento.
period_estimated_runnable_units INTEGER Unità di lavoro che possono essere pianificate immediatamente in questo periodo. Gli slot aggiuntivi per queste unità di lavoro accelerano la query, a condizione che nessun'altra query nella prenotazione richieda slot aggiuntivi.
transaction_id STRING ID della transazione in cui è stato eseguito questo job, se presente.
global_query_info RECORD Informazioni su una query globale. Contiene i seguenti campi:
  • parent_job_id: l'ID del job di query globale principale nella regione principale.
  • parent_job_location: la località del job di query globale principale.
  • remote_regions: un array di regioni remote a cui fa riferimento la query globale.

Per garantire la stabilità, ti consigliamo di elencare esplicitamente le colonne nelle query dello schema di informazioni anziché utilizzare un carattere jolly (SELECT *). L'elenco esplicito delle colonne impedisce l'interruzione delle query se lo schema sottostante cambia.

Conservazione dei dati

Questa visualizzazione mostra i job in esecuzione insieme alla cronologia dei job degli ultimi 180 giorni. Se un progetto viene migrato a un'organizzazione (da nessuna organizzazione o da un'altra), le informazioni sul job precedenti alla data di migrazione non sono accessibili tramite la vista INFORMATION_SCHEMA.JOBS_TIMELINE, poiché la vista conserva i dati solo a partire dalla data di migrazione.

Ambito e sintassi

Le query su questa vista devono includere un qualificatore di regione. Se non specifichi un qualificatore regionale, i metadati vengono recuperati da tutte le regioni. La tabella seguente illustra l'ambito della regione per questa visualizzazione:

Nome vista Ambito risorsa Ambito della regione
[PROJECT_ID.]`region-REGION`.INFORMATION_SCHEMA.JOBS_TIMELINE[_BY_PROJECT] Livello progetto REGION
Sostituisci quanto segue:
  • (Facoltativo) PROJECT_ID: l'ID del tuo progetto Google Cloud . Se non specificato, viene utilizzato il progetto predefinito.
  • REGION: qualsiasi nome della regione del set di dati. Ad esempio: `region-us`.

Esempi

Per eseguire la query su un progetto diverso da quello predefinito, aggiungi l'ID progetto nel seguente formato: 

`PROJECT_ID`.`region-REGION_NAME`.INFORMATION_SCHEMA.VIEW

Ad esempio, `myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE.

L'esempio seguente calcola l'utilizzo degli slot per ogni secondo dell'ultimo giorno:

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;

Il risultato è simile al seguente:

+---------------------+---------------+
|    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 |
+---------------------+---------------+

Puoi controllare l'utilizzo di una prenotazione specifica con WHERE reservation_id = "…". Per i job di script, il job principale segnala anche l'utilizzo totale degli slot dei job secondari. Per evitare il doppio conteggio, utilizza WHERE statement_type != "SCRIPT" per escludere il job principale.

Numero di job RUNNING e PENDING nel tempo

Per eseguire la query su un progetto diverso da quello predefinito, aggiungi l'ID progetto nel seguente formato: 

`PROJECT_ID`.`region-REGION_NAME`.INFORMATION_SCHEMA.VIEW

Ad esempio, `myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE.

L'esempio seguente calcola il numero di job RUNNING e PENDING ogni secondo nell'ultimo giorno:

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;

Il risultato è simile al seguente:

+---------------------+---------+---------+
|    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 |
+---------------------+---------+---------+

Utilizzo delle risorse da parte dei job in un momento specifico

Per eseguire la query su un progetto diverso da quello predefinito, aggiungi l'ID progetto nel seguente formato: 

`PROJECT_ID`.`region-REGION_NAME`.INFORMATION_SCHEMA.VIEW

Ad esempio, `myproject`.`region-us`.INFORMATION_SCHEMA.JOBS.

L'esempio seguente restituisce il job_id di tutti i job in esecuzione in un momento specifico, insieme all'utilizzo delle risorse durante quel periodo di un secondo:

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);

Il risultato è simile al seguente:

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

Comportamento di utilizzo degli slot corrispondente dai grafici delle risorse amministrative

Puoi utilizzare i grafici delle risorse amministrative per monitorare l'integrità della tua organizzazione, l'utilizzo degli slot e le prestazioni dei job BigQuery nel tempo. L'esempio seguente esegue una query sulla vista INFORMATION_SCHEMA.JOBS_TIMELINE per una cronologia di utilizzo degli slot a intervalli di un'ora, simile alle informazioni disponibili nei grafici delle risorse amministrative.

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;

Calcola la percentuale di tempo di esecuzione con lavoro in attesa

Per eseguire la query su un progetto diverso da quello predefinito, aggiungi l'ID progetto nel seguente formato: 

`PROJECT_ID`.`region-REGION_NAME`.INFORMATION_SCHEMA.VIEW

Ad esempio, `myproject`.`region-us`.INFORMATION_SCHEMA.JOBS.

L'esempio seguente restituisce un valore float che rappresenta la percentuale della durata totale dell'esecuzione del job in cui il valore di period_estimated_runnable_units era diverso da zero, il che significa che il job richiedeva più slot. Un valore elevato indica che il job ha subito una contesa degli slot, mentre un valore basso indica che il job non ha richiesto slot per la maggior parte del tempo di esecuzione, il che significa che la contesa degli slot è stata minima o nulla.

Se il valore risultante è elevato, puoi provare ad aggiungere altri slot per vedere l'impatto e capire se la contesa degli slot è l'unico collo di bottiglia.

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 conosci la data di esecuzione della query, aggiungi una clausola DATE(period_start) = 'YYYY-MM-DD' alla query per ridurre la quantità di byte elaborati e velocizzare l'esecuzione. Ad esempio, DATE(period_start) = '2025-08-22'.

Il risultato è simile al seguente:

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