Gestire le configurazioni predefinite

Questo documento descrive come creare e recuperare le impostazioni di configurazione predefinite a livello di organizzazione o progetto.

Per facilitare la gestione dei job, puoi configurare le impostazioni predefinite in BigQuery. Le impostazioni che utilizzano questo servizio sono configurate a livello di organizzazione o progetto, ma possono essere sostituite a livello di sessione o job. Puoi configurare le impostazioni predefinite in combinazione con le norme organizzative correlate per applicare il comportamento predefinito.

Prezzi

Non sono previsti costi aggiuntivi per l'utilizzo del servizio di configurazione BigQuery. Per ulteriori informazioni, consulta la sezione Prezzi.

Configurazioni predefinite

Puoi specificare le seguenti impostazioni di configurazione predefinite:

  • default_batch_query_queue_timeout_ms: il tempo predefinito, in millisecondi, durante il quale una query batch viene messa in coda. Se non viene impostato, il valore predefinito è 24 ore. Il valore minimo è 1 millisecondo. Il valore massimo è 48 ore. Per disattivare la coda delle query batch, imposta il valore su -1.
  • default_column_name_character_map: l'ambito e la gestione predefiniti dei caratteri nei nomi delle colonne. Se non è impostato, i job di caricamento che utilizzano caratteri non supportati nei nomi delle colonne non riescono a completare l'operazione e viene visualizzato un messaggio di errore. Alcune tabelle meno recenti potrebbero essere impostate per sostituire i caratteri non supportati nei nomi delle colonne. Per ulteriori informazioni, consulta load_option_list.
  • default_interactive_query_queue_timeout_ms: il tempo predefinito, in millisecondi, per cui una query interattiva viene messa in coda. Se non viene impostato, il valore predefinito è 6 ore. Il valore minimo è 1 millisecondo. Il valore massimo è 48 ore. Per disattivare la coda delle query interattive, imposta il valore su -1.
  • default_kms_key_name: la chiave Cloud Key Management Service predefinita per la crittografia dei dati delle tabelle, incluse le tabelle temporanee o anonime. Per ulteriori informazioni, consulta Chiavi Cloud KMS gestite dal cliente.
  • default_query_job_timeout_ms: il tempo predefinito dopo il quale un job di query scade, incluso il tempo in cui il job è in coda e il tempo di esecuzione. Il periodo di timeout deve essere compreso tra cinque minuti e sei ore. Questo timeout si applica solo ai singoli job di query e ai job secondari degli script. Per impostare un timeout per i job di script, devi utilizzare il metodo API jobs.insert e impostare il campo jobTimeoutMs.

  • default_query_optimizer_options: le ottimizzazioni delle query basate sulla cronologia. Questa opzione può essere una delle seguenti:

    • 'adaptive=on': utilizza le ottimizzazioni delle query basate sulla cronologia.
    • 'adaptive=off': non utilizzare le ottimizzazioni delle query basate sulla cronologia.
    • NULL (valore predefinito): utilizza l'impostazione predefinita per le ottimizzazioni delle query basate sulla cronologia, equivalente a 'adaptive=off'.

  • default_time_zone: il fuso orario predefinito da utilizzare nelle funzioni SQL dipendenti dal fuso orario, quando un fuso orario non è specificato come argomento. Questa configurazione non si applica alle tabelle con partizioni per colonne di unità di tempo (che utilizzano UTC come fuso orario), ai trasferimenti pianificati di Storage Transfer Service o al caricamento dei dati con lo strumento a riga di comando bq. Per ulteriori informazioni, consulta Fusi orari.

  • default_storage_billing_model: il modello di fatturazione dello spazio di archiviazione predefinito per i nuovi set di dati. Imposta il valore su PHYSICAL per utilizzare i byte fisici durante il calcolo degli addebiti per lo spazio di archiviazione o su LOGICAL per utilizzare i byte logici. Tieni presente che la modifica del modello di fatturazione dello spazio di archiviazione predefinito non influisce sui set di dati esistenti. Per ulteriori informazioni, consulta Modelli di fatturazione dello spazio di archiviazione.

  • default_max_time_travel_hours: la finestra di spostamento cronologico predefinita in ore per i nuovi set di dati. Questa durata deve essere compresa tra 48 e 168 ore, incluse, e deve essere divisibile per 24. La modifica del numero massimo di ore di viaggio predefinite non influisce sui set di dati esistenti. Per ulteriori informazioni, vedi Viaggio nel tempo.

