Gérer les configurations par défaut

Ce document explique comment créer et récupérer des paramètres de configuration par défaut au niveau d'une organisation ou d'un projet.

Pour vous aider à gérer les jobs, vous pouvez configurer des paramètres par défaut dans BigQuery. Les paramètres qui utilisent ce service sont configurés au niveau de l'organisation ou du projet, mais peuvent être remplacés au niveau de la session ou du job. Vous pouvez configurer les paramètres par défaut conjointement avec des règles d'administration associées pour appliquer le comportement par défaut.

Tarifs

L'utilisation du service de configuration BigQuery est gratuite. Pour en savoir plus, reportez-vous à la page Tarifs.

Configurations par défaut

Vous pouvez spécifier les paramètres de configuration par défaut suivants:

  • default_batch_query_queue_timeout_ms : durée par défaut, en millisecondes, pendant laquelle une requête par lot est placée en file d'attente. Si elle n'est pas spécifiée, la valeur par défaut est de 24 heures. La valeur minimale est de 1 milliseconde. La valeur maximale est de 48 heures. Pour désactiver la mise en file d'attente des requêtes par lot, définissez la valeur sur -1.
  • default_column_name_character_map : champ d'application et gestion par défaut des caractères dans les noms de colonnes. Si cette valeur n'est pas définie, les jobs de chargement qui utilisent des caractères non compatibles dans les noms de colonnes échouent avec un message d'erreur. Certaines tables plus anciennes peuvent être configurées pour remplacer les caractères non acceptés dans les noms de colonnes. Pour en savoir plus, consultez la section load_option_list.
  • default_interactive_query_queue_timeout_ms : durée par défaut, en millisecondes, pendant laquelle une requête interactive est placée en file d'attente. Si elle n'est pas spécifiée, la valeur par défaut est de six heures. La valeur minimale est de 1 milliseconde. La valeur maximale est de 48 heures. Pour désactiver la mise en file d'attente des requêtes interactives, définissez la valeur sur -1.
  • default_kms_key_name : clé Cloud Key Management Service par défaut pour le chiffrement des données de table, y compris les tables temporaires ou anonymes. Pour en savoir plus, consultez la section Clés Cloud KMS gérées par le client.
  • default_query_job_timeout_ms : délai par défaut au bout duquel un job de requête expire, comprenant le délai de mise en file d'attente du job et son temps d'exécution. Le délai avant expiration doit être compris entre cinq minutes et six heures. Ce délai d'expiration ne s'applique qu'aux jobs de requête individuels et aux jobs enfants des scripts. Pour définir un délai avant expiration pour les tâches de script, vous devez utiliser la méthode API jobs.insert et définir le champ jobTimeoutMs.

  • default_query_optimizer_options: optimisations des requêtes basées sur l'historique. Cette option peut être l'une des suivantes:

    • 'adaptive=on': utilisez les optimisations de requêtes basées sur l'historique.
    • 'adaptive=off': n'utilisez pas les optimisations de requêtes basées sur l'historique.
    • NULL (par défaut): utilisez le paramètre d'optimisation des requêtes basées sur l'historique par défaut, qui équivaut à 'adaptive=off'.

  • default_time_zone : fuseau horaire par défaut à utiliser dans les fonctions SQL dépendantes du fuseau horaire, lorsqu'un fuseau horaire n'est pas spécifié en tant qu'argument. Cette configuration ne s'applique pas aux tables partitionnées par colonnes d'unités de temps (qui utilisent le fuseau horaire UTC), aux transferts planifiés du service de transfert de stockage ou au chargement des données à l'aide de l'outil de ligne de commande bq. Pour en savoir plus, consultez la section Fuseaux horaires.

  • default_storage_billing_model: modèle de facturation du stockage par défaut pour les nouveaux ensembles de données. Définissez la valeur sur PHYSICAL pour utiliser des octets physiques lors du calcul des frais de stockage ou sur LOGICAL pour utiliser des octets logiques. Notez que la modification du modèle de facturation du stockage par défaut n'a aucune incidence sur les ensembles de données existants. Pour en savoir plus, consultez la page Modèles de facturation du stockage.

  • default_max_time_travel_hours: fenêtre temporelle par défaut en heures pour les nouveaux ensembles de données. Cette durée doit être comprise entre 48 et 168 heures, inclus, et doit être divisible par 24. La modification de la durée maximale de trajet par défaut n'a aucune incidence sur les ensembles de données existants. Pour en savoir plus, consultez Fonctionnalité temporelle.

Créer des configurations par défaut

Cette section explique comment créer une configuration.

Autorisations requises

Pour créer une configuration, vous devez disposer de l'autorisation IAM (Identity and Access Management) bigquery.config.update. Le rôle IAM prédéfini roles/bigquery.admin inclut les autorisations dont vous avez besoin pour créer une configuration.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Configurer les paramètres par défaut

Vous pouvez configurer les paramètres par défaut au niveau de l'organisation ou du projet à l'aide des instructions SQL suivantes. Lorsque vous créez la configuration, vous devez spécifier la région dans laquelle elle s'applique. Vous ne pouvez utiliser qu'une seule région par instruction.

Configurer les paramètres de l'organisation

