Creazione tabelle BigLake di Apache Iceberg

Con BigLake, puoi accedere alle tabelle Iceberg con controllo dell'accesso più granulare. Per farlo, devi prima creare una tabella BigLake Iceberg.

Iceberg è un formato di tabelle open source che supporta tabelle di dati nell'ordine dei petabyte. La specifica aperta di Iceberg consente di eseguire più motori di query su una singola copia dei dati archiviati in un archivio di oggetti.

In qualità di amministratore BigQuery, puoi applicare controllo dell'accesso a livello di riga e colonna, incluso il mascheramento dei dati nelle tabelle. Per informazioni su come configurare il controllo dell'accesso dell'accesso a livello di tabella, consulta Configurare i criteri di controllo dell'accesso dell'accesso. I criteri di accesso alle tabelle vengono applicati anche quando utilizzi l'API BigQuery Storage come origine dati per la tabella in Dataproc e Spark serverless. Le tabelle BigLake forniscono integrazioni aggiuntive con altri servizi BigQuery. Per un elenco completo delle integrazioni disponibili, consulta Introduzione alle tabelle BigLake.

Puoi creare tabelle BigLake di Iceberg nei seguenti modi:

  • Con BigLake Metastore (consigliato). BigLake Metastore è un catalogo personalizzato di Iceberg. L'utilizzo di BigLake Metastore è il metodo consigliato perché consente la sincronizzazione delle tabelle tra carichi di lavoro Spark e BigQuery. A questo scopo, puoi utilizzare una stored procedure BigQuery per Apache Spark per inizializzare BigLake Metastore e creare la tabella BigLake Iceberg. Tuttavia, per gli aggiornamenti dello schema è comunque necessario eseguire una query di aggiornamento in BigQuery. Per un elenco completo delle limitazioni, consulta la sezione Limitazioni.

  • Con il file JSON dei metadati di Iceberg. Se utilizzi un file di metadati JSON Iceberg, devi aggiornare manualmente il file di metadati più recente ogni volta che vengono eseguiti aggiornamenti della tabella. Per evitarlo, utilizza BigLake Metastore. Puoi utilizzare una stored procedure BigQuery per Apache Spark per creare tabelle BigLake di Iceberg che fanno riferimento a un file di metadati Iceberg.

Prima di iniziare

Ruoli obbligatori

Per assicurarti che il chiamante dell'API BigLake disponga delle autorizzazioni necessarie per creare una tabella BigLake, chiedi all'amministratore di concedere al chiamante dell'API BigLake i seguenti ruoli IAM sul progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per creare una tabella BigLake. Per visualizzare le autorizzazioni esatte necessarie, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per creare una tabella BigLake, sono necessarie le seguenti autorizzazioni:

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

L'amministratore potrebbe anche essere in grado di concedere al chiamante dell'API BigLake queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Inoltre, per consentire agli utenti BigQuery di eseguire query sulla tabella, l'account di servizio associato alla connessione deve disporre del ruolo Visualizzatore BigLake (roles/biglake.viewer) e dell'accesso al bucket Cloud Storage contenente i dati.

Per creare tabelle BigLake Iceberg con BigLake Metastore, il chiamante dell'API BigLake cambia. Devi concedere all'account di servizio Dataproc o Spark l'accesso al bucket Cloud Storage che contiene i dati:

Creazione di tabelle con BigLake Metastore

