Questa pagina è stata tradotta dall'API Cloud Translation.

Esegui query sui formati delle tabelle aperte con i manifest

Questo documento descrive come utilizzare i file manifest per eseguire query sui dati archiviati in formati di tabella aperti come Apache Hudi e Delta Lake.

Alcuni formati di tabelle aperte, come Hudi e Delta Lake, esportano il loro stato attuale come uno o più file manifest. Un file manifest contiene un elenco di file di dati che formano tabelle. Con il supporto del manifest in BigQuery, puoi eseguire query e caricare i dati archiviati in formati di tabelle aperte.

Prima di iniziare

Enable the BigQuery Connection, BigQuery Reservation, and BigLake APIs.
Enable the APIs
Per creare tabelle BigLake, puoi eseguire i comandi Spark utilizzando uno dei seguenti metodi:
- Crea un cluster Dataproc. Per eseguire query sulle tabelle Hudi, imposta il campo --optional-components su HUDI. Per eseguire query sulle tabelle Delta, imposta --optional-components su Presto.
- Utilizza una stored procedure per Spark in BigQuery. Per farlo, segui questi passaggi:
  1. Crea una connessione Spark.
  2. Configura il controllo dell'accesso per la connessione.
Per archiviare il file manifest in Cloud Storage, crea un bucket Cloud Storage. Devi collegarti al tuo bucket Cloud Storage per accedere al file manifest. Per farlo, segui questi passaggi:
1. Crea una connessione alla risorsa Cloud.
2. Configura l'accesso per la connessione.

Ruoli obbligatori

Per eseguire query sulle tabelle BigLake in base ai dati di Hudi e Delta Lake, assicurati di disporre dei seguenti ruoli:

Utente connessione BigQuery (roles/bigquery.connectionUser)
Visualizzatore dati BigQuery (roles/bigquery.dataViewer)
Utente BigQuery (roles/bigquery.user)

Puoi anche eseguire query sulle tabelle esterne Hudi. Tuttavia, ti consigliamo di eseguire l'upgrade della tabella esterna a BigLake. Per eseguire query sulle tabelle esterne di Hudi, assicurati di disporre dei seguenti ruoli:

Visualizzatore dati BigQuery (roles/bigquery.dataViewer)
Utente BigQuery (roles/bigquery.user)
Storage Object Viewer (roles/storage.objectViewer)

A seconda delle tue autorizzazioni, puoi concederti questi ruoli o chiedere all'amministratore di concederteli. Per ulteriori informazioni sulla concessione dei ruoli, consulta Visualizzazione dei ruoli assegnabili sulle risorse.

Per visualizzare le autorizzazioni esatte necessarie per eseguire query sulle tabelle BigLake, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

