Crea tabelle BigLake di Cloud Storage

Le tabelle BigLake di Cloud Storage ti consentono di eseguire query sui dati strutturati in Cloud Storage utilizzando la delega dell'accesso. Questo approccio disaccoppia l'accesso alla tabella BigLake dall'accesso al datastore sottostante, in modo che gli utenti abbiano bisogno delle autorizzazioni solo per la tabella.

Questo documento descrive come creare una tabella BigLake di Cloud Storage.

Prima di iniziare

  1. Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .

    Ruoli richiesti per selezionare o creare un progetto

    • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

    Vai al selettore di progetti

  2. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  3. Abilita l'API BigQuery Connection, se non è già abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

    Se vuoi leggere le tabelle BigLake da motori open source come Apache Spark, devi abilitare l'API BigQuery Storage Read.

  4. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

  5. Assicurati di avere un set di dati BigQuery.

  6. Assicurati che la tua versione di Google Cloud SDK sia 366.0.0 o successiva:

    gcloud version

    Se necessario, aggiorna Google Cloud SDK.

    1. (Facoltativo) Per Terraform, è richiesta la versione 4.25.0 o successiva di terraform-provider-google. Le release di terraform-provider-google sono elencate su GitHub. Puoi scaricare l'ultima versione di Terraform dalla pagina dei download di HashiCorp Terraform.

  7. Crea una connessione alle risorse Cloud o configura una connessione predefinita alla tua origine dati esterna. Le connessioni richiedono ruoli e autorizzazioni aggiuntivi. Per saperne di più, consulta Crea una connessione alle risorse Cloud e la panoramica della connessione predefinita.

Ruoli obbligatori

Per creare una tabella BigLake, devi disporre delle seguenti autorizzazioni Identity and Access Management (IAM) di BigQuery:

  • bigquery.tables.create
  • bigquery.connections.delegate

Il ruolo Identity and Access Management predefinito Amministratore BigQuery (roles/bigquery.admin) include queste autorizzazioni.

Se non sei un'entità con questo ruolo, chiedi all'amministratore di concederti l'accesso o di creare la tabella BigLake per te.

Per saperne di più sui ruoli e sulle autorizzazioni di Identity and Access Management in BigQuery, consulta Ruoli predefiniti e autorizzazioni.

Considerazione della posizione

Quando utilizzi Cloud Storage per archiviare i file di dati, puoi migliorare le prestazioni utilizzando bucket Cloud Storage a regione singola o a due regioni anziché bucket multiregionali.

Crea tabelle esterne su dati non partizionati

Se hai familiarità con la creazione di tabelle in BigQuery, il processo di creazione di una tabella esterna è simile. La tabella può utilizzare qualsiasi formato file supportato dalle tabelle esterne. Per saperne di più, consulta Limitazioni.

Prima di creare una tabella BigLake, devi disporre di un set di dati e di una connessione alle risorse Cloud che possa accedere a Cloud Storage.

Per creare una tabella BigLake, seleziona una delle seguenti opzioni:

Console

  1. Vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

    Pulsante evidenziato per il riquadro Spazio di esplorazione.

    Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.

  3. Nel riquadro Explorer, espandi il progetto, fai clic su Set di dati, quindi seleziona un set di dati.

  4. Espandi l'opzione Azioni e fai clic su Crea tabella.

  5. Nella sezione Origine, specifica i seguenti dettagli:

    1. In Crea tabella da, seleziona Google Cloud Storage.

    2. In Seleziona il file dal bucket GCS oppure utilizza un pattern URI, sfoglia per selezionare un bucket e un file da utilizzare oppure digita il percorso nel formato gs://bucket_name/[folder_name/]file_name.

      Non puoi specificare più URI nella console Google Cloud , ma puoi selezionare più file specificando un carattere jolly asterisco (*). Ad esempio: gs://mybucket/file_name*. Per saperne di più, consulta Supporto dei caratteri jolly per gli URI Cloud Storage.

      Il bucket Cloud Storage deve trovarsi nella stessa località del set di dati che contiene la tabella che stai creando.

    3. In Formato file, seleziona il formato corrispondente al tuo file.

  6. Nella sezione Destinazione, specifica i seguenti dettagli:

    1. In Progetto, scegli il progetto in cui creare la tabella.

    2. In Set di dati, scegli il set di dati in cui creare la tabella.

    3. In Tabella, inserisci il nome della tabella che stai creando.

    4. In Tipo di tabella, seleziona Tabella esterna.

    5. Seleziona Crea una tabella BigLake utilizzando una connessione alle risorse Cloud.

    6. In ID connessione, seleziona la connessione creata in precedenza.

  7. Nella sezione Schema, puoi attivare il rilevamento automatico dello schema o specificare manualmente uno schema se hai un file di origine. Se non hai un file di origine, devi specificare manualmente uno schema.

    • Per attivare il rilevamento automatico dello schema, seleziona l'opzione Rilevamento automatico.

    • Per specificare manualmente uno schema, lascia deselezionata l'opzione Rilevamento automatico. Attiva Modifica come testo e inserisci lo schema della tabella come array JSON.

  8. Per ignorare le righe con valori di colonna aggiuntivi che non corrispondono allo schema, espandi la sezione Opzioni avanzate e seleziona Valori sconosciuti.

  9. Fai clic su Crea tabella.

