Creare tabelle esterne BigLake per Delta Lake

BigLake consente di accedere alle tabelle Delta Lake con un controllo dell'accesso più granulare. Delta Lake è un formato di archiviazione dei dati tabellari open source sviluppato da Databricks che supporta tabelle di dati su scala di petabyte.

BigQuery supporta le seguenti funzionalità con le tabelle Delta Lake:

  • Delega dell'accesso: esegui query sui dati strutturati negli archivi dati esterni con la delega dell'accesso. La delega dell'accesso disaccoppia l'accesso alla tabella Delta Lake dall'accesso al datastore sottostante.
  • Controllo dell'accesso granulare: applica una sicurezza granulare a livello di tabella, inclusa la sicurezza a livello di riga e colonna. Per le tabelle Delta Lake basate su Cloud Storage, puoi anche utilizzare la maschera dei dati dinamica.
  • Evoluzione dello schema: le modifiche dello schema nelle tabelle Delta Lake vengono rilevate automaticamente. Le modifiche allo schema vengono riportate nella tabella BigQuery.

Le tabelle Delta Lake supportano anche tutte le funzionalità BigLake quando le configuri come tabelle BigLake.

Prima di iniziare

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

    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 su 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' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.

    Vai al selettore di progetti

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

  3. Abilita le API BigQuery Connection e BigQuery Reservation.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

  4. Nella Google Cloud console, 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.

  7. Crea una connessione alle risorse Cloud basata sull'origine dati esterna e concedi a questa connessione l'accesso a Cloud Storage. Se non disponi delle autorizzazioni appropriate per creare una connessione, chiedi all'amministratore di BigQuery di crearne una e condividerla con te.

Ruoli obbligatori

Per creare una tabella Delta Lake sono necessarie le seguenti autorizzazioni:

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

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

Se non sei un principal in questo ruolo, chiedi all'amministratore di concederti queste autorizzazioni o di creare la tabella Delta Lake per te.

Inoltre, per consentire agli utenti di BigQuery di eseguire query sulla tabella, il account di servizio associato alla connessione deve disporre delle seguenti autorizzazioni e accesso:

  • Ruolo Visualizzatore BigQuery (roles/bigquery.viewer)
  • Ruolo Utente connessione BigQuery (roles/bigquery.connectionUser)
  • Accesso al bucket Cloud Storage che contiene i dati

Per ulteriori informazioni sui ruoli e sulle autorizzazioni di Identity and Access Management in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Creare tabelle con Delta Lake

Per creare tabelle Delta Lake, segui questi passaggi.

SQL

Utilizza l'istruzione CREATE EXTERNAL TABLEper creare la tabella Delta Lake: 

CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.DELTALAKE_TABLE_NAME`
WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (
  format ="DELTA_LAKE",
  uris=['DELTA_TABLE_GCS_BASE_PATH']);

Sostituisci i seguenti valori:

  • PROJECT_ID: l'ID del progetto in cui vuoi creare la tabella Delta Lake
  • DATASET: il set di dati BigQuery che deve contenere la tabella Delta Lake
  • DELTALAKE_TABLE_NAME: il nome della tabella Delta Lake
  • REGION: la regione che contiene la connessione per creare la tabella Delta Lake, ad esempio us

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

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

  • DELTA_TABLE_GCS_BASE_PATH: il prefisso della tabella Delta Lake

bq

In un ambiente della riga di comando, utilizza il bq mk comando per creare la tabella Delta Lake:

bq mk --table --external_table_definition=DEFINITION_FILE PROJECT_ID:DATASET.DELTALAKE_TABLE_NAME

Sostituisci i seguenti valori:

  • DEFINITION_FILE: il percorso di un file di definizione della tabella
  • PROJECT_ID: l'ID del progetto in cui vuoi creare la tabella Delta Lake
  • DATASET: il set di dati BigQuery che deve contenere la tabella Delta Lake
  • DELTALAKE_TABLE_NAME: il nome della tabella Delta Lake

REST

Utilizza l'API BigQuery per creare una tabella Delta Lake chiamando il metodo dell'API tables.insert:

REQUEST='{
  "autodetect": true,
  "externalDataConfiguration": {
  "sourceFormat": "DELTA_LAKE",
  "connectionId": "PROJECT_ID.REGION.CONNECTION_ID",
  "sourceUris": [
    "DELTA_TABLE_GCS_BASE_PATH"
  ],
 },
"tableReference": {
"tableId": "DELTALAKE_TABLE_NAME"
}
}'

echo $REQUEST | curl -X POST -d @- -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables?autodetect_schema=true

Sostituisci i seguenti valori:

  • PROJECT_ID: l'ID del progetto in cui vuoi creare la tabella Delta Lake
  • REGION: la regione che contiene la connessione per creare la tabella Delta Lake, ad esempio us

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

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

  • DELTA_TABLE_GCS_BASE_PATH: il prefisso della tabella Delta Lake

  • DELTALAKE_TABLE_NAME: il nome della tabella Delta Lake

  • DATASET: il set di dati BigQuery che deve contenere la tabella Delta Lake

Quando crei tabelle Delta Lake, il prefisso Delta Lake viene utilizzato come URI per la tabella. Ad esempio, per una tabella che contiene log nel bucket gs://bucket/warehouse/basictable/_delta_log, l'URI della tabella è gs://bucket/warehouse/basictable. Quando esegui query sulla tabella Delta Lake, BigQuery legge i dati sotto il prefisso per identificare la versione corrente della tabella, quindi calcola i metadati e i file per la tabella.

Sebbene tu possa creare tabelle esterne Delta Lake senza una connessione, non è consigliabile per i seguenti motivi:

  • Gli utenti potrebbero riscontrare errori ACCESS_DENIED quando tentano di accedere ai file su Cloud Storage.
  • Funzionalità come il controllo dell'accesso granulare sono disponibili solo nelle tabelle BigLake Delta Lake.

Aggiornare le tabelle Delta Lake

Per aggiornare (aggiornare) lo schema delle tabelle Delta Lake, segui questi passaggi.

bq

In un ambiente della riga di comando, utilizza il bq update comando per aggiornare (aggiornare) lo schema della tabella Delta Lake:

bq update --autodetect_schema PROJECT_ID:DATASET.DELTALAKE_TABLE_NAME

Sostituisci i seguenti valori:

  • PROJECT_ID: l'ID del progetto in cui vuoi creare la tabella Delta Lake
  • DATASET: il set di dati BigQuery che deve contenere la tabella Delta Lake
  • DELTALAKE_TABLE_NAME: il nome della tabella Delta Lake

REST

Utilizza l'API BigQuery per aggiornare una tabella Delta Lake chiamando il metodo dell'API tables.patch:

REQUEST='{
  "externalDataConfiguration": {
    "sourceFormat": "DELTA_LAKE",
    "sourceUris": [
      "DELTA_TABLE_GCS_BASE_PATH"
    ],
    "connectionId": "PROJECT_ID.REGION.CONNECTION_ID",
    "autodetect": true
  }
}'
echo $REQUEST |curl -X PATCH -d @- -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/DELTALAKE_TABLE_NAME?autodetect_schema=true

Sostituisci i seguenti valori:

  • DELTA_TABLE_GCS_BASE_PATH: il prefisso della tabella Delta Lake
  • PROJECT_ID: l'ID del progetto in cui vuoi creare la tabella Delta Lake
  • REGION: la regione che contiene la connessione per creare la tabella Delta Lake, ad esempio us

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

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

  • DELTALAKE_TABLE_NAME: il nome della tabella Delta Lake

  • DATASET: il set di dati BigQuery che deve contenere la tabella Delta Lake

Eseguire query sulle tabelle Delta Lake

Dopo aver creato una tabella BigLake Delta Lake, puoi eseguirne query utilizzando la sintassi GoogleSQL, come faresti con una tabella BigQuery standard. Ad esempio:

SELECT field1, field2 FROM mydataset.my_cloud_storage_table;

Per ulteriori informazioni, consulta Eseguire query sui dati di Cloud Storage nelle tabelle BigLake.

Per connettersi al datastore viene utilizzata una connessione esterna associata a un account di servizio. Poiché il service account recupera i dati dal datastore, gli utenti hanno bisogno solo dell'accesso alla tabella Delta Lake.

Mappatura dei dati

BigQuery converte i tipi di dati Delta Lake in tipi di dati BigQuery come mostrato nella tabella seguente:

Tipo Delta Lake Tipo BigQuery
boolean BOOL
byte INT64
int INT64
long INT64
float FLOAT64
double FLOAT64
Decimal(P/S) NUMERIC o BIG_NUMERIC a seconda della precisione
date DATE
time TIME
timestamp (not partition column) TIMESTAMP
timestamp (partition column) DATETIME
string STRING
binary BYTES
array<Type> ARRAY<Type>
struct STRUCT
map<KeyType, ValueType> ARRAY<Struct<key KeyType, value ValueType>>

Limitazioni

Le tabelle Delta Lake presentano limitazioni delle tabelle BigLake e anche le seguenti limitazioni:

  • Supporta la versione del lettore Delta Lake 3 con vettori di eliminazione del percorso relativo e mappatura delle colonne.
  • Non supporta i punti di controllo Delta Lake V2.
  • Devi elencare la versione del lettore nell'ultimo file di voce di log. Ad esempio, le nuove tabelle devono includere 00000..0.json.
  • Le operazioni di change data capture (CDC) non sono supportate. Eventuali operazioni CDC esistenti vengono ignorate.
  • Lo schema viene rilevato automaticamente. La modifica dello schema tramite BigQuery non è supportata.
  • I nomi delle colonne delle tabelle devono rispettare le limitazioni dei nomi delle colonne di BigQuery column name restrictions.
  • Le viste materializzate non sono supportate.
  • L'API Read non è supportata per Delta Lake.
  • Il tipo di dati timestamp_ntz non è supportato per le tabelle BigLake Delta Lake.

Risoluzione dei problemi

Questa sezione fornisce assistenza per le tabelle BigLake Delta Lake. Per un aiuto più generale per la risoluzione dei problemi delle query BigQuery, consulta Risolvere i problemi delle query.

Errori di timeout e risorse delle query

Controlla la directory dei log (gs://bucket/warehouse/basictable/_delta_log) della tabella Delta Lake e cerca i file JSON con un numero di versione maggiore del precedente punto di controllo. Puoi ottenere il numero di versione elencando la directory o esaminando il file _delta_log/_last_checkpoint. I file JSON di dimensioni superiori a 10 MiB possono rallentare l'espansione della tabella, il che può causare problemi di timeout e risorse. Per risolvere il problema, utilizza il seguente comando per creare un nuovo punto di controllo in modo che le query saltino la lettura dei file JSON:

  spark.sql("ALTER TABLE delta.`gs://bucket/mydeltatabledir` SET TBLPROPERTIES ('delta.checkpointInterval' = '1')");