Consigliamo di creare le tabelle Iceberg BigLake con BigLake Metastore. Puoi usare Apache Spark per creare queste tabelle. Un modo conveniente per farlo è utilizzare le procedure archiviate di BigQuery per Spark, seguendo questi passaggi:

  1. Vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nel riquadro Explorer, fai clic sulla connessione nel progetto che hai utilizzato per creare la risorsa di connessione.

  3. Per creare una stored procedure per Spark, fai clic su Crea stored procedure.

  4. Nell'editor query, modifica il codice campione per inizializzare BigLake Metastore e creare una tabella BigLake di Iceberg utilizzando l'istruzione CREATE PROCEDURE che viene visualizzata:

     # Creates a stored procedure that initializes BLMS and database.
 # Creates a table in the database and populates a few rows of data.
 CREATE OR REPLACE PROCEDURE iceberg_demo.iceberg_setup_3_3 ()
 WITH CONNECTION `PROCEDURE_CONNECTION_PROJECT_ID.PROCEDURE_CONNECTION_REGION.PROCEDURE_CONNECTION_ID`
 OPTIONS(engine="SPARK",
 jar_uris=["gs://spark-lib/biglake/biglake-catalog-iceberg1.2.0-0.1.0-with-dependencies.jar"],
 properties=[
 ("spark.jars.packages","org.apache.iceberg:iceberg-spark-runtime-3.3_2.12:1.2.0"),
 ("spark.sql.catalog.CATALOG", "org.apache.iceberg.spark.SparkCatalog"),
 ("spark.sql.catalog.CATALOG.catalog-impl", "org.apache.iceberg.gcp.biglake.BigLakeCatalog"),
 ("spark.sql.catalog.CATALOG.hms_uri: HMS_URI")
 ("spark.sql.catalog.CATALOG.gcp_project", "PROJECT_ID"),
 ("spark.sql.catalog.CATALOG.gcp_location", "LOCATION"),
 ("spark.sql.catalog.CATALOG.blms_catalog", "CATALOG"),
 ("spark.sql.catalog.CATALOG.warehouse", "DATA_WAREHOUSE_URI")
 ]
 )
 LANGUAGE PYTHON AS R'''
 from pyspark.sql import SparkSession

 spark = SparkSession \
   .builder \
   .appName("BigLake Iceberg Example") \
   .enableHiveSupport() \
   .getOrCreate()

 spark.sql("CREATE NAMESPACE IF NOT EXISTS CATALOG;")
 spark.sql("CREATE DATABASE IF NOT EXISTS CATALOG.CATALOG_DB;")
 spark.sql("DROP TABLE IF EXISTS CATALOG.CATALOG_DB.CATALOG_TABLE;")

 /* Create a BigLake Metastore table and a BigQuery Iceberg table. */
 spark.sql("CREATE TABLE IF NOT EXISTS CATALOG.CATALOG_DB.CATALOG_TABLE (id bigint, demo_name string)
           USING iceberg
           TBLPROPERTIES(bq_table='BQ_DATASET.BQ_TABLE', bq_connection='TABLE_CONNECTION_PROJECT_ID.TABLE_CONNECTION_REGION.TABLE_CONNECTION_ID');
           ")

 /* Copy a Hive Metastore table to BigLake Metastore. Can be used together with
    TBLPROPERTIES `bq_table` to create a BigQuery Iceberg table. */
 spark.sql("CREATE TABLE CATALOG.CATALOG_DB.CATALOG_TABLE (id bigint, demo_name string)
            USING iceberg
            TBLPROPERTIES(hms_table='HMS_DB.HMS_TABLE');")
 ''';

    Sostituisci quanto segue:

    • PROCEDURE_CONNECTION_PROJECT_ID: il progetto che contiene la connessione per l'esecuzione delle procedure Spark, ad esempio myproject.

    • PROCEDURE_CONNECTION_REGION: la regione che contiene la connessione per eseguire le procedure Spark, ad esempio us.

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

      Quando visualizza 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.

    • CATALOG: il nome del catalogo Iceberg da creare per BigLake Metastore.

      Il valore predefinito è iceberg.

    • HMS_URI: se vuoi copiare le tabelle Hive Metastore esistenti in BigLake Metastore, specifica un URI Hive Metastore.

      Ad esempio, thrift://localhost:9083.

    • PROJECT_ID: l'ID progetto in cui vuoi creare l'istanza Metastore di BigLake.

      Anche le tabelle BigLake Iceberg vengono create nello stesso progetto.

    • LOCATION: la località in cui vuoi creare l'istanza Metastore BigLake.

      BigQuery può accedere solo alle istanze BigLake Metastore archiviate nella stessa località.

    • DATA_WAREHOUSE_URI: l'URI del bucket Cloud Storage che hai creato per archiviare i metadati e i file di dati Iceberg.

      Ad esempio, gs://mybucket/iceberg-warehouse.

    • CATALOG_DB: il nome del database che vuoi creare in BigLake Metastore.

      Questo database è equivalente al set di dati BigQuery che conterrà la tabella BigLake di Iceberg.

    • CATALOG_TABLE: il nome della tabella che vuoi creare in BigLake Metastore.

      Questa è l'equivalente della tabella BigLake di Iceberg che vuoi creare.

    • BQ_DATASET: il set di dati BigQuery che contiene la tabella BigLake di Iceberg.

    • BQ_TABLE: la tabella BigLake Iceberg che vuoi creare.

    • TABLE_CONNECTION_PROJECT_ID: il progetto che contiene la connessione per creare la tabella BigLake, ad esempio myproject.

    • TABLE_CONNECTION_REGION: la regione che contiene la connessione per creare la tabella BigLake, ad esempio us.

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

      Quando visualizza 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.

      L'account di servizio associato alla connessione deve avere roles/biglake.viewer per consentire agli utenti BigQuery di eseguire query sulla tabella.

    • HMS_DB: se vuoi copiare tabelle Hive Metastore esistenti in BigLake Metastore, specifica un database Hive Metastore.

    • HMS_TABLE: se vuoi copiare tabelle Hive Metastore esistenti, specifica una tabella Hive Metastore.

    Per informazioni sulle configurazioni del catalogo Iceberg, consulta Cataloghi Spark.

  5. Per eseguire la stored procedure, fai clic su Esegui. Per maggiori informazioni, consulta Chiamare la stored procedure Spark. viene creata una tabella BigLake Iceberg in BigQuery.