Dopo aver creato la tabella permanente, puoi eseguire una query sulla tabella come se fosse una tabella BigQuery nativa. Una volta completata la query, puoi esportare i risultati come file CSV o JSON, salvarli come tabella o salvarli in Fogli Google.

SQL

Utilizza l'istruzione DDL CREATE EXTERNAL TABLE. Puoi specificare lo schema in modo esplicito o utilizzare il rilevamento automatico dello schema per dedurlo dai dati esterni.

  1. Nella console Google Cloud , vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente istruzione:

    CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID` | DEFAULT}
  OPTIONS (
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'[,...]],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );

    Sostituisci quanto segue:

    • PROJECT_ID: il nome del progetto in cui vuoi creare la tabella, ad esempio myproject
    • DATASET: il nome del set di dati BigQuery in cui vuoi creare la tabella, ad esempio mydataset
    • EXTERNAL_TABLE_NAME: il nome della tabella che vuoi creare, ad esempio mytable
    • REGION: la regione che contiene la connessione, ad esempio us
    • CONNECTION_ID: l'ID connessione, ad esempio myconnection

      Quando visualizzi i dettagli della connessione nella console Google Cloud , l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

      Per utilizzare una connessione predefinita, specifica DEFAULT anziché la stringa di connessione contenente PROJECT_ID.REGION.CONNECTION_ID.

    • TABLE_FORMAT: il formato della tabella che vuoi creare, ad esempio PARQUET

      Per ulteriori informazioni sui formati supportati, consulta Limitazioni.

    • BUCKET_PATH: il percorso del bucket Cloud Storage che contiene i dati per la tabella esterna, nel formato ['gs://bucket_name/[folder_name/]file_name'].

      Puoi selezionare più file dal bucket specificando un carattere jolly asterisco (*) nel percorso. Ad esempio, ['gs://mybucket/file_name*']. Per saperne di più, consulta Supporto dei caratteri jolly per gli URI Cloud Storage.

      Puoi specificare più bucket per l'opzione uris fornendo più percorsi.

      I seguenti esempi mostrano valori uris validi:

      • ['gs://bucket/path1/myfile.csv']
      • ['gs://bucket/path1/*.csv']
      • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

      Quando specifichi valori uris che hanno come target più file, tutti questi file devono condividere uno schema compatibile.

      Per saperne di più sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa Cloud Storage.

    • STALENESS_INTERVAL: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione possa utilizzarli. Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

      Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.

      Per abilitare la memorizzazione nella cache dei metadati, specifica un valore valore letterale dell'intervallo compreso tra 30 minuti e 7 giorni. Ad esempio, specifica INTERVAL 4 HOUR per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono più vecchi, l'operazione recupera i metadati da Cloud Storage.

    • CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

      Imposta su AUTOMATIC per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere compreso tra 30 e 60 minuti.

      Impostalo su MANUAL se vuoi aggiornare la cache dei metadati in base a una pianificazione che hai stabilito. In questo caso, puoi chiamare la procedura di sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE per aggiornare la cache.

      Devi impostare CACHE_MODE se STALENESS_INTERVAL è impostato su un valore maggiore di 0.

  3. Fai clic su Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

bq

Opzione 1: file di definizione della tabella

Utilizza il comando bq mkdef per creare un file di definizione della tabella, quindi passa il percorso al comando bq mk come segue:

bq mkdef \
    --connection_id=CONNECTION_ID \
    --source_format=SOURCE_FORMAT \
  BUCKET_PATH > DEFINITION_FILE

bq mk --table \
    --external_table_definition=DEFINITION_FILE \
    --max_staleness=STALENESS_INTERVAL \
    PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \
    SCHEMA

Sostituisci quanto segue:

  • CONNECTION_ID: l'ID connessione, ad esempio myconnection

    Quando visualizzi i dettagli della connessione nella console Google Cloud , l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

    Per utilizzare una connessione predefinita, specifica DEFAULT anziché la stringa di connessione contenente PROJECT_ID.REGION.CONNECTION_ID.

  • SOURCE_FORMAT: il formato dell'origine dati esterna. Ad esempio, PARQUET.

  • BUCKET_PATH: il percorso del bucket Cloud Storage che contiene i dati della tabella, nel formato gs://bucket_name/[folder_name/]file_pattern.

    Puoi selezionare più file dal bucket specificando un carattere jolly asterisco (*) in file_pattern. Ad esempio: gs://mybucket/file00*.parquet. Per saperne di più, consulta Supporto dei caratteri jolly per gli URI Cloud Storage.

    Puoi specificare più bucket per l'opzione uris fornendo più percorsi.

    I seguenti esempi mostrano valori uris validi:

    • gs://bucket/path1/myfile.csv
    • gs://bucket/path1/*.parquet
    • gs://bucket/path1/file1*, gs://bucket1/path1/*

    Quando specifichi valori uris che hanno come target più file, tutti questi file devono condividere uno schema compatibile.

    Per saperne di più sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa Cloud Storage.

  • DEFINITION_FILE: il percorso del file di definizione della tabella sulla tua macchina locale.

  • STALENESS_INTERVAL: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione possa utilizzarli. Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

    Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.

    Per attivare la memorizzazione nella cache dei metadati, specifica un valore di intervallo compreso tra 30 minuti e 7 giorni, utilizzando il formato Y-M D H:M:S descritto nella documentazione del tipo di dati INTERVAL. Ad esempio, specifica 0-0 0 4:0:0 per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono più vecchi, l'operazione recupera i metadati da Cloud Storage.

  • DATASET: il nome del set di dati BigQuery in cui vuoi creare una tabella, ad esempio mydataset

  • EXTERNAL_TABLE_NAME: il nome della tabella che vuoi creare, ad esempio mytable

  • SCHEMA: lo schema per la tabella BigLake

Esempio:

bq mkdef
    --connection_id=myconnection
    --metadata_cache_mode=CACHE_MODE
    --source_format=CSV 'gs://mybucket/*.csv' > mytable_def

bq mk
    --table
    --external_table_definition=mytable_def='gs://mybucket/*.csv'
    --max_staleness=0-0 0 4:0:0
    myproject:mydataset.mybiglaketable
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

Per utilizzare il rilevamento automatico dello schema, imposta il flag --autodetect=true nel comando mkdef e ometti lo schema:

bq mkdef \
    --connection_id=myconnection \
    --metadata_cache_mode=CACHE_MODE \
    --source_format=CSV --autodetect=true \
    gs://mybucket/*.csv > mytable_def

bq mk \
    --table \
    --external_table_definition=mytable_def=gs://mybucket/*.csv \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable

Opzione 2: definizione della tabella incorporata

Anziché creare un file di definizione della tabella, puoi passare la definizione della tabella direttamente al comando bq mk. Utilizza il decoratore @connection per specificare la connessione da utilizzare alla fine del flag --external_table_definition.

bq mk --table \
  --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

Sostituisci quanto segue:

  • SOURCE_FORMAT: il formato dell'origine dati esterna

    Ad esempio, CSV.

  • BUCKET_PATH: il percorso del bucket Cloud Storage che contiene i dati della tabella, nel formato gs://bucket_name/[folder_name/]file_pattern.

    Puoi selezionare più file dal bucket specificando un carattere jolly asterisco (*) in file_pattern. Ad esempio: gs://mybucket/file00*.parquet. Per saperne di più, consulta Supporto dei caratteri jolly per gli URI Cloud Storage.

    Puoi specificare più bucket per l'opzione uris fornendo più percorsi.

    I seguenti esempi mostrano valori uris validi:

    • gs://bucket/path1/myfile.csv
    • gs://bucket/path1/*.parquet
    • gs://bucket/path1/file1*, gs://bucket1/path1/*

    Quando specifichi valori uris che hanno come target più file, tutti questi file devono condividere uno schema compatibile.

    Per saperne di più sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa Cloud Storage.

  • PROJECT_ID: il nome del progetto in cui vuoi creare la tabella, ad esempio myproject

  • REGION: la regione che contiene la connessione, us

  • CONNECTION_ID: l'ID connessione, ad esempio myconnection

    Quando visualizzi i dettagli della connessione nella console Google Cloud , l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

    Per utilizzare una connessione predefinita, specifica DEFAULT anziché la stringa di connessione contenente PROJECT_ID.REGION.CONNECTION_ID.

  • DATASET_NAME: il nome del set di dati in cui vuoi creare la tabella BigLake

  • TABLE_NAME: il nome della tabella BigLake

  • SCHEMA: lo schema per la tabella BigLake

Esempio:

bq mk --table \
    --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable \
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Chiama il metodo tables.insert dell'API e crea un ExternalDataConfiguration nella risorsa Table che passi.

Specifica la proprietà schema o imposta la proprietà autodetect su true per attivare il rilevamento automatico dello schema per le origini dati supportate.

Specifica la proprietà connectionId per identificare la connessione da utilizzare per connetterti a Cloud Storage.

Terraform

Questo esempio crea una tabella BigLake su dati non partizionati.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This queries the provider for project information.
data "google_project" "project" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.project.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding.
# This lets IAM permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with
# default expiration times for partitions and tables, a
# description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}


# This creates a BigQuery Table with automatic metadata caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema = jsonencode([
    { "name" : "country", "type" : "STRING" },
    { "name" : "product", "type" : "STRING" },
    { "name" : "price", "type" : "INT64" }
  ])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/data/*"]
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  depends_on = [time_sleep.default]
}

Per applicare la configurazione Terraform in un progetto Google Cloud , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

  1. Avvia Cloud Shell.

  2. Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

    Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).

  1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

    Copia il codice campione nel file main.tf appena creato.

    Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

  3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
  4. Salva le modifiche.
  5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory. 
    terraform init

    Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade: 

    terraform init -upgrade

Applica le modifiche

  1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

  2. Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt: 
    terraform apply

    Attendi che Terraform visualizzi il messaggio "Apply complete!".

  3. Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

BigLake supporta il rilevamento automatico dello schema. Tuttavia, se non hai fornito uno schema e al account di servizio non è stato concesso l'accesso nei passaggi precedenti, questi passaggi non vanno a buon fine e viene visualizzato un messaggio di accesso negato se provi a rilevare automaticamente lo schema.

Crea tabelle BigLake su dati partizionati Apache Hive

Puoi creare una tabella BigLake per i dati partizionati Hive in Cloud Storage. Dopo aver creato una tabella partizionata esternamente, non puoi modificare la chiave di partizione. Devi ricreare la tabella per modificare la chiave di partizione.

Prima di creare una tabella BigLake, devi disporre di un set di dati e di una connessione alle risorse Cloud che possa accedere a Cloud Storage.

Per creare una tabella BigLake basata su dati partizionati Hive in Cloud Storage, seleziona una delle seguenti opzioni:

Console

  1. Vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

    Pulsante evidenziato per il riquadro Spazio di esplorazione.

    Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.

  3. Nel riquadro Explorer, espandi il progetto, fai clic su Set di dati, quindi su un set di dati.

  4. Fai clic su Crea tabella. Viene visualizzato il riquadro Crea tabella.

  5. Nella sezione Origine, specifica i seguenti dettagli:

    1. In Crea tabella da, seleziona Google Cloud Storage.

    2. Specifica il percorso della cartella utilizzando i caratteri jolly. Ad esempio, my_bucket/my_files*. La cartella deve trovarsi nella stessa località del set di dati che contiene la tabella che vuoi creare, aggiungere o sovrascrivere.

    3. Nell'elenco Formato file, seleziona il tipo di file.

    4. Seleziona la casella di controllo Partizionamento dei dati di origine, quindi specifica i seguenti dettagli:

      1. In Seleziona il prefisso URI di origine, inserisci il prefisso URI. Ad esempio, gs://my_bucket/my_files.
      2. (Facoltativo) Per richiedere un filtro di partizione su tutte le query per questa tabella, seleziona la casella di controllo Richiedi filtro di partizione. Se il filtro di partizionamento è obbligatorio, i costi possono essere ridotti e le prestazioni migliorate. Per saperne di più, consulta Richiedere filtri di predicato sulle chiavi di partizione nelle query.

      3. Nella sezione Modalità di inferenza della partizione, seleziona una delle seguenti opzioni:

        • Deduci automaticamente i tipi: imposta la modalità di rilevamento dello schema di partizione su AUTO.
        • Tutte le colonne sono stringhe: imposta la modalità di rilevamento dello schema di partizione su STRINGS.
        • Fornisci il tuo: imposta la modalità di rilevamento dello schema di partizione su CUSTOM e inserisci manualmente le informazioni sullo schema per le chiavi di partizione. Per saperne di più, consulta Fornisci uno schema di chiave di partizione personalizzato.

  6. Nella sezione Destinazione, specifica i seguenti dettagli:

    1. In Progetto, seleziona il progetto in cui vuoi creare la tabella.
    2. In Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
    3. In Tabella, inserisci il nome della tabella che vuoi creare.
    4. In Tipo di tabella, seleziona Tabella esterna.
    5. Seleziona la casella di controllo Crea una tabella BigLake utilizzando una connessione alle risorse Cloud.
    6. In ID connessione, seleziona la connessione che hai creato in precedenza.

  7. Nella sezione Schema, attiva il rilevamento automatico dello schema selezionando l'opzione Rilevamento automatico.

  8. Per ignorare le righe con valori di colonna aggiuntivi che non corrispondono allo schema, espandi la sezione Opzioni avanzate e seleziona Valori sconosciuti.

  9. Fai clic su Crea tabella.

SQL

Utilizza l'istruzione DDL CREATE EXTERNAL TABLE:

  1. Nella console Google Cloud , vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente istruzione:

    CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
WITH PARTITION COLUMNS
(
  PARTITION_COLUMN PARTITION_COLUMN_TYPE,
)
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID` | DEFAULT}
OPTIONS (
  hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
  uris=['FILE_PATH'],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE',
  format ="TABLE_FORMAT"
);

    Sostituisci quanto segue:

    • PROJECT_ID: il nome del progetto in cui vuoi creare la tabella, ad esempio myproject
    • DATASET: il nome del set di dati BigQuery in cui vuoi creare la tabella, ad esempio mydataset
    • EXTERNAL_TABLE_NAME: il nome della tabella che vuoi creare, ad esempio mytable
    • PARTITION_COLUMN: il nome della colonna di partizionamento
    • PARTITION_COLUMN_TYPE: il tipo di colonna di partizionamento
    • REGION: la regione che contiene la connessione, ad esempio us
    • CONNECTION_ID: l'ID connessione, ad esempio myconnection

      Quando visualizzi i dettagli della connessione nella console Google Cloud , l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

      Per utilizzare una connessione predefinita, specifica DEFAULT anziché la stringa di connessione contenente PROJECT_ID.REGION.CONNECTION_ID.

    • HIVE_PARTITION_URI_PREFIX: prefisso URI del partizionamento Hive, ad esempio gs://mybucket/
    • FILE_PATH: il percorso dell'origine dati per la tabella esterna che vuoi creare, ad esempio gs://mybucket/*.parquet
    • STALENESS_INTERVAL: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione possa utilizzarli. Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

      Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.

      Per abilitare la memorizzazione nella cache dei metadati, specifica un valore valore letterale dell'intervallo compreso tra 30 minuti e 7 giorni. Ad esempio, specifica INTERVAL 4 HOUR per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono più vecchi, l'operazione recupera i metadati da Cloud Storage.

    • CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

      Imposta su AUTOMATIC per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere compreso tra 30 e 60 minuti.

      Impostalo su MANUAL se vuoi aggiornare la cache dei metadati in base a una pianificazione che hai stabilito. In questo caso, puoi chiamare la procedura di sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE per aggiornare la cache.

      Devi impostare CACHE_MODE se STALENESS_INTERVAL è impostato su un valore maggiore di 0.

    • TABLE_FORMAT: il formato della tabella che vuoi creare, ad esempio PARQUET

  3. Fai clic su Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

