Présentation du dépannage

Ce document présente les outils de diagnostic, les interfaces de télémétrie et les ressources de documentation disponibles pour vous aider à résoudre les problèmes dans BigQuery.

Lorsque vous rencontrez des échecs de requête, des goulots d'étranglement des performances, des erreurs d'autorisation, des limites de quota ou des problèmes d'ingestion de données, BigQuery fournit des outils intégrés pour vous aider à identifier les causes profondes et à résoudre rapidement les problèmes.

Résoudre un problème lié aux workflows

Pour résoudre efficacement un problème dans BigQuery, tenez compte des critères de diagnostic suivants :

  1. Identifiez le symptôme et le mode de défaillance. Examinez les résultats de votre tâche pour déterminer si le problème est un échec matériel (tel qu'un code d'erreur ou un échec de job), une dégradation des performances (telle qu'une requête lente ou un manque d'emplacements), un refus d'autorisation ou un écart de coût inattendu.
  2. Inspectez les détails d'exécution du job. Utilisez l'explorateur de jobs de la console Google Cloud , le graphique d'exécution des requêtes ou les outils de ligne de commande pour examiner les temps d'exécution au niveau des étapes, l'allocation des emplacements et les détails des erreurs. Vous pouvez également demander à Gemini Cloud Assist d'examiner votre problème.
  3. Analysez la télémétrie et les métadonnées. Interrogez les vues de schéma d'informations ou inspectez Cloud Audit Logs pour mettre en corrélation le comportement des jobs avec les conflits de ressources, les limites de réservation ou les modifications administratives.
  4. Appliquez des mesures d'atténuation ciblées. Utilisez les guides de dépannage par catégorie ou les fonctions SQL défensives pour résoudre la cause sous-jacente.

Distinguer le dépannage de l'optimisation

Lorsque vous travaillez avec BigQuery, il est important de faire la distinction entre le dépannage, l'optimisation des performances et les bonnes pratiques :

  • Dépannage. Se concentre sur le diagnostic et la résolution des échecs inattendus, des erreurs d'exécution, des pipelines défaillants, de l'épuisement des quotas ou des comportements involontaires qui empêchent la réussite des jobs.
  • Optimisation des performances Se concentre sur l'amélioration de la vitesse d'exécution, de la latence ou de l'efficacité des ressources des requêtes et des charges de travail qui s'exécutent déjà correctement. Pour en savoir plus, consultez Optimiser les performances des requêtes.
  • Bonnes pratiques Se concentre sur les modèles d'architecture et de conception pour la modélisation, le stockage, la sécurité et la gestion des coûts des données. Pour en savoir plus, consultez Présentation des bonnes pratiques.

Outils de diagnostic

Les sections suivantes décrivent plusieurs interfaces et outils automatisés BigQuery pour vous aider à diagnostiquer les problèmes liés à vos charges de travail.

Outils visuels et de console

Les outils suivants vous aident à résoudre les problèmes liés à BigQuery à partir de la consoleGoogle Cloud .

  • Explorateur de jobs. Recherchez, filtrez et inspectez les jobs passés et en cours d'exécution dans des projets ou des organisations sans écrire de requêtes SQL. Vous pouvez afficher les messages d'erreur, l'utilisation des emplacements, les chronologies d'exécution et les métadonnées des jobs. Pour en savoir plus, consultez Surveiller les jobs dans l'explorateur de jobs.
  • Graphique d'exécution de la requête Inspectez le plan d'exécution visuel étape par étape d'une requête. Le graphique d'exécution vous aide à identifier les goulots d'étranglement tels que les transferts de données vers le disque, les étapes liées au calcul, le décalage des données ou les retards d'entrée/sortie. Pour en savoir plus, consultez Obtenir des insights sur les performances des requêtes.
  • Insights sur les requêtes et graphiques de ressources Affichez des graphiques historiques et en temps réel de l'utilisation des emplacements, de la simultanéité des jobs et des allocations de réservations pour diagnostiquer les contraintes de capacité. Pour en savoir plus, consultez Utiliser des graphiques de ressources d'administration.
  • Gemini Cloud Assist dans BigQuery Obtenez une analyse contextuelle assistée par l'IA des requêtes ayant échoué et des goulots d'étranglement des performances. Gemini Cloud Assist explique les codes d'erreur, met en évidence la syntaxe SQL problématique et suggère des mesures correctives directement dans la consoleGoogle Cloud . Pour en savoir plus, consultez Résoudre les problèmes liés aux requêtes à l'aide de Gemini Cloud Assist.

