Introduzione alla risoluzione dei problemi

Questo documento fornisce una panoramica degli strumenti di diagnostica, delle interfacce di telemetria e delle risorse di documentazione disponibili per aiutarti a risolvere i problemi in BigQuery.

Quando riscontri errori delle query, colli di bottiglia delle prestazioni, errori di autorizzazione, limiti di quota o problemi di importazione dati, BigQuery fornisce strumenti integrati per aiutarti a identificare le cause principali e risolvere rapidamente i problemi.

Workflow di risoluzione dei problemi

Per risolvere efficacemente un problema in BigQuery, prendi in considerazione i seguenti criteri di diagnostica:

  1. Identifica il sintomo e la modalità di errore. Esamina i risultati dell'attività per determinare se il problema è un errore grave (ad esempio un codice di errore o un errore del job), un peggioramento delle prestazioni (ad esempio una query lenta o una carenza di slot), un rifiuto di autorizzazione o una discrepanza di costi imprevista.
  2. Controlla i dettagli dell'esecuzione del job. Utilizza lo strumento di esplorazione dei job della Google Cloud console , il grafico di esecuzione delle query o gli strumenti a riga di comando per esaminare i tempi a livello di fase, l'allocazione degli slot e i dettagli degli errori. Puoi anche chiedere a Gemini Cloud Assist di indagare sul problema.
  3. Analizza la telemetria e i metadati. Esegui query sulle visualizzazioni dello schema informativo o esamina Cloud Audit Logs per correlare il comportamento del job con la contesa delle risorse, i limiti di prenotazione o le modifiche amministrative.
  4. Applica mitigazioni mirate. Utilizza guide alla risoluzione dei problemi specifiche per categoria o funzioni SQL difensive per risolvere la causa sottostante.

Distinguere la risoluzione dei problemi dall'ottimizzazione

Quando lavori con BigQuery, è importante distinguere tra risoluzione dei problemi, ottimizzazione delle prestazioni e best practice:

  • Risoluzione dei problemi. Si concentra sulla diagnosi e sulla risoluzione di errori imprevisti, errori di runtime, pipeline interrotte, esaurimento delle quote o comportamenti indesiderati che impediscono il completamento corretto dei job.
  • Ottimizzazione delle prestazioni. Si concentra sul miglioramento della velocità di esecuzione, della latenza o dell'efficienza delle risorse di query e workload già in esecuzione. Per saperne di più, consulta Ottimizzare le prestazioni delle query.
  • Best practice. Si concentra sui pattern architetturali e di progettazione per la modellazione, l'archiviazione, la sicurezza e la gestione dei costi dei dati. Per saperne di più, consulta Introduzione alle best practice.

Strumenti di diagnostica

Le sezioni seguenti descrivono diverse interfacce e strumenti automatici di BigQuery per aiutarti a diagnosticare i problemi nei tuoi workload.

Strumenti visivi e della console

I seguenti strumenti ti aiutano a risolvere i problemi di BigQuery da Google Cloud console.

  • Esplora job. Cerca, filtra e controlla i job passati e in esecuzione in progetti o organizzazioni senza scrivere query SQL. Puoi visualizzare messaggi di errore, utilizzo degli slot, sequenze temporali di esecuzione e metadati dei job. Per saperne di più, consulta Monitorare i job in Esplora job.
  • Grafico di esecuzione delle query. Esamina il piano di esecuzione visivo fase per fase di una query. Il grafico di esecuzione ti aiuta a identificare i colli di bottiglia, come gli spill di shuffling su disco, le fasi con vincoli di calcolo, la distorsione dei dati o i ritardi di input/output. Per saperne di più, consulta Ottenere informazioni sulle prestazioni delle query.
  • Query Insights e grafici delle risorse. Visualizza grafici storici e in tempo reale dell'utilizzo degli slot, della concorrenza dei job e delle allocazioni delle prenotazioni per diagnosticare i vincoli di capacità. Per saperne di più, consulta Utilizzare i grafici delle risorse amministrative.
  • Gemini Cloud Assist in BigQuery. Ricevi un'analisi contestuale assistita dall'AI delle query non riuscite e dei colli di bottiglia delle prestazioni. Gemini Cloud Assist spiega i codici di errore, evidenzia la sintassi SQL problematica e suggerisce passaggi di correzione direttamente nella Google Cloud console. Per saperne di più, consulta Risolvere i problemi relativi alle query utilizzando Gemini Cloud Assist.

Strumenti di diagnostica automatici e a riga di comando

I seguenti strumenti possono aiutarti a diagnosticare i problemi di BigQuery da un'interfaccia a riga di comando.

  • Strumento a riga di comando bq. Esamina le strutture di errore dettagliate, gli ID delle richieste e i metadati dei job utilizzando il comando bq show -j <var>JOB_ID</var>o aggiungendo il flag --format=prettyjsonai comandi delle query. Per saperne di più, consulta Risolvere i problemi relativi ai comandi CLI.
  • Strumento gcpdiag. Esegui la diagnostica automatica dalla riga di comando per rilevare i problemi di configurazione Google Cloud comuni, tra cui lacune nelle autorizzazioni IAM , restrizioni di rete ed errori degli account di servizio. Per saperne di più, consulta Risolvere i problemi relativi agli errori delle query utilizzando gcpdiag.

