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 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 policy dell'organizzazione 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, vedi 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 criptare i 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 5 minuti e 6 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 (impostazione predefinita): utilizza l'impostazione predefinita per l'ottimizzazione delle query basata sulla cronologia, che equivale a 'adaptive=on'.

  • 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 a 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 saperne di più, consulta Fusi orari.

  • default_storage_billing_model: Il modello di fatturazione dell'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 saperne di più, 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, inclusi, e deve essere divisibile per 24. La modifica delle ore di viaggio massime predefinite non influisce sui set di dati esistenti. Per ulteriori informazioni, vedi Time Travel.

  • default_cloud_resource_connection_id: la connessione predefinita da utilizzare per la creazione di tabelle e modelli. Specifica solo l'ID o il nome della connessione ed escludi i prefissi di ID progetto e regione allegati. L'utilizzo delle connessioni predefinite può causare l'aggiornamento delle autorizzazioni concesse alaccount di serviziot della connessione, a seconda del tipo di tabella o modello che stai creando. Per saperne di più, vedi la panoramica della connessione predefinita.

  • default_sql_dialect_option: il dialetto di query SQL predefinito per l'esecuzione dei job di query utilizzando lo strumento a riga di comando bq o l'API BigQuery. La modifica di questa impostazione non influisce sul dialetto predefinito nella console. Questa opzione può essere una delle seguenti:

    • 'default_legacy_sql' (impostazione predefinita): utilizza SQL precedente se il dialetto della query non è specificato a livello di job.
    • 'default_google_sql': utilizza GoogleSQL se il dialetto della query non è specificato a livello di job.
    • 'only_google_sql': utilizza GoogleSQL se il dialetto della query non è specificato a livello di job. Rifiuta i job con il dialetto della query impostato su SQL precedente.
    • NULL: utilizza l'impostazione predefinita del dialetto della query, che equivale a 'default_legacy_sql'.

  • enable_reservation_based_fairness: l'opzione che determina la modalità di condivisione degli slot inattivi. Il valore predefinito è false, il che significa che gli slot inattivi sono distribuiti equamente tra tutti i progetti di query. Se l'opzione è abilitata, gli slot inattivi vengono condivisi equamente tra tutte le prenotazioni e poi tra i progetti all'interno della prenotazione. Per saperne di più, consulta la sezione Equità basata sulle prenotazioni. Questa opzione è supportata solo a livello di progetto. Non puoi specificarlo a livello di organizzazione o lavoro.

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 Identity and Access Management (IAM) bigquery.config.update. Il ruolo IAM predefinito roles/bigquery.admin include le autorizzazioni necessarie per specificare un'impostazione di configurazione.

Per ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, vedi Ruoli e autorizzazioni predefiniti.

Configura le impostazioni

Puoi configurare le impostazioni a livello di organizzazione o progetto utilizzando le seguenti istruzioni SQL. Quando specifichi la configurazione, devi specificare la regione in cui viene applicata. Puoi utilizzare una sola regione per ogni estratto conto.

Configurare 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, il valore predefinito è 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 predefinito della query su 1 ora, il timeout predefinito della coda di query interattive su 10 minuti, il timeout predefinito della coda di query batch su 20 minuti e abilita l'equità basata sulla prenotazione.

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,
  `region-REGION.default_cloud_resource_connection_id` = CONNECTION_ID,
  `region-REGION.default_sql_dialect_option` = 'default_google_sql',
  `region-REGION.enable_reservation_based_fairness` = true);

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto
  • 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.
  • CONNECTION_ID: l'ID della connessione da utilizzare come connessione predefinita per tabelle e modelli.

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 sono impostate sul valore predefinito 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,
  `region-REGION.default_cloud_resource_connection_id` = NULL,
  `region-REGION.default_sql_dialect_option` = NULL,
  `region-REGION.enable_reservation_based_fairness` = 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 per un'organizzazione o un progetto utilizzando le seguenti viste dello schema delle informazioni:

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

Autorizzazioni obbligatorie

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

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

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

Per ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, vedi Ruoli e autorizzazioni predefiniti.

Esempi

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

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.