Creare tabelle con un file di metadati

Puoi creare tabelle BigLake di Iceberg con un file di metadati JSON. Tuttavia, questo non è il metodo consigliato perché devi aggiornare manualmente l'URI del file di metadati JSON per mantenere aggiornata la tabella BigLake. Se l'URI non viene mantenuto aggiornato, le query in BigQuery possono avere esito negativo o fornire risultati diversi rispetto ad altri motori di query che utilizzano direttamente un catalogo Iceberg. Per evitare che ciò accada, fai riferimento a un'istanza Metastore BigLake quando crei una tabella BigLake di Iceberg.

I file di metadati della tabella Iceberg vengono creati nel bucket Cloud Storage specificato quando crei una tabella Iceberg utilizzando Spark.

Seleziona una delle seguenti opzioni:

SQL

Utilizza l'istruzione CREATE EXTERNAL TABLE. L'esempio seguente crea una tabella BigLake denominata myexternal-table:

  CREATE EXTERNAL TABLE myexternal-table
  WITH CONNECTION `myproject.us.myconnection`
  OPTIONS (
         format = 'ICEBERG',
         uris = ["gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json"]
   )

Sostituisci il valore uris con il file di metadati JSON più recente per uno snapshot della tabella specifico.

Puoi abilitare l'opzione Richiedi filtro di partizionamento impostando il flag require_partition_filter.

bq

In un ambiente a riga di comando, utilizza il comando bq mk --table con il decorator @connection per specificare la connessione da utilizzare alla fine del parametro --external_table_definition. Per abilitare il filtro di partizionamento richiesto, utilizza --require_partition_filter. 

bq mk 

    --table 

    --external_table_definition=TABLE_FORMAT=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID 

    PROJECT_ID:DATASET.EXTERNAL_TABLE

Sostituisci quanto segue:

  • TABLE_FORMAT: il formato della tabella che vuoi creare

    In questo caso, ICEBERG.

  • URI: il file di metadati JSON più recente per uno snapshot specifico della tabella.

    Ad esempio, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json.

  • CONNECTION_PROJECT_ID: il progetto che contiene la connessione per creare la tabella BigLake, ad esempio myproject

  • CONNECTION_REGION: la regione che contiene la connessione per creare la tabella BigLake, ad esempio us

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

    Quando visualizza 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

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

    Ad esempio, mydataset.

  • EXTERNAL_TABLE: il nome della tabella che vuoi creare

    Ad esempio, mytable.