Gli utenti possono quindi utilizzare lo stesso comando per reimpostare l'intervallo del punto di controllo sul valore predefinito di 10 o su un valore che eviti di avere più di 50 MB di file JSON tra i punti di controllo.

Nome colonna non valido

Assicurati che la mappatura delle colonne sia attivata per la tabella Delta Lake. La mappatura delle colonne è supportata con la versione 2 o successive del lettore. Per la versione 1 del lettore, imposta "delta.columnMapping.mode" su "name" utilizzando il seguente comando:

spark.sql("ALTER TABLE delta.`gs://bucket/mydeltatabledir` SET TBLPROPERTIES ('delta.columnMapping.mode' = 'name', 'delta.minReaderVersion' = '3', 'delta.minWriterVersion' = '7')");

biglake-help@google.com

Errori di accesso negato

Per diagnosticare i problemi con le tabelle BigLake Delta Lake, controlla quanto segue:

Prestazioni

Per migliorare le prestazioni delle query, prova a svolgere i seguenti passaggi:

  • Utilizza le utilità Delta Lake per compattare i file di dati sottostanti e rimuovere i file ridondanti, come dati e metadati.

  • Assicurati che delta.checkpoint.writeStatsAsStruct sia impostato su true.

  • Assicurati che le variabili utilizzate di frequente nelle clausole del predicato si trovino nelle colonne di partizionamento.

I set di dati di grandi dimensioni (maggiori di 100 TB) potrebbero trarre vantaggio da configurazioni e funzionalità aggiuntive. Se i passaggi precedenti non risolvono i problemi, valuta la possibilità di contattare l'assistenza clienti o biglake-help@google.com, soprattutto per i set di dati di dimensioni superiori a 100 TB.