Vista JOBS_BY_FOLDER

La visualizzazione INFORMATION_SCHEMA.JOBS_BY_FOLDER contiene metadati quasi in tempo reale su tutti i job inviati nella cartella principale del progetto attuale, inclusi i job nelle sottocartelle.

Ruolo richiesto

Per ottenere l'autorizzazione necessaria per eseguire query sulla vista INFORMATION_SCHEMA.JOBS_BY_FOLDER, chiedi all'amministratore di concederti il ruolo IAM BigQuery Resource Viewer (roles/bigquery.resourceViewer) nella cartella principale. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l'autorizzazione bigquery.jobs.listAll necessaria per eseguire query sulla vista INFORMATION_SCHEMA.JOBS_BY_FOLDER.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

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

Schema

I dati sottostanti sono partizionati in base alla colonna creation_time e raggruppati in cluster in base a project_id e user_email. La colonna query_info contiene informazioni aggiuntive sui job di query.

La vista INFORMATION_SCHEMA.JOBS_BY_FOLDER ha il seguente schema:

Nome colonna	Tipo di dati	Valore
bi_engine_statistics	RECORD	Se il progetto è configurato per utilizzare BI Engine, questo campo contiene BiEngineStatistics. In caso contrario, NULL.
cache_hit	BOOLEAN	Indica se i risultati della query di questo job provengono da una cache. Se hai un job con istruzione multi-query, cache_hit per la query principale è NULL.
creation_time	TIMESTAMP	(Colonna di partizionamento) Ora di creazione di questo job. Il partizionamento si basa sull'ora UTC di questo timestamp.
destination_table	RECORD	Tabella di destinazione per i risultati, se presente.
dml_statistics	RECORD	Se il job è una query con un'istruzione DML, il valore è un record con i seguenti campi: inserted_row_count: Il numero di righe inserite. deleted_row_count: Il numero di righe eliminate. updated_row_count: il numero di righe aggiornate. Per tutti gli altri lavori, il valore è NULL. Questa colonna è presente nelle visualizzazioni INFORMATION_SCHEMA.JOBS_BY_USER e INFORMATION_SCHEMA.JOBS_BY_PROJECT.
end_time	TIMESTAMP	L'ora di fine di questo job, in millisecondi dall'epoca. Questo campo rappresenta l'ora in cui il job entra nello stato DONE.
error_result	RECORD	Dettagli di eventuali errori come oggetti ErrorProto.
folder_numbers	REPEATED INTEGER	ID numerici delle cartelle che contengono il progetto, a partire dalla cartella che contiene immediatamente il progetto, seguita dalla cartella che contiene la cartella secondaria e così via. Ad esempio, se folder_numbers è [1, 2, 3], la cartella 1 contiene immediatamente il progetto, la cartella 2 contiene 1 e la cartella 3 contiene 2. Questa colonna viene compilata solo in JOBS_BY_FOLDER.
job_creation_reason.code	STRING	Specifica il motivo generale per cui è stato creato un job. I valori possibili sono: REQUESTED: è stata richiesta la creazione del job. LONG_RUNNING: la richiesta di query è stata eseguita oltre un timeout definito dal sistema specificato dal campo timeoutMs nel QueryRequest. Di conseguenza, è stata considerata un'operazione a lunga esecuzione per la quale è stato creato un job. LARGE_RESULTS: i risultati della query non possono essere inseriti nella risposta in linea. OTHER: il sistema ha stabilito che la query deve essere eseguita come job.
job_id	STRING	L'ID del job, se ne è stato creato uno. In caso contrario, l'ID query di una query che utilizza la modalità di creazione job facoltativa. Ad esempio, bquxjob_1234.
job_stages	RECORD REPEATED	Fasi di query del job. Nota: i valori di questa colonna sono vuoti per le query che leggono da tabelle con policy di accesso a livello di riga. Per saperne di più, consulta le best practice per la sicurezza a livello di riga in BigQuery.
job_type	STRING	Il tipo di lavoro. 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.
object_storage_stats	RECORD REPEATED	Statistiche per l'utilizzo dell'archiviazione di oggetti e della memorizzazione nella cache per un job di query. Il valore è un record ripetuto con i seguenti campi: cloud_provider: il cloud provider in cui è ospitato l'archivio di oggetti (ad esempio AWS). object_storage_bytes_read: il numero totale di byte letti direttamente dall'archivio di oggetti. cache_bytes_read: il numero totale di byte letti dalla cache.
parent_job_id	STRING	ID del job principale, se presente.
priority	STRING	La priorità di questo job. I valori validi includono INTERACTIVE e BATCH.
project_id	STRING	(Colonna di clustering) L'ID del progetto.
project_number	INTEGER	Il numero del progetto.
referenced_tables	RECORD	Array di valori STRUCT che contengono i seguenti campi STRING per ogni tabella a cui fa riferimento la query: project_id, dataset_id e table_id. Compilato solo per i job di query che non sono successi della cache.
referenced_logical_views	RECORD	Array di valori STRUCT che contengono i seguenti campi STRING per ogni vista logica a cui fa riferimento la query: project_id, dataset_id e table_id. Compilato solo per i job di query che non sono successi della cache.
reservation_id	STRING	Nome della prenotazione principale assegnata a questo job, nel formato RESERVATION_ADMIN_PROJECT:RESERVATION_LOCATION.RESERVATION_NAME. In questo output: RESERVATION_ADMIN_PROJECT: il nome del progetto Google Cloud che amministra la prenotazione RESERVATION_LOCATION: la località della prenotazione RESERVATION_NAME: il nome della prenotazione
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.
session_info	RECORD	Dettagli sulla sessione in cui è stato eseguito questo job, se presente.
start_time	TIMESTAMP	L'ora di inizio di questo job, in millisecondi dall'epoca. Questo campo rappresenta il momento in cui il job passa dallo stato PENDING a RUNNING o DONE.
state	STRING	Stato di esecuzione del job. Gli stati validi includono PENDING, RUNNING e DONE.
statement_type	STRING	Il tipo di istruzione di query. Ad esempio, DELETE, INSERT, SCRIPT, SELECT o UPDATE. Consulta QueryStatementType per un elenco di valori validi.
timeline	RECORD	Cronologia della query del job. Contiene snapshot dell'esecuzione delle query.
total_bytes_billed	INTEGER	Se il progetto è configurato per utilizzare i prezzi on demand, questo campo contiene il totale dei byte fatturati per il job. Se il progetto è configurato per l'utilizzo dei prezzi a costo fisso, non ti vengono addebitati i byte e questo campo è solo a scopo informativo. Nota: i valori di questa colonna sono vuoti per le query che leggono da tabelle con policy di accesso a livello di riga. Per saperne di più, consulta le best practice per la sicurezza a livello di riga in BigQuery.
total_bytes_processed	INTEGER	Byte totali elaborati dal job. Nota: i valori di questa colonna sono vuoti per le query che leggono da tabelle con policy di accesso a livello di riga. Per saperne di più, consulta le best practice per la sicurezza a livello di riga in BigQuery.
total_modified_partitions	INTEGER	Il numero totale di partizioni modificate dal job. Questo campo viene compilato per i job LOAD e QUERY.
total_slot_ms	INTEGER	Millisecondi di slot per il job per l'intera durata nello stato RUNNING, inclusi i nuovi tentativi.
total_services_sku_slot_ms	INTEGER	Il totale dei millisecondi di slot per il job eseguito su servizi esterni e fatturato in base allo SKU dei servizi. Questo campo viene compilato solo per i job che hanno costi di servizi esterni e rappresenta l'utilizzo totale per i costi il cui metodo di fatturazione è "SERVICES_SKU".
transaction_id	STRING	ID della transazione in cui è stato eseguito questo job, se presente.
user_email	STRING	(Colonna di clustering) Indirizzo email o account di servizio dell'utente che ha eseguito il job.
principal_subject	STRING	Una rappresentazione in formato stringa dell'identità dell'entità che ha eseguito il job.
query_info.resource_warning	STRING	Il messaggio di avviso visualizzato se l'utilizzo delle risorse durante l'elaborazione delle query supera la soglia interna del sistema. Un job di query riuscito può avere il campo resource_warning compilato. Con resource_warning, ottieni punti dati aggiuntivi per ottimizzare le query e configurare il monitoraggio delle tendenze delle prestazioni di un insieme equivalente di query utilizzando query_hashes.
query_info.query_hashes.normalized_literals	STRING	Contiene il valore hash della query. normalized_literals è un hash STRING esadecimale che ignora i commenti, i valori parametro, le funzioni definite dall'utente e i valori letterali. Il valore hash sarà diverso quando le visualizzazioni sottostanti cambiano o se la query fa riferimento implicitamente a colonne, ad esempio SELECT *, e lo schema della tabella cambia. Questo campo viene visualizzato per le query GoogleSQL riuscite che non sono successi della cache.
query_info.performance_insights	RECORD	Insight sulle prestazioni per il job.
transferred_bytes	INTEGER	Byte totali trasferiti per le query BigQuery Omni, ad esempio i job di trasferimento BigQuery Omni.
materialized_view_statistics	RECORD	Statistiche delle viste materializzate considerate in un job di query. (Anteprima)
metadata_cache_statistics	RECORD	Statistiche per l'utilizzo dell'indice delle colonne dei metadati per le tabelle a cui viene fatto riferimento in un job di query.
search_statistics	RECORD	Statistiche per una query di ricerca.
query_dialect	STRING	Questo campo sarà disponibile a maggio 2025. Il dialetto della query utilizzato per il job. I valori validi includono: GOOGLE_SQL: è stato richiesto l'utilizzo di GoogleSQL per il job. LEGACY_SQL: È stato richiesto al job di utilizzare LegacySQL. DEFAULT_LEGACY_SQL: nella richiesta di job non è stato specificato alcun dialetto della query. BigQuery ha utilizzato il valore predefinito di LegacySQL. DEFAULT_GOOGLE_SQL: nella richiesta di job non è stato specificato alcun dialetto della query. BigQuery ha utilizzato il valore predefinito di GoogleSQL. Per i job inviati dagli utenti, questo campo viene compilato solo per i job di query. La selezione predefinita del dialetto della query può essere controllata dalle impostazioni di configurazione. Per i job in background, il valore di questo campo non è controllato dalle impostazioni di configurazione del dialetto di query predefinito e non influisce sui job inviati dagli utenti. Per alcuni job in background, il valore viene omesso.
continuous	BOOLEAN	Indica se il job è una query continua.
continuous_query_info.output_watermark	TIMESTAMP	Rappresenta il punto fino al quale la query continua ha elaborato correttamente i dati.
vector_search_statistics	RECORD	Statistiche per una query di ricerca vettoriale.
external_service_costs	RECORD	Un array di informazioni sui costi del servizio esterno per un job di query.
ml_statistics.model_type	STRING	Se il job è una query di creazione del modello BigQuery ML, questo campo specifica il tipo di modello in fase di creazione. Per tutti gli altri lavori, il valore è NULL.