Esempi

L'esempio seguente crea una tabella BigLake su dati partizionati dove:

  • Lo schema viene rilevato automaticamente.
  • L'intervallo di inattività della cache dei metadati per la tabella è di 1 giorno.
  • La cache dei metadati viene aggiornata automaticamente.
CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

L'esempio seguente crea una tabella BigLake su dati partizionati dove:

  • Lo schema è specificato.
  • L'intervallo di inattività della cache dei metadati per la tabella è di 8 ore.
  • La cache dei metadati deve essere aggiornata manualmente.
CREATE EXTERNAL TABLE `my_dataset.my_table`
(
  ProductId INTEGER,
  ProductName STRING,
  ProductType STRING
)
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 8 HOUR,
  metadata_cache_mode = 'MANUAL'
);

bq

Innanzitutto, utilizza il comando bq mkdef per creare un file di definizione della tabella:

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 GCS_URIS > DEFINITION_FILE

Sostituisci quanto segue:

  • SOURCE_FORMAT: il formato dell'origine dati esterna. Ad esempio, CSV.
  • REGION: la regione che contiene la connessione, ad esempio us.

  • CONNECTION_ID: l'ID connessione, ad esempio myconnection.

    Quando visualizzi i dettagli della connessione nella console Google Cloud , l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

    Per utilizzare una connessione predefinita, specifica DEFAULT anziché la stringa di connessione contenente PROJECT_ID.REGION.CONNECTION_ID.

  • PARTITIONING_MODE: la modalità di partizionamento Hive. Utilizza uno dei seguenti valori:

    • AUTO: rileva automaticamente i nomi e i tipi di chiavi.
    • STRINGS: converte automaticamente i nomi delle chiavi in stringhe.
    • CUSTOM: codifica lo schema della chiave nel prefisso dell'URI di origine.

  • GCS_URI_SHARED_PREFIX: il prefisso dell'URI di origine.

  • BOOLEAN: specifica se richiedere un filtro del predicato al momento della query. Questo flag è facoltativo. Il valore predefinito è false.

  • CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Devi includere questo flag solo se prevedi di utilizzare anche il flag --max_staleness nel comando bq mk successivo per attivare la memorizzazione nella cache dei metadati. Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

    Imposta su AUTOMATIC per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere compreso tra 30 e 60 minuti.

    Imposta su MANUAL se vuoi aggiornare la cache dei metadati in base a una pianificazione che hai stabilito. In questo caso, puoi chiamare la procedura di sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE per aggiornare la cache.

    Devi impostare CACHE_MODE se STALENESS_INTERVAL è impostato su un valore maggiore di 0.

  • GCS_URIS: il percorso della cartella Cloud Storage, utilizzando il formato con caratteri jolly.

  • DEFINITION_FILE: il percorso del file di definizione della tabella sulla tua macchina locale.