Outils de diagnostic automatisés et de ligne de commande

Les outils suivants peuvent vous aider à diagnostiquer les problèmes BigQuery à partir d'une interface de ligne de commande.

  • Outil de ligne de commande bq Inspectez les structures d'erreur détaillées, les ID de requête et les métadonnées de job à l'aide de la commande bq show -j <var>JOB_ID</var> ou en ajoutant l'option --format=prettyjson aux commandes de requête. Pour en savoir plus, consultez Résoudre les problèmes liés aux commandes de la CLI.
  • Outil gcpdiag Exécutez des diagnostics automatisés à partir de la ligne de commande pour détecter les problèmes de configuration Google Cloud courants, y compris les lacunes d'autorisation IAM, les restrictions réseau et les erreurs de compte de service. Pour en savoir plus, consultez Résoudre les échecs de requête à l'aide de gcpdiag.

Vues des métadonnées et de la télémétrie

Les vues de schéma d'informations vous permettent d'interroger des métadonnées historiques et en temps réel sur les jobs, la capacité, l'ingestion en flux continu et les ensembles de données à l'aide du langage SQL standard. Ces vues incluent les éléments suivants :

Pour en savoir plus, consultez la page Présentation de BigQuery INFORMATION_SCHEMA.

Cloud Monitoring et Cloud Audit Logs

  • Cloud Audit Logs Examinez les journaux d'audit des activités d'administration et des accès aux données pour identifier l'auteur d'opérations spécifiques, inspecter les identités des appelants et diagnostiquer les erreurs PERMISSION_DENIED. Pour en savoir plus, consultez la documentation de référence sur les journaux d'audit BigQuery.
  • Cloud Monitoring Suivez des métriques telles que l'utilisation des emplacements, la durée d'exécution des requêtes et les octets importés, et configurez des règles d'alerte pour avertir votre équipe lorsque des seuils ou des quotas sont dépassés. Pour en savoir plus, consultez Surveiller BigQuery à l'aide de Cloud Monitoring.

Fonctions SQL défensives et instructions de débogage

Pour éviter que les requêtes échouent de manière inattendue en raison d'erreurs de données d'exécution, utilisez les éléments suivants :

  • Expressions sécurisées Utilisez SAFE_CAST(), SAFE_DIVIDE(), SAFE_OFFSET() et SAFE_ORDINAL() pour renvoyer NULL au lieu de générer des erreurs d'exécution lorsque les types de données ou les limites de tableau ne correspondent pas. La plupart des fonctions scalaires sont compatibles avec le préfixe SAFE.. Pour en savoir plus, consultez Fonctions de débogage et Préfixe SAFE..
  • Assertions SQL Utilisez l'instruction ASSERT dans des transactions ou des scripts multi-instructions pour appliquer des conditions de validation des données et échouer avec des messages d'erreur personnalisés avant l'exécution des opérations en aval. Pour en savoir plus, consultez Instructions de débogage.

Résoudre les problèmes par catégorie

Sélectionnez une catégorie dans les sections suivantes pour afficher les codes d'erreur détaillés, les causes racines et les guides de résolution par étapes.

Performances et exécution des requêtes

Diagnostiquez les requêtes qui ne s'exécutent pas, expirent, rencontrent des contraintes de ressources ou subissent des retards inattendus.

Identity and Access Management (IAM) et sécurité

Diagnostiquez les échecs de contrôle des accès, les attributions de rôles manquantes et les blocages de règles de gouvernance des données.