Visualizzazioni di metadati e telemetria

Le visualizzazioni dello schema informativo ti consentono di eseguire query sui metadati storici e in tempo reale relativi a job, capacità, importazione di flussi di dati e set di dati utilizzando SQL standard. Queste visualizzazioni includono:

Per saperne di più, consulta Introduzione a BigQuery INFORMATION_SCHEMA.

Cloud Monitoring e Cloud Audit Logs

  • Audit log di Cloud. Esamina gli audit log per le Attività degli amministratori e l'Accesso ai dati per monitorare chi ha avviato operazioni specifiche, controllare le identità dei chiamanti e diagnosticare gli errori PERMISSION_DENIED. Per saperne di più, consulta la documentazione di riferimento sull'audit logging di BigQuery .
  • Cloud Monitoring. Monitora metriche come l'utilizzo degli slot, le durate di esecuzione delle query e i byte caricati e configura le policy di avviso per notificare al tuo team quando vengono superate le soglie o le quote. Per saperne di più, consulta Monitorare BigQuery utilizzando Cloud Monitoring.

Funzioni SQL difensive e istruzioni di debug

Per evitare che le query non vadano a buon fine in modo imprevisto a causa di errori di dati di runtime, utilizza quanto segue:

  • Espressioni sicure. Utilizza SAFE_CAST(), SAFE_DIVIDE(), SAFE_OFFSET() e SAFE_ORDINAL() per restituire NULL anziché generare errori di runtime quando i tipi di dati o i limiti degli array non corrispondono. La maggior parte delle funzioni scalari supporta il prefisso SAFE.. Per saperne di più, consulta Funzioni di debug e SAFE. prefisso.
  • Asserzioni SQL. Utilizza l'istruzione ASSERT in transazioni o script con più istruzioni per applicare le condizioni di convalida dei dati e non riuscire con messaggi di errore personalizzati prima dell'esecuzione delle operazioni downstream. Per saperne di più, consulta Istruzioni di debug.

Risolvere i problemi per categoria

Seleziona una categoria dalle sezioni seguenti per visualizzare codici di errore dettagliati, cause principali e guide passo passo per la risoluzione.

Prestazioni ed esecuzione delle query

Diagnostica le query che non vengono eseguite, vanno in timeout, riscontrano vincoli di risorse o subiscono ritardi imprevisti.

Identity and Access Management (IAM) e sicurezza

Diagnostica gli errori di controllo dell'accesso, le assegnazioni di ruoli mancanti e i blocchi delle policy di governance dei dati.

Quote, limiti di frequenza e prenotazioni

Risolvi i problemi quando i workload superano i limiti di servizio o le allocazioni di capacità di BigQuery.

Importazione, streaming e trasferimenti di dati

Diagnostica gli errori durante il caricamento dei dati, lo streaming dei record o la sincronizzazione delle origini esterne.

Origini dati esterne e query federate

Diagnostica gli errori di connettività, autenticazione ed esecuzione durante l'esecuzione di query sui dati al di fuori di BigQuery.

Discrepanze di fatturazione e costi

Indaga sugli addebiti imprevisti e sulle discrepanze di fatturazione per il calcolo e l'archiviazione.

Mitigazione della perdita di dati

Per recuperare i dati storici modificati o eliminati o per mantenere la continuità aziendale durante un'interruzione regionale, utilizza i seguenti strumenti di ripristino di emergenza e conservazione dei dati:

  • Ripristinare i dati. Esegui query o ripristina i dati delle tabelle modificati o eliminati nella finestra di viaggio nel tempo. Per saperne di più, consulta Ripristinare i dati.
  • Viaggio nel tempo. Conserva i dati aggiornati o eliminati in un set di dati per un periodo di conservazione configurato per proteggerti da modifiche accidentali. Per saperne di più, consulta Viaggio nel tempo.
  • Failover regionale. Promuovi una replica secondaria al ruolo primario durante un'interruzione regionale quando utilizzi il ripristino di emergenza gestito da BigQuery. Per saperne di più, consulta Failover regionale.

Utilizzo delle API

Quando interagisci con BigQuery a livello di programmazione, utilizza le seguenti risorse per ottimizzare la latenza delle richieste e gestire i workflow di caricamento:

  • Suggerimenti sulle prestazioni dell'API. Segui le best practice per effettuare chiamate API, ad esempio la gestione dei pool di connessioni, l'utilizzo di operazioni batch e la gestione dei nuovi tentativi. Per saperne di più, consulta Suggerimenti sulle prestazioni dell'API.
  • Caricamenti dell'API. Risolvi i problemi e gestisci importazione dati utilizzando le richieste di caricamento ripristinabili e multipart dell'API REST. Per saperne di più, consulta Caricamenti dell'API.

Passaggi successivi