Se PARTITIONING_MODE è CUSTOM, includi lo schema della chiave di partizione nel prefisso dell'URI di origine, utilizzando il seguente formato:

--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Dopo aver creato il file di definizione della tabella, utilizza il comando bq mk per creare la tabella BigLake:

bq mk --external_table_definition=DEFINITION_FILE \
--max_staleness=STALENESS_INTERVAL \
DATASET_NAME.TABLE_NAME \
SCHEMA

Sostituisci quanto segue:

  • DEFINITION_FILE: il percorso del file di definizione della tabella.

  • STALENESS_INTERVAL: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione possa utilizzarli. Se includi questo flag, devi aver specificato anche un valore per il flag --metadata_cache_mode nel comando bq mkdef precedente. Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

    Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.

    Per attivare la memorizzazione nella cache dei metadati, specifica un valore di intervallo compreso tra 30 minuti e 7 giorni, utilizzando il formato Y-M D H:M:S descritto nella documentazione del tipo di dati INTERVAL. Ad esempio, specifica 0-0 0 4:0:0 per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono più vecchi, l'operazione recupera i metadati da Cloud Storage.

  • DATASET_NAME: il nome del set di dati che contiene la tabella.

  • TABLE_NAME: il nome della tabella che stai creando.

  • SCHEMA: specifica un percorso di un file di schema JSON o specifica lo schema nel formato field:data_type,field:data_type,.... Per utilizzare il rilevamento automatico dello schema, ometti questo argomento.

