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 des configurations par défaut pour les paramètres 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 option n'est pas définie, les tâches de chargement qui utilisent des caractères non compatibles dans les noms de colonnes échouent et génèrent un message d'erreur. Certaines tables plus anciennes peuvent être configurées pour remplacer les caractères non compatibles 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.
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.

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.

Avertissement : Si vous souhaitez définir une clé Cloud Key Management Service par défaut, vous devez attribuer le rôle de chiffreur/déchiffreur à tous les comptes de service BigQuery utilisés dans le projet ou l'organisation. Si un compte de service du projet ou de l'organisation ne dispose pas des autorisations appropriées, toutes les requêtes du compte de service échouent. Pour attribuer le rôle de chiffreur/déchiffreur, consultez la section Attribuer le rôle de chiffreur/déchiffreur. Si vous définissez par erreur une clé Cloud Key Management Service sans attribuer au préalable les rôles appropriés, vous pouvez supprimer la clé par défaut en définissant la valeur sur NULL. Pour obtenir des exemples, consultez les sections Configurer les paramètres de l'organisation et Configurer les paramètres du projet de ce document. De même, si vous souhaitez définir un fuseau horaire par défaut, assurez-vous que les requêtes existantes utilisant des littéraux DATETIME ne sont pas affectées. Cela inclut les requêtes avec le mot clé explicite DATETIME, les littéraux de chaîne implicitement transmis en tant que paramètre à des fonctions temporelles telles que DATETIME_DIFF('2022-10-01', ...), la fonction PARSE_DATETIME(), etc. Pour cette raison, il est plus sûr de ne définir le paramètre default_time_zone que sur les nouveaux projets.

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

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

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

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

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 :

INFORMATION_SCHEMA.PROJECT_OPTIONS : configurations appliquées à un projet
INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS : configurations effectives appliquées à un projet. Les configurations effectives incluent toutes les configurations définies au niveau du projet ainsi que tous les paramètres hérités par le projet d'une organisation.
INFORMATION_SCHEMA.ORGANIZATION_OPTIONS : configurations appliquées à une organisation.

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;