bigquery.connections.use
bigquery.jobs.create
bigquery.readsessions.create (obbligatorio solo se leggi i dati con l'API BigQuery Storage Read)
bigquery.tables.get
bigquery.tables.getData

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Esegui query sui carichi di lavoro Hudi

Per eseguire query sui dati Hudi, segui questi passaggi:

Crea una tabella esterna in base ai dati di Hudi.
Esegui l'upgrade della tabella esterna a BigLake.

Creare tabelle esterne Hudi

Quando sincronizzi le tabelle utilizzando lo strumento di sincronizzazione per Hudi e BigQuery, attiva il flag use-bq-manifest-file per eseguire la transizione all'approccio del file manifest. Questo flag esporta anche un file manifest in un formato supportato da BigQuery e lo utilizza per creare una tabella esterna con il nome specificato nel parametro --table.

Per creare una tabella esterna Hudi:

Per creare una tabella esterna Hudi, invia un job a un cluster Dataproc esistente. Quando crei il connettore Hudi-BigQuery, attiva il flag use-bq-manifest-file per passare all'approccio del file manifest. Questo flag esporta un file manifest in un formato supportato da BigQuery e lo utilizza per creare una tabella esterna con il nome specificato nel parametro --table.
```
spark-submit \
   --master yarn \
   --packages com.google.cloud:google-cloud-bigquery:2.10.4 \
   --class org.apache.hudi.gcp.bigquery.BigQuerySyncTool  \
   JAR \
   --project-id PROJECT_ID \
   --dataset-name DATASET \
   --dataset-location LOCATION \
   --table TABLE \
   --source-uri URI  \
   --source-uri-prefix URI_PREFIX \
   --base-path BASE_PATH  \
   --partitioned-by PARTITION_BY \
   --use-bq-manifest-file
```
Sostituisci quanto segue:
- JAR: se utilizzi il connettore Hudi-BigQuery, specifica hudi-gcp-bundle-0.14.0.jar. Se utilizzi il componente Hudi in Dataproc 2.1, specifica /usr/lib/hudi/tools/bq-sync-tool/hudi-gcp-bundle-0.12.3.1.jar
- PROJECT_ID: l'ID progetto in cui vuoi creare la tabella Hudi BigLake
- DATASET: il set di dati in cui vuoi creare la tabella Hudi BigLake
- LOCATION: la posizione in cui vuoi creare la tabella Hudi BigLake
- TABLE: il nome della tabella che vuoi creare
  
  Se stai eseguendo la transizione dalla versione precedente del connettore Hudi-BigQuery (0.13.0 e versioni precedenti) che ha creato visualizzazioni nei file manifest, assicurati di utilizzare lo stesso nome della tabella, in quanto ti consente di mantenere il codice della pipeline a valle esistente.
- URI: l'URI Cloud Storage che hai creato per archiviare il file manifest di Hudi
  
  Questo URI punta alla partizione di primo livello. Assicurati di includere la chiave della partizione. Ad esempio, gs://mybucket/hudi/mydataset/EventDate=*
- URI_PREFIX: il prefisso per il percorso dell'URI di Cloud Storage, in genere il percorso alle tabelle Hudi
- BASE_PATH: il percorso di base per le tabelle Hudi
  
  Ad esempio, gs://mybucket/hudi/mydataset/
- PARTITION_BY: il valore della partizione
  
  Ad esempio, EventDate
Per ulteriori informazioni sulla configurazione del connettore, consulta Connettore Hudi-BigQuery.
Per impostare controlli granulari appropriati o per accelerare le prestazioni attivando la memorizzazione nella cache dei metadati, consulta Eseguire l'upgrade delle tabelle BigLake.

Esegui query sui carichi di lavoro Delta

Le tabelle Delta sono ora supportate in modo nativo. Ti consigliamo di creare tabelle Delta BigLake per i carichi di lavoro Delta. Le tabelle BigLake di Delta Lake supportano le tabelle Delta Lake più avanzate, incluse le tabelle con vettori di eliminazione e rimappatura delle colonne. Inoltre, le tabelle Delta BigLake leggono direttamente l'ultimo snapshot, quindi gli aggiornamenti sono disponibili immediatamente.

Per eseguire query sui carichi di lavoro Delta:

Genera un file manifest.
Crea una tabella BigLake basata sul file manifest.
Imposta controlli granulari appropriati o accelera le prestazioni attivando la memorizzazione nella cache dei metadati. Per farlo, consulta Eseguire l'upgrade delle tabelle BigLake.

Generare un file manifest

BigQuery supporta il file manifest in un formato SymLinkTextInputFormat, ovvero un elenco di URI delimitati da una nuova riga. Per ulteriori informazioni sulla generazione di un file manifest, consulta Configurare l'integrazione di Presto con Delta Lake ed eseguire query sulle tabelle Delta.

Per generare un file manifest, invia un job a un cluster Dataproc esistente:

SQL

Utilizzando Spark, esegui il seguente comando su una tabella Delta nella posizione path-to-delta-table:

GENERATE symlink_format_manifest FOR TABLE delta.`<path-to-delta-table>`

Scala

Utilizzando Spark, esegui il seguente comando su una tabella Delta nella posizione path-to-delta-table:

val deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Java

Utilizzando Spark, esegui il seguente comando su una tabella Delta nella posizione path-to-delta-table:

DeltaTable deltaTable = DeltaTable.forPath(<path-to-delta-table>);
deltaTable.generate("symlink_format_manifest");

Python

Utilizzando Spark, esegui il seguente comando su una tabella Delta nella posizione path-to-delta-table:

deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Crea tabelle Delta BigLake

Per creare una tabella Delta BigLake, utilizza l'istruzione CREATE EXTERNAL TABLE con il campo file_set_spec_type impostato su NEW_LINE_DELIMITED_MANIFEST:

Vai alla pagina BigQuery.

Vai a BigQuery
Nell'editor di query, esegui l'istruzione CREATE EXTERNAL TABLE:
```
CREATE EXTERNAL TABLE PROJECT_ID.DATASET_NAME.TABLE_NAME
WITH PARTITION COLUMNS(
`PARTITION_COLUMN PARTITION_COLUMN_TYPE`,)
WITH CONNECTION `PROJECT_IDREGION.CONNECTION_NAME`
OPTIONS (
   format = "DATA_FORMAT",
   uris = ["URI"],
   file_set_spec_type = 'NEW_LINE_DELIMITED_MANIFEST',
   hive_partition_uri_prefix = "PATH_TO_DELTA_TABLE"
   max_staleness = STALENESS_INTERVAL,
   metadata_cache_mode = 'CACHE_MODE');
```
Sostituisci quanto segue:
- DATASET_NAME: il nome del set di dati creato
- TABLE_NAME: il nome che vuoi assegnare a questa tabella
- REGION: la posizione in cui si trova la connessione (ad esempio us-east1)
- CONNECTION_NAME: il nome della connessione che hai creato
- DATA_FORMAT: uno dei formati supportati (ad esempio PARQUET)
- URI: il percorso del file manifest (ad esempio, gs://mybucket/path)
- PATH_TO_DELTA_TABLE: un prefisso comune per tutti gli URI di origine prima dell'inizio della codifica della chiave di partizione
- STALENESS_INTERVAL: specifica se i metadati memorizzati nella cache vengono utilizzati dalle operazioni sulla tabella BigLake e quanto devono essere aggiornati per poter essere utilizzati dall'operazione. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.
  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 letterale 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 precedenti a questa data, l'operazione recupera i metadati da Delta Lake.
- CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.
  Imposta su AUTOMATIC per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere tra 30 e 60 minuti.
  
  Imposta MANUAL se vuoi aggiornare la cache dei metadati in base a una pianificazione da te stabilita. 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.
Esempio:
```
CREATE EXTERNAL TABLE mydataset.mytable
WITH CONNECTION `us-east1.myconnection`
OPTIONS (
    format="PARQUET",
    uris=["gs://mybucket/path/partitionpath=*"],
    file_set_spec_type = 'NEW_LINE_DELIMITED_MANIFEST'
    hive_partition_uri_prefix = "gs://mybucket/path/"
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);
```

Eseguire l'upgrade delle tabelle BigLake

Puoi anche accelerare le prestazioni dei tuoi carichi di lavoro sfruttando la memorizzazione nella cache dei metadati e le viste materializzate. Se vuoi utilizzare la memorizzazione nella cache dei metadati, puoi specificare le impostazioni contemporaneamente. Per visualizzare i dettagli della tabella, come il formato e l'URI di origine, consulta Ottenere informazioni sulle tabelle.

Per aggiornare una tabella esterna in una tabella BigLake o aggiornare un BigLake esistente, seleziona una delle seguenti opzioni:

SQL

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

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nell'editor di query, inserisci la seguente istruzione:
```
CREATE OR REPLACE EXTERNAL TABLE
  `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION `REGION.CONNECTION_ID`
  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
- TABLE_FORMAT: il formato utilizzato dalla tabella
  
  Non puoi modificarlo quando aggiorni la tabella.
- BUCKET_PATH: il percorso del bucket Cloud Storage contenente i dati della 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 ulteriori informazioni, consulta Supporto dei caratteri jolly per gli URI di Cloud Storage.
  
  Puoi specificare più bucket per l'opzione uris fornendo più percorsi.
  
  Gli esempi seguenti 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 ulteriori informazioni 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 possa utilizzarli
  
  Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.
  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 letterale 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 precedenti a questa data, l'operazione recupera i metadati da Cloud Storage.
- CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente
  
  Per ulteriori informazioni su considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.
  Imposta su AUTOMATIC per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere tra 30 e 60 minuti.
  
  Imposta MANUAL se vuoi aggiornare la cache dei metadati in base a una pianificazione da te stabilita. 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.
Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

bq

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

Genera una definizione della tabella esterna, che descrive 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 modificarlo quando aggiorni la tabella.
- CACHE_MODE: specifica se la cache dei metadati viene aggiornata automaticamente o manualmente. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.
  
  Imposta su AUTOMATIC per aggiornare la cache dei metadati a un intervallo definito dal sistema, in genere tra 30 e 60 minuti.
  
  Imposta MANUAL se vuoi aggiornare la cache dei metadati in base a una programmazione da te stabilita. 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 contenente i dati della 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 ulteriori informazioni, consulta Supporto dei caratteri jolly per gli URI Cloud Storage.
  
  Puoi specificare più bucket per l'opzione uris fornendo più percorsi.
  
  Gli esempi seguenti 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 ulteriori informazioni 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.
Aggiorna la tabella utilizzando la nuova definizione della 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 per poter essere utilizzati dall'operazione. Per ulteriori informazioni sulle considerazioni relative alla memorizzazione nella cache dei metadati, consulta Memorizzazione nella cache dei metadati per il rendimento.
  
  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 dato 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 precedenti a questa data, 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

Esegui query su tabelle BigLake ed esterne

Dopo aver creato una tabella BigLake, puoi eseguire query utilizzando la sintassi GoogleSQL, come se fosse una tabella BigQuery standard. Ad esempio, SELECT field1, field2 FROM mydataset.my_cloud_storage_table;.

Limitazioni

BigQuery supporta l'esecuzione di query solo sulle tabelle v1 del lettore Delta Lake.
L'integrazione di Hudi e BigQuery funziona solo per le tabelle copy-on-write partizionate in stile Hive.

Passaggi successivi

Scopri di più sull'utilizzo di SQL in BigQuery.
Scopri di più sulle tabelle BigLake.
Scopri di più sulle quote di BigQuery.