Quotas, limites de débit et réservations

Résoudre les problèmes lorsque les charges de travail dépassent les limites de service ou les allocations de capacité de BigQuery.

Ingestion, flux et transferts de données

Diagnostiquez les échecs lors du chargement de données, de l'insertion d'enregistrements en flux continu ou de la synchronisation de sources externes.

  • Résoudre les problèmes liés aux transferts de données Diagnostiquez les problèmes liés au service de transfert de données BigQuery, à la connectivité réseau pour les transferts privés et aux erreurs de chargement des données CSV.
  • Résoudre les problèmes liés aux configurations de transfert. Résolvez les erreurs de configuration du service de transfert de données BigQuery sur des sources telles qu'Amazon Simple Storage Service (Amazon S3), Salesforce, Google Ads et Cloud Storage.
  • Résoudre les problèmes liés à l'API BigQuery Storage Déboguez les échecs d'ingestion en flux continu, les erreurs d'insertion au niveau des lignes et les quotas de débit de l'API BigQuery Storage Read, de l'API BigQuery Storage Write (gRPC) et de l'API BigQuery Storage Write (REST).
  • Résolvez les erreurs de schéma. Résolvez les erreurs d'incohérence de schéma lors des opérations de chargement, de requête, de copie et de mise à jour de schéma (par exemple, des modifications de colonnes manquantes, en double ou incompatibles), ainsi que les limites de profondeur d'imbrication de schéma, de fichier et de routine à 15 niveaux.

Migration d'entrepôts de données

Diagnostiquez les problèmes lors de l'évaluation, de la traduction ou de la migration d'entrepôts de données externes vers BigQuery.

  • Résoudre les problèmes de migration Résolvez les erreurs d'évaluation de la migration, les problèmes de traduction SQL interactive et par lot, et les échecs d'extraction des métadonnées.

Sources de données externes et requêtes fédérées

Diagnostiquez les erreurs de connectivité, d'authentification et d'exécution lors de l'interrogation de données en dehors de BigQuery.

Écarts de facturation et de coût

Examiner les frais inattendus et les écarts de facturation entre le calcul et le stockage.

Limitation de la perte de données

Pour récupérer des données historiques qui ont été modifiées ou supprimées, ou pour maintenir la continuité des activités lors d'une panne régionale, utilisez les outils de reprise après sinistre et de conservation des données suivants :

  • Restaurer les données Interrogez ou restaurez les données de table qui ont été modifiées ou supprimées pendant la fenêtre de fonctionnalité temporelle. Pour en savoir plus, consultez Restaurer des données.
  • Fonctionnalité temporelle Conservez les données mises à jour ou supprimées dans un ensemble de données pendant une période de conservation configurée pour vous protéger contre les modifications accidentelles. Pour en savoir plus, consultez la page Fonctionnalité temporelle.
  • Basculement régional. Promouvoir une instance répliquée secondaire au rôle principal lors d'une panne régionale lorsque vous utilisez la reprise après sinistre gérée par BigQuery. Pour en savoir plus, consultez Basculement régional.

Utiliser des API

Lorsque vous interagissez avec BigQuery de manière programmatique, utilisez les ressources suivantes pour optimiser la latence des requêtes et gérer les workflows d'importation :

  • Astuces relatives aux performances de l'API Suivez les bonnes pratiques pour effectuer des appels d'API, comme la gestion des pools de connexions, l'utilisation d'opérations par lot et la gestion des nouvelles tentatives. Pour en savoir plus, consultez Astuces relatives aux performances de l'API.
  • Importations via l'API Résolvez les problèmes d'ingestion de données et gérez-la à l'aide de requêtes d'importation multipart et avec reprise de l'API REST. Pour en savoir plus, consultez Importations par API.

Authentification et ADC

Pour obtenir de l'aide sur la résolution des problèmes courants que vous pouvez rencontrer lors de l'utilisation des Identifiants par défaut de l'application (ADC), consultez Résoudre les problèmes de configuration de vos ADC.

Étapes suivantes