Aggiornamento metadati tabella

Se utilizzi un file di metadati JSON per creare tabelle BigLake di Iceberg, aggiorna la definizione della tabella utilizzando i metadati della tabella più recenti. Per aggiornare lo schema o il file dei metadati, seleziona una delle seguenti opzioni:

bq

  1. Crea un file di definizione della tabella:

    bq mkdef --source_format=ICEBERG \
"URI" > TABLE_DEFINITION_FILE

  2. Utilizza il comando bq update con il flag --autodetect_schema:

    bq update --autodetect_schema --external_table_definition=TABLE_DEFINITION_FILE
PROJECT_ID:DATASET.TABLE

    Sostituisci quanto segue:

    • URI: l'URI Cloud Storage con il file di metadati JSON più recente

      Ad esempio, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

    • TABLE_DEFINITION_FILE: nome del file contenente lo schema della tabella

    • PROJECT_ID: l'ID progetto contenente la tabella da aggiornare

    • DATASET: il set di dati contenente la tabella da aggiornare

    • TABLE: la tabella da aggiornare

API

Utilizza il metodo tables.patch con la proprietà autodetect_schema impostata su true:

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/TABLE?autodetect_schema=true

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto contenente la tabella da aggiornare
  • DATASET: il set di dati contenente la tabella da aggiornare
  • TABLE: la tabella da aggiornare

Nel corpo della richiesta, specifica i valori aggiornati per i seguenti campi:

{
     "externalDataConfiguration": {
      "sourceFormat": "ICEBERG",
      "sourceUris": [
        "URI"
      ]
    },
    "schema": null
  }'

Sostituisci URI con il file di metadati Iceberg più recente. Ad esempio, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

Configura i criteri di controllo dell'accesso

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

Ad esempio, supponiamo di voler 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 il suo 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 maggiori informazioni, consulta la pagina relativa ai dati di Query Iceberg.

Mappatura dei dati

BigQuery converte i tipi di dati Iceberg in tipi di dati BigQuery, come mostrato nella seguente tabella:

Tipo di dati Iceberg Tipo di dati BigQuery
boolean BOOL
int INT64
long INT64
float FLOAT64
double FLOAT64
Decimal(P/S) NUMERIC or BIG_NUMERIC depending on precision
date DATE
time TIME
timestamp DATETIME
timestamptz TIMESTAMP
string STRING
uuid BYTES
fixed(L) BYTES
binary BYTES
list<Type> ARRAY<Type>
struct STRUCT
map<KeyType, ValueType> ARRAY<Struct<key KeyType, value ValueType>>

Limitazioni

Le tabelle BigLake di Iceberg hanno limitazioni per le tabelle BigLake e anche le seguenti limitazioni:

  • La configurazione di copy-on-write è supportata, ma la configurazione di merge-on-read non è supportata. Per ulteriori informazioni, consulta Configurazione di Iceberg.

  • BigQuery supporta l'eliminazione dei manifest utilizzando tutte le funzioni di trasformazione delle partizioni Iceberg, ad eccezione di Bucket. Per informazioni su come eliminare le partizioni, consulta Eseguire query sulle tabelle partizionate. Le query che fanno riferimento alle tabelle BigLake di Iceberg devono contenere i valori letterali nei predicati rispetto alle colonne partizionate.

  • La creazione di tabelle BigLake Iceberg nella regione BigQuery Omni Azure (azure-eastus2) non è supportata.

  • Sono supportati solo i file di dati Apache Parquet.

  • Tutti i file di dati Iceberg devono avere la proprietà field_id impostata nei metadati per associare le colonne allo schema Iceberg. Le tabelle con la proprietà schema.name-mapping.default non sono supportate.

  • Le tabelle Hive di cui è stata eseguita la migrazione alle tabelle Iceberg utilizzando le stored procedure Spark di Iceberg non sono supportate.

  • Se utilizzi BigLake Metastore, si applicano le seguenti limitazioni:

    • BigLake Metastore non è supportato nelle regioni BigQuery Omni.
    • Quando rinomini una tabella, questa deve trovarsi nello stesso database della tabella di origine. Il database della tabella di destinazione deve essere specificato in modo esplicito.
    • Quando esamini una tabella di metadati Iceberg, devi utilizzare un nome di tabella completo. Ad esempio, prod.db.table.history.