Pour configurer les paramètres de l'organisation, utilisez l'instruction LDD ALTER ORGANIZATION SET OPTIONS. Dans l'exemple suivant, le fuseau horaire par défaut est défini sur America/Chicago, la clé Cloud KMS par défaut sur une clé définie par l'utilisateur, le délai avant expiration par défaut de la requête sur 30 minutes, le délai avant expiration par défaut de la file d'attente de requêtes sur 10 minutes et le délai avant expiration par défaut de la file d'attente de requêtes par lot sur 20 minutes :

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.default_time_zone`= 'America/Chicago',
  -- Ensure all service accounts under the organization have permission to KMS_KEY
  `region-REGION.default_kms_key_name` = KMS_KEY,
  `region-REGION.default_query_job_timeout_ms` = 1800000,
  `region-REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `region-REGION.default_batch_query_queue_timeout_ms` = 1200000,
  `region-REGION.default_storage_billing_model`= PHYSICAL,
  `region-REGION.default_max_time_travel_hours` = 72);

Remplacez les éléments suivants :

  • REGION : région associée à votre projet ou à votre organisation. Par exemple, us ou europe-west6.
  • KMS_KEY : clé Cloud KMS définie par l'utilisateur. Pour en savoir plus sur les clés Cloud KMS, consultez la page Clés Cloud KMS gérées par le client.

L'exemple suivant supprime tous les paramètres par défaut au niveau de l'organisation :

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.default_time_zone` = NULL,
  `region-REGION.default_kms_key_name` = NULL,
  `region-REGION.default_query_job_timeout_ms` = NULL,
  `region-REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `region-REGION.default_batch_query_queue_timeout_ms` = NULL,
  `region-REGION.default_storage_billing_model`= NULL,
  `region-REGION.default_max_time_travel_hours` = NULL);

Configurer les paramètres du projet

Pour configurer les paramètres du projet, utilisez l'instruction LDD ALTER PROJECT SET OPTIONS. L'instruction LDD ALTER PROJECT SET OPTIONS accepte éventuellement la variable project_id. Si project_id n'est pas spécifié, il s'agit par défaut du projet en cours dans lequel la requête est exécutée. Dans l'exemple suivant, le fuseau horaire par défaut est défini sur America/Los_Angeles, la clé Cloud KMS par défaut sur un exemple de clé, le délai avant expiration par défaut de la requête sur une heure, le délai avant expiration par défaut de la file d'attente de requêtes interactives sur 10 minutes et le délai avant expiration par défaut de la file d'attente de requêtes par lot sur 20 minutes :

ALTER PROJECT project_id
SET OPTIONS (
  `region-REGION.default_time_zone` = 'America/Los_Angeles',
  -- Ensure all service accounts under the project have permission to KMS_KEY
  `region-REGION.default_kms_key_name` = KMS_KEY,
  `region-REGION.default_query_job_timeout_ms` = 3600000,
  `region-REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `region-REGION.default_batch_query_queue_timeout_ms` = 1200000,
  `region-REGION.default_storage_billing_model`= PHYSICAL,
  `region-REGION.default_max_time_travel_hours` = 72);

L'exemple suivant supprime tous les paramètres par défaut au niveau du projet. Les paramètres par défaut utilisent les paramètres par défaut du niveau de l'organisation, s'ils existent. Sinon, tous les paramètres par défaut sont définis sur la valeur par défaut globale.

ALTER PROJECT project_id
SET OPTIONS (
  `region-REGION.default_time_zone` = NULL,
  `region-REGION.default_kms_key_name` = NULL,
  `region-REGION.default_query_job_timeout_ms` = NULL,
  `region-REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `region-REGION.default_batch_query_queue_timeout_ms` = NULL,
  `region-REGION.default_storage_billing_model`= NULL,
  `region-REGION.default_max_time_travel_hours` = NULL);

Les configurations au niveau du projet remplacent les configurations au niveau de l'organisation. Les configurations au niveau du projet peuvent à leur tour être remplacées par des configurations au niveau de la session, qui peuvent être remplacées par des configurations au niveau du job.

Récupérer les valeurs de configuration

Vous pouvez afficher les paramètres de configuration par défaut d'une organisation ou d'un projet en affichant le schéma d'informations. Il existe trois vues différentes :

L'application des nouvelles configurations et leur prise en compte dans la vue INFORMATION_SCHEMA peuvent prendre quelques minutes.

Autorisations requises

Pour récupérer les valeurs de configuration, vous devez disposer de l'autorisation IAM bigquery.config.get.

Chacun des rôles IAM prédéfinis suivants inclut les autorisations dont vous avez besoin pour obtenir la configuration à partir de la vue INFORMATION_SCHEMA :

  • roles/bigquery.jobUser
  • roles/bigquery.dataEditor
  • roles/bigquery.dataUser

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Examples

Pour afficher les configurations d'une organisation dans la région us, exécutez la requête suivante :

SELECT * FROM region-us.INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

Pour afficher les configurations effectives de votre projet par défaut dans la région us, exécutez la requête suivante :

SELECT * FROM region-us.INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

Pour afficher les configurations de votre projet par défaut dans la région us, exécutez la requête suivante :

SELECT * FROM region-us.INFORMATION_SCHEMA.PROJECT_OPTIONS;