Esempi

L'esempio seguente utilizza la modalità di partizionamento Hive AUTO e imposta anche la cache dei metadati in modo che abbia un intervallo di inattività di 12 ore e venga aggiornata automaticamente:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  --max_staleness=0-0 0 12:0:0 \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

L'esempio seguente utilizza la modalità di partizionamento Hive STRING:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

L'esempio seguente utilizza la modalità di partizionamento Hive CUSTOM:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=CUSTOM \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Per impostare il partizionamento Hive utilizzando l'API BigQuery, includi l'oggetto hivePartitioningOptions nell'oggetto ExternalDataConfiguration quando crei il file di definizione della tabella. Per creare una tabella BigLake, devi anche specificare un valore per il campo connectionId.

Se imposti il campo hivePartitioningOptions.mode su CUSTOM, devi codificare lo schema della chiave di partizione nel campo hivePartitioningOptions.sourceUriPrefix come segue: gs://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Per applicare l'utilizzo di un filtro di predicato al momento della query, imposta il campo hivePartitioningOptions.requirePartitionFilter su true.

Terraform

Questo esempio crea una tabella BigLake su dati partizionati.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.


# This creates a bucket in the US region named "my-bucket" with a pseudorandom
# suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

resource "google_storage_bucket_object" "default" {
  # This creates a fake message to create partition locations on the table.
  # Otherwise, the table deployment fails.
  name    = "publish/dt=2000-01-01/hr=00/min=00/fake_message.json"
  content = "{\"column1\": \"XXX\"}"
  bucket  = google_storage_bucket.default.name
}

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding. This lets IAM
# permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with default expiration times for
# partitions and tables, a description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery table with partitioning and automatic metadata
# caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema     = jsonencode([{ "name" : "column1", "type" : "STRING", "mode" : "NULLABLE" }])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/publish/*"]
    # This configures Hive partitioning for the BigQuery table,
    # partitioning the data by date and time.
    hive_partitioning_options {
      mode                     = "CUSTOM"
      source_uri_prefix        = "gs://${google_storage_bucket.default.name}/publish/{dt:STRING}/{hr:STRING}/{min:STRING}"
      require_partition_filter = false
    }
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }


  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  depends_on = [
    time_sleep.default,
    google_storage_bucket_object.default
  ]
}

