Gestire le impostazioni di configurazione

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

Ad esempio, per gestire più facilmente i job, puoi utilizzare questo servizio per configurare le impostazioni predefinite dei job. Le impostazioni predefinite 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.

Impostazioni di configurazione

Puoi specificare le seguenti impostazioni di configurazione:

  • default_batch_query_queue_timeout_ms: il periodo di tempo predefinito, in millisecondi, in cui 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 l'inserimento in coda delle query batch, imposta il valore su -1.
  • default_column_name_character_map: l'ambito predefinito e la gestione dei caratteri nei nomi delle colonne. Se non viene impostato, i job di caricamento che utilizzano caratteri non supportati nei nomi delle colonne non vengono eseguiti 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 periodo di tempo predefinito, in millisecondi, in cui una query interattiva viene messa in coda. Se non viene impostato, il valore predefinito è sei ore. Il valore minimo è 1 millisecondo. Il valore massimo è 48 ore. Per disattivare l'inserimento in 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 relativo alla query scade, incluso il tempo in cui il job viene messo 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 non ne è specificato uno come argomento. Questa configurazione non si applica alle tabelle partizionate per colonne di unità di tempo (che utilizzano UTC come fuso orario), ai trasferimenti pianificati di Storage Transfer Service o al caricamento di 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 temporale 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.

Specificare le impostazioni di configurazione

Questa sezione descrive come specificare un'impostazione di configurazione.

Autorizzazioni obbligatorie

Per specificare un'impostazione di 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 specificare un'impostazione di configurazione.

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

Configura le impostazioni

Puoi configurare le impostazioni a livello di organizzazione o progetto utilizzando i seguenti statement SQL. Quando specifichi la configurazione, devi anche 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 predefinito delle query su 30 minuti, il timeout predefinito della coda di query interattive su 10 minuti e il timeout predefinito della coda di query batch 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.

Recuperare le impostazioni di configurazione

Puoi visualizzare le impostazioni di configurazione di un'organizzazione o di un progetto utilizzando le seguenti visualizzazioni dello schema di informazioni:

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

Autorizzazioni obbligatorie

Per recuperare le impostazioni di configurazione, devi disporre dell'bigquery.config.get autorizzazione IAM per il progetto specificato.

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;

Prezzi

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