Costi

Ti verrà addebitato 1 TB al prezzo delle query on demand (per TB) per 6.250.000 richieste a BigLake Metastore e per 625.000 oggetti archiviati in BigLake Metastore. Le tariffe dei prezzi on demand per le query variano a seconda della regione. Per un numero inferiore di richieste o oggetti, ti verrà addebitata la frazione appropriata di 1 TB.

Ad esempio, se hai inviato 6.250.000 richieste a BigLake Metastore e hai anche archiviato 312.500 oggetti al suo interno, ti verrà addebitato 1,5 TB al prezzo delle query on demand per la regione in cui hai creato l'istanza Metastore BigLake.

Richiedi filtro di partizionamento

Puoi richiedere l'uso di filtri dei predicati attivando l'opzione Richiedi filtro di partizionamento per la tabella Iceberg. Se abiliti questa opzione, i tentativi di eseguire query sulla tabella senza specificare una clausola WHERE in linea con ogni file manifest produrranno il seguente errore:

Cannot query over table project_id.dataset.table without a
filter that can be used for partition elimination.

Ogni file manifest richiede almeno un predicato idoneo per l'eliminazione della partizione.

Puoi abilitare require_partition_filter nei modi seguenti durante la creazione di una tabella Iceberg :

SQL

Utilizza l'istruzione CREATE EXTERNAL TABLE.Nell'esempio seguente viene creata una tabella BigLake denominata TABLE con la richiesta di filtro di partizionamento abilitato:

  CREATE EXTERNAL TABLE TABLE
  WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
  OPTIONS (
         format = 'ICEBERG',
         uris = [URI],
         require_partition_filter = true
   )

Sostituisci quanto segue:

  • TABLE: il nome della tabella che vuoi creare.
  • PROJECT_ID: l'ID progetto contenente la tabella che vuoi creare.
  • REGION: la località in cui vuoi creare la tabella Iceberg.

  • CONNECTION_ID: l'ID connessione. Ad esempio: myconnection.

  • URI: l'URI Cloud Storage con il file di metadati JSON più recente.

    Ad esempio, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

bq

Utilizza il comando bq mk --table con il decorator @connection per specificare la connessione da utilizzare alla fine del parametro --external_table_definition. Usa --require_partition_filter per abilitare il filtro di partizionamento richiesto. L'esempio seguente crea una tabella BigLake denominata TABLE con il filtro di partizione richiesto abilitato: 

bq mk \
    --table \
    --external_table_definition=ICEBERG=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID \
    PROJECT_ID:DATASET.EXTERNAL_TABLE \
    --require_partition_filter

Sostituisci quanto segue:

  • URI: il file di metadati JSON più recente per una specifica istantanea della tabella

    Ad esempio, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json.

  • CONNECTION_PROJECT_ID: il progetto che contiene la connessione per creare la tabella BigLake, ad esempio myproject

  • CONNECTION_REGION: la regione che contiene la connessione per creare la tabella BigLake. Ad esempio: us.

  • CONNECTION_ID: l'ID connessione. Ad esempio: myconnection.

    Quando visualizza 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

  • DATASET: il nome del database BigQuery

    un set di dati contenente la tabella da aggiornare. Ad esempio, mydataset.

  • EXTERNAL_TABLE: il nome della tabella che vuoi creare

    Ad esempio, mytable.

Puoi anche aggiornare la tabella Iceberg per abilitare il filtro di partizionamento richiesto.

Se non abiliti l'opzione Richiedi filtro di partizionamento quando crei la tabella partizionata, puoi aggiornare la tabella per aggiungere l'opzione.

bq

Utilizza il comando bq update e fornisci il flag --require_partition_filter.

Ad esempio:

Per aggiornare mypartitionedtable in mydataset nel progetto predefinito, inserisci:

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

Passaggi successivi