Per garantire la stabilità, ti consigliamo di elencare esplicitamente le colonne nelle query dello schema informativo 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 viene eseguita la migrazione di un progetto in un'organizzazione (da nessuna organizzazione o da un'altra), le informazioni sui job precedenti alla data di migrazione non sono accessibili tramite la vista INFORMATION_SCHEMA.JOBS_BY_FOLDER, poiché la vista conserva i dati solo a partire dalla data di migrazione.

Ambito e sintassi

Le query su questa visualizzazione devono includere un qualificatore di regione. 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_BY_FOLDER	Cartella che contiene il progetto specificato	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`.
  Nota: devi utilizzare un qualificatore di regione per eseguire query sulle visualizzazioni INFORMATION_SCHEMA. La località di esecuzione della query deve corrispondere alla regione della vista INFORMATION_SCHEMA.

Nota :quando esegui una query su INFORMATION_SCHEMA.JOBS_BY_FOLDER per trovare un costo riepilogativo dei job di query, devi escludere il tipo di istruzione SCRIPT, altrimenti alcuni valori potrebbero essere conteggiati due volte. La riga SCRIPT include i valori di riepilogo per tutti i job secondari eseguiti nell'ambito di questo job.

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

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto
• REGION_NAME: la regione del progetto

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

Visualizzare job interattivi

La seguente query mostra l'ID job, l'ora di creazione e lo stato (PENDING, RUNNING o DONE) di tutti i job interattivi nella cartella del progetto designato:

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

Nota: i nomi delle visualizzazioni INFORMATION_SCHEMA sono sensibili alle maiuscole.

Il risultato è simile al seguente:

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