Per applicare la configurazione Terraform in un progetto Google Cloud , completa i passaggi descritti nelle sezioni seguenti.

Prepara Cloud Shell

  1. Avvia Cloud Shell.

  2. Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

    Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).

  1. In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

    Copia il codice campione nel file main.tf appena creato.

    Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.

  3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
  4. Salva le modifiche.
  5. Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory. 
    terraform init

    Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione -upgrade: 

    terraform init -upgrade

Applica le modifiche

  1. Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative: 
    terraform plan

    Apporta le correzioni necessarie alla configurazione.

  2. Applica la configurazione Terraform eseguendo il comando seguente e inserendo yes al prompt: 
    terraform apply

    Attendi che Terraform visualizzi il messaggio "Apply complete!".

  3. Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Configura le policy di controllo dell'accesso

Puoi utilizzare diversi metodi per controllare l'accesso alle tabelle BigLake:

Ad esempio, supponiamo che tu voglia limitare l'accesso alle righe per la tabella mytable nel set di dati mydataset:

+---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
| JP      | tablet  |   300 |
| UK      | laptop  |   200 |
+---------+---------+-------+

Puoi creare un filtro a livello di riga per Kim (kim@example.com) che limita l'accesso alle righe in cui country è uguale a US.

CREATE ROW ACCESS POLICY only_us_filter
ON mydataset.mytable
GRANT TO ('user:kim@example.com')
FILTER USING (country = 'US');