Creare configurazioni predefinite

Questa sezione descrive come creare una configurazione.

Autorizzazioni obbligatorie

Per creare una configurazione, devi disporre dell'autorizzazione bigquery.config.update Identity and Access Management (IAM). Il ruolo IAM predefinito roles/bigquery.admin include le autorizzazioni necessarie per creare una configurazione.

Per ulteriori informazioni sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Configura le impostazioni predefinite

Puoi configurare le impostazioni predefinite a livello di organizzazione o progetto utilizzando i seguenti statement SQL. Quando crei la configurazione, devi specificare la regione in cui si applica. Puoi utilizzare una sola regione per ogni dichiarazione.

Configura le impostazioni dell'organizzazione

Per configurare le impostazioni dell'organizzazione, utilizza l'istruzione DDL ALTER ORGANIZATION SET OPTIONS. L'esempio seguente imposta il fuso orario predefinito su America/Chicago, la chiave Cloud KMS predefinita su una chiave definita dall'utente, il timeout delle query predefinito su 30 minuti, il timeout della coda delle query interattive predefinito su 10 minuti e il timeout della coda delle query batch predefinito su 20 minuti:

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

Sostituisci quanto segue:

  • REGION: la regione associata al tuo progetto o alla tua organizzazione. Ad esempio, us o europe-west6.
  • KMS_KEY: una chiave Cloud KMS definita dall'utente. Per maggiori informazioni sulle chiavi Cloud KMS, consulta Chiavi Cloud KMS gestite dal cliente.

L'esempio seguente cancella tutte le impostazioni predefinite a livello di organizzazione:

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

Configura le impostazioni del progetto

Per configurare le impostazioni del progetto, utilizza l'istruzione DDL ALTER PROJECT SET OPTIONS. L'istruzione DDL ALTER PROJECT SET OPTIONS accetta facoltativamente la variabile project_id. Se project_id non è specificato, viene utilizzato per impostazione predefinita il progetto corrente in cui viene eseguita la query. L'esempio seguente imposta il fuso orario predefinito su America/Los_Angeles, la chiave Cloud KMS predefinita su una chiave di esempio, il timeout delle query predefinito su 1 ora, il timeout della coda delle query interattive predefinito su 10 minuti e il timeout della coda delle query batch predefinito su 20 minuti:

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'esempio seguente cancella tutte le impostazioni predefinite a livello di progetto. Le impostazioni predefinite utilizzano eventuali impostazioni predefinite a livello di organizzazione, se esistenti. In caso contrario, tutte le impostazioni predefinite vengono impostate su quelle predefinite globali.

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

Le configurazioni a livello di progetto hanno la precedenza su quelle a livello di organizzazione. Le configurazioni a livello di progetto possono a loro volta essere sostituite dalle configurazioni a livello di sessione, che possono essere sostituite dalle configurazioni a livello di job.

Recupera i valori di configurazione

Puoi visualizzare le impostazioni di configurazione predefinite per un'organizzazione o un progetto esaminando lo schema delle informazioni. Esistono tre diverse viste per eseguire query:

Potrebbero essere necessari alcuni minuti prima che le nuove configurazioni diventino effettive e vengano riportate nella visualizzazione INFORMATION_SCHEMA.

Autorizzazioni obbligatorie

Per recuperare i valori di configurazione, devi disporre dell'autorizzazione IAM bigquery.config.get.

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per recuperare la configurazione dalla visualizzazione INFORMATION_SCHEMA:

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

Per ulteriori informazioni sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Esempi

Per visualizzare le configurazioni di un'organizzazione nella regione us, esegui la seguente query:

SELECT * FROM region-us.INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

Per visualizzare le configurazioni effettive nel progetto predefinito nella regione us, esegui la seguente query:

SELECT * FROM region-us.INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

Per visualizzare le configurazioni nel progetto predefinito nella regione us, esegui la seguente query:

SELECT * FROM region-us.INFORMATION_SCHEMA.PROJECT_OPTIONS;