Creazione tabelle Apache Iceberg BigLake

Con BigLake puoi accedere alle tabelle di Iceberg con un controllo dell'accesso più granulare. Per farlo, devi per prima cosa creerai una tabella BigLake Iceberg.

Iceberg è un formato di tabella open source che supporta dati su scala petabyte tabelle. La specifica aperta Iceberg ti 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 colonna, inclusi i dati di mascheramento sulle tabelle. Per informazioni su come configurare il controllo dell'accesso nella a livello di tabella, consulta Configurare i criteri di controllo dell'accesso. Tavolo vengono applicate forzatamente anche quando utilizzi l'API BigQuery Storage come origine dati per la tabella in Dataproc Spark serverless. Le tabelle BigLake forniscono integrazioni aggiuntive con altri servizi BigQuery. Per un elenco completo delle integrazioni, consulta Introduzione alle tabelle BigLake.

Puoi creare tabelle BigLake Iceberg nei seguenti modi modi:

  • Con BigLake Metastore (consigliato per Google Cloud). BigLake Metastore è un catalogo Iceberg personalizzato. Utilizzare BigLake Metastore è il metodo consigliato per Google Cloud perché consente la sincronizzazione delle tabelle tra Spark e BigQuery carichi di lavoro con scale out impegnativi. Per farlo, puoi utilizzare una stored procedure BigQuery per Apache Spark per inizializzare BigLake Metastore e creare il tavolo BigLake Iceberg. Tuttavia, lo schema si aggiorna devi comunque eseguire una query di aggiornamento in BigQuery.

  • Con AWS Glue Data Catalog (consigliato per AWS). AWS Glue è il metodo consigliato per AWS perché è un repository di metadati centralizzato in cui si definiscono la struttura e la località dei dati archiviati in vari servizi AWS come il rilevamento automatico degli schemi e l'integrazione con gli strumenti di analisi AWS.

  • Con file di metadati JSON Iceberg (consigliato per Azure). Se utilizzi un file di metadati JSON Iceberg, devi aggiornare manualmente la versione più recente ogni volta che ci sono aggiornamenti della tabella. Puoi usare un modello di archiviazione BigQuery per Apache Spark per creare Iceberg BigLake che fanno riferimento a un file di metadati Iceberg. Per evitare che ciò accada, puoi utilizzare BigLake Metastore per Google Cloud o AWS Glue Data Catalog per AWS.

    Per un elenco completo delle limitazioni, vedi Limitazioni.

Prima di iniziare

Ruoli obbligatori

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

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

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

Autorizzazioni obbligatorie

Per creare una tabella BigLake sono necessarie le autorizzazioni seguenti:

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

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

Inoltre, per consentire agli utenti di BigQuery di eseguire query sulla tabella, l'account di servizio associato alla connessione deve avere il visualizzatore BigLake Ruolo (roles/biglake.viewer) e accesso al bucket Cloud Storage che contiene quei dati.

Per creare tabelle BigLake Iceberg con BigLake Metastore, il chiamante del BigLake modifiche all'API. Devi concedere a Dataproc o Accesso dell'account di servizio Spark al bucket Cloud Storage che contengono questi dati:

Crea tabelle con BigLake Metastore

Ti consigliamo di creare Iceberg BigLake con BigLake Metastore. Puoi utilizzare Apache Spark per creare queste tabelle. Un modo pratico per farlo è usare BigQuery archiviate per Spark procedendo nel seguente modo:

  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 l'inizializzazione BigLake Metastore e la creazione di un Tabella BigLake Iceberg utilizzando Dichiarazione CREATE PROCEDURE che viene visualizzato:

     # 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 eseguire Procedure Spark, ad esempio myproject.

    • PROCEDURE_CONNECTION_REGION: la regione contiene la connessione per eseguire Spark di archiviazione, ad esempio us.

    • PROCEDURE_CONNECTION_ID: il valore ID connessione, ad esempio myconnection.

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

    • CATALOG: il nome del Catalogo Iceberg per cui creare Metastore BigLake

      Il valore predefinito è iceberg.

    • HMS_URI: se vuoi copiare l'Hive esistente Tabelle Metastore in BigLake Metastore, specifica un Hive URI Metastore.

      Ad esempio, thrift://localhost:9083.

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

      Anche le tabelle BigLake Iceberg vengono create nello stesso progetto.

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

      BigQuery può accedere solo di istanze BigLake Metastore archiviate nello stesso in ogni località.

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

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

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

      Questo database è equivalente alla classe set di dati BigQuery che conterrà Tabella BigLake Iceberg.

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

      Questa tabella è equivalente alla tabella BigLake di Iceberg che vuoi creare.

    • BQ_DATASET: il set di dati BigQuery per contenere la tabella BigLake Iceberg.

    • BQ_TABLE: il BigLake di Iceberg che vuoi creare.

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

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

    • TABLE_CONNECTION_ID: il valore ID connessione, ad esempio myconnection.

      Quando visualizzi i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima dell'ID connessione completo visualizzato in Connection ID (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 di BigQuery di eseguire query sulla tabella.

    • HMS_DB: se vuoi copiare l'Hive esistente Tabelle Metastore in BigLake Metastore, specifica un Hive Database Metastore.

    • HMS_TABLE: se vuoi copiare l'Hive esistente Tabelle Metastore in BigLake Metastore, specifica un Hive Tabella Metastore.

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

  5. Per eseguire la stored procedure, fai clic su Esegui. Per ulteriori informazioni, vedi Chiama la stored procedure di Spark. viene creata una tabella BigLake Iceberg in BigQuery.

Creare tabelle con un file di metadati