Quindi, Kim esegue la seguente query:

SELECT * FROM projectid.mydataset.mytable;

L'output mostra solo le righe in cui country è uguale a US:

+---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
+---------+---------+-------+

Esegui query sulle tabelle BigLake

Per saperne di più, consulta Esegui query sui dati di Cloud Storage nelle tabelle BigLake.

Aggiorna le tabelle BigLake

Se necessario, puoi aggiornare le tabelle BigLake, ad esempio per modificare la memorizzazione nella cache dei metadati. Per ottenere i dettagli della tabella, come il formato e l'URI di origine, consulta Ottieni informazioni sulla tabella.

Puoi anche utilizzare questa stessa procedura per eseguire l'upgrade delle tabelle esterne basate su Cloud Storage alle tabelle BigLake associando la tabella esterna a una connessione. Per saperne di più, consulta Esegui l'upgrade delle tabelle esterne alle tabelle BigLake.

Per aggiornare una tabella BigLake, seleziona una delle seguenti opzioni:

SQL

Utilizza l'istruzione DDL CREATE OR REPLACE EXTERNAL TABLE per aggiornare una tabella:

  1. Nella console Google Cloud , vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente istruzione:

    CREATE OR REPLACE EXTERNAL TABLE
  `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION {`REGION.CONNECTION_ID` | DEFAULT}
  OPTIONS(
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );

    Sostituisci quanto segue:

    • PROJECT_ID: il nome del progetto che contiene la tabella
    • DATASET: il nome del set di dati che contiene la tabella
    • EXTERNAL_TABLE_NAME: il nome della tabella
    • REGION: la regione che contiene la connessione
    • CONNECTION_ID: il nome della connessione da utilizzare

      Per utilizzare una connessione predefinita, specifica DEFAULT anziché la stringa di connessione contenente REGION.CONNECTION_ID.

    • TABLE_FORMAT: il formato utilizzato dalla tabella

      Non puoi modificare questa impostazione durante l'aggiornamento della tabella.

    • BUCKET_PATH: il percorso del bucket Cloud Storage che contiene i dati per la tabella esterna, nel formato ['gs://bucket_name/[folder_name/]file_name'].

      Puoi selezionare più file dal bucket specificando un carattere jolly asterisco (*) nel percorso. Ad esempio, ['gs://mybucket/file_name*']. Per saperne di più, consulta Supporto dei caratteri jolly per gli URI Cloud Storage.

      Puoi specificare più bucket per l'opzione uris fornendo più percorsi.

      I seguenti esempi mostrano valori uris validi:

      • ['gs://bucket/path1/myfile.csv']
      • ['gs://bucket/path1/*.csv']
      • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

      Quando specifichi valori uris che hanno come target più file, tutti questi file devono condividere uno schema compatibile.

      Per saperne di più sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa Cloud Storage.

    • STALENESS_INTERVAL: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione li utilizzi

      Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

      Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.

      Per abilitare la memorizzazione nella cache dei metadati, specifica un valore valore letterale dell'intervallo compreso tra 30 minuti e 7 giorni. Ad esempio, specifica INTERVAL 4 HOUR per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono più vecchi, l'operazione recupera i metadati da Cloud Storage.

    • CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente

      Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

      Imposta su AUTOMATIC per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere compreso tra 30 e 60 minuti.

      Impostalo su MANUAL se vuoi aggiornare la cache dei metadati in base a una pianificazione che hai stabilito. In questo caso, puoi chiamare la procedura di sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE per aggiornare la cache.

      Devi impostare CACHE_MODE se STALENESS_INTERVAL è impostato su un valore maggiore di 0.

  3. Fai clic su Esegui.

Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.

bq

Utilizza i comandi bq mkdef e bq update per aggiornare una tabella:

  1. Genera una definizione di tabella esterna che descriva gli aspetti della tabella da modificare:

    bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
--source_format=TABLE_FORMAT \
--metadata_cache_mode=CACHE_MODE \
"BUCKET_PATH" > /tmp/DEFINITION_FILE

    Sostituisci quanto segue:

    • PROJECT_ID: il nome del progetto che contiene la connessione
    • REGION: la regione che contiene la connessione
    • CONNECTION_ID: il nome della connessione da utilizzare
    • TABLE_FORMAT: il formato utilizzato dalla tabella. Non puoi modificare questa impostazione durante l'aggiornamento della tabella.

    • CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per saperne di più sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

      Imposta su AUTOMATIC per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere compreso tra 30 e 60 minuti.

      Imposta su MANUAL se vuoi aggiornare la cache dei metadati in base a una pianificazione che hai stabilito. In questo caso, puoi chiamare la procedura di sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE per aggiornare la cache.

      Devi impostare CACHE_MODE se STALENESS_INTERVAL è impostato su un valore maggiore di 0.

    • BUCKET_PATH: il percorso del bucket Cloud Storage che contiene i dati per la tabella esterna, nel formato gs://bucket_name/[folder_name/]file_name.

      Puoi limitare i file selezionati dal bucket specificando un carattere jolly asterisco (*) nel percorso. Ad esempio, gs://mybucket/file_name*. Per saperne di più, consulta Supporto dei caratteri jolly per gli URI Cloud Storage.

      Puoi specificare più bucket per l'opzione uris fornendo più percorsi.

      I seguenti esempi mostrano valori uris validi:

      • gs://bucket/path1/myfile.csv
      • gs://bucket/path1/*.csv
      • gs://bucket/path1/*,gs://bucket/path2/file00*

      Quando specifichi valori uris che hanno come target più file, tutti questi file devono condividere uno schema compatibile.

      Per saperne di più sull'utilizzo degli URI Cloud Storage in BigQuery, consulta Percorso della risorsa Cloud Storage.

    • DEFINITION_FILE: il nome del file di definizione della tabella che stai creando.

  2. Aggiorna la tabella utilizzando la nuova definizione di tabella esterna:

    bq update --max_staleness=STALENESS_INTERVAL \
--external_table_definition=/tmp/DEFINITION_FILE \
PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME

    Sostituisci quanto segue:

    • STALENESS_INTERVAL: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella e quanto devono essere aggiornati i metadati memorizzati nella cache affinché l'operazione li utilizzi. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per le prestazioni.

      Per disattivare la memorizzazione nella cache dei metadati, specifica 0. Questa è l'impostazione predefinita.

      Per attivare la memorizzazione nella cache dei metadati, specifica un valore di intervallo compreso tra 30 minuti e 7 giorni, utilizzando il formato Y-M D H:M:S descritto nella documentazione del tipo di dati INTERVAL. Ad esempio, specifica 0-0 0 4:0:0 per un intervallo di inattività di 4 ore. Con questo valore, le operazioni sulla tabella utilizzano i metadati memorizzati nella cache se sono stati aggiornati nelle ultime 4 ore. Se i metadati memorizzati nella cache sono più vecchi, l'operazione recupera i metadati da Cloud Storage.

    • DEFINITION_FILE: il nome del file di definizione della tabella che hai creato o aggiornato.

    • PROJECT_ID: il nome del progetto che contiene la tabella

    • DATASET: il nome del set di dati che contiene la tabella

    • EXTERNAL_TABLE_NAME: il nome della tabella

Esempio

L'esempio seguente aggiorna mytable in modo che utilizzi i metadati memorizzati nella cache, purché siano stati aggiornati nelle ultime 4,5 ore, e che aggiorni automaticamente i metadati memorizzati nella cache:

bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable

Dove enable_metadata.json ha i seguenti contenuti: json { "metadataCacheMode": "AUTOMATIC" }

Audit logging

Per informazioni sul logging in BigQuery, consulta Introduzione al monitoraggio di BigQuery. Per scoprire di più sul logging in Google Cloud, consulta Cloud Logging.

Passaggi successivi