Puoi creare tabelle BigLake Iceberg con 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 a oggi, le query in BigQuery possono non riuscire o fornire risultati da altri motori di query che utilizzano direttamente un catalogo Iceberg. Per evitare che ciò accada, consulta un metastore BigLake un'istanza quando crei un'istanza Tabella BigLake Iceberg.

File di metadati della tabella Iceberg vengono creati nel bucket Cloud Storage specificato durante la creazione di una tabella Iceberg utilizzando Spark.

Seleziona una delle seguenti opzioni:

SQL

Utilizza l'istruzione CREATE EXTERNAL TABLE. L'esempio seguente crea un 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 il filtro di partizione richiesto 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 obbligatorio, 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 di tabella specifico.

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

    L'URI può anche puntare a una località cloud esterna; ad esempio Amazon S3 o Azure Blob Storage.

    • Esempio per AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Esempio per Azure: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

  • CONNECTION_PROJECT_ID: il progetto che contiene la connessione a crea la tabella BigLake, ad esempio myproject

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

  • CONNECTION_ID: la connessione della tabella ID, ad esempio myconnection

    Quando visualizzi i dettagli della connessione nella console Google Cloud, l'ID connessione è il valore nell'ultima dell'ID connessione completo visualizzato in Connection ID (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 nel

    Ad esempio, mydataset.

  • EXTERNAL_TABLE: il nome della tabella che vuoi creare

    Ad esempio, mytable.

Aggiornamento metadati tabella

Se usi un file di metadati JSON per creare tabelle BigLake Iceberg, quindi aggiorna la definizione della tabella con i metadati più recenti. Per aggiornare schema o del 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. Usa 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 più recente file di metadati JSON

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

    • TABLE_DEFINITION_FILE: il nome del file contenente schema della tabella

    • PROJECT_ID: l'ID progetto contenente la tabella che voglio aggiornare

    • DATASET: il set di dati contenente la tabella che voglio aggiornare

    • TABLE: la tabella che vuoi 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 che contiene la tabella che voglio aggiornare
  • DATASET: il set di dati contenente la tabella che voglio aggiornare
  • TABLE: la tabella che vuoi aggiornare

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

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

Sostituisci URI con l'Iceberg più recente dei metadati. 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 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 il suo accesso alle righe dove 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 query seguente:

SELECT * FROM projectid.mydataset.mytable;

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

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

Esegui query su tabelle BigLake

Per ulteriori informazioni, vedi Eseguire query sui dati di Iceberg.

Mappatura dei dati

BigQuery converte i tipi di dati Iceberg in BigQuery tipi di dati, come illustrato 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

I tavoli BigLake Iceberg hanno una tabella BigLake limitazioni e anche quanto segue limitazioni:

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

  • BigQuery supporta l'eliminazione dei manifest utilizzando tutte le partizioni di Iceberg di trasformazione tranne Bucket. Per informazioni su come eliminare le partizioni, consulta Eseguire query partizionate. Query fare riferimento alle tabelle Iceberg BigLake devono contenere valori letterali nei predicati rispetto alle colonne partizionate.

  • Sono supportati solo i file di dati Apache Parquet.

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

    • BigLake Metastore non è supportato in BigQuery Omni regioni.
    • Quando rinomini una tabella, la tabella di destinazione deve trovarsi nello stesso database di la tabella di origine. È necessario specificare il database della tabella di destinazione in modo esplicito.
    • Durante l'ispezione di una tabella dei metadati di Iceberg, devi utilizzare un nome completo di tabella. Ad esempio, prod.db.table.history.

Costi

Ti verrà addebitato 1 TB il giorno prezzi on demand (per TB) delle query per ogni 6.250.000 richieste a BigLake Metastore e per ogni 625.000 oggetti archiviati in BigLake Metastore. On demand i prezzi delle query variano in base alla regione. Per un numero inferiore di richieste o oggetti, ti verrà addebitata la frazione appropriata di 1 TB.

Ad esempio, se hai effettuato 6.250.000 richieste a BigLake Metastore oltre a 312.500 oggetti archiviati al suo interno,ti verranno addebitati 1, 5 TB tariffa on demand per le query per la regione in cui hai creato Istanza BigLake Metastore.

Richiedi filtro di partizionamento

Puoi richiedere l'utilizzo di filtri per i predicati attivando il metodo richiede filtro di partizionamento per la tabella Iceberg. Se abiliti questa opzione, tenta di eseguire una query sulla tabella senza specificare un La clausola WHERE che si allinea con ogni file manifest genererà 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 adatto per l'eliminazione della partizione.

Puoi attivare require_partition_filter nei seguenti modi, mentre creando una tabella Iceberg :

SQL

Utilizza l'istruzione CREATE EXTERNAL TABLE.L'esempio seguente crea una tabella BigLake denominata TABLE con Richiedi l'attivazione del filtro di partizionamento:

  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 da 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 più recente del file di metadati JSON.

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

    L'URI può anche puntare a una località cloud esterna; ad esempio Amazon S3 o Azure Blob Storage.

    • Esempio per AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Esempio per Azure: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/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 obbligatorio. L'esempio seguente crea una tabella BigLake denominata TABLE con l'opzione Richiedi filtro di partizione 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 uno snapshot di tabella specifico

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

    L'URI può anche puntare a una località cloud esterna; ad esempio Amazon S3 o Azure Blob Storage.

    • Esempio per AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Esempio per Azure: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

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

  • CONNECTION_REGION: la regione in cui contiene la connessione per creare BigLake . 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 dell'ID connessione completo visualizzato in Connection ID (ID connessione), ad esempio projects/myproject/locations/connection_location/connections/myconnection

  • DATASET: il nome del cluster BigQuery

    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 partizione obbligatorio.

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

bq

Usa 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