Tabellenoptionen konfigurieren

Durch Konfigurieren von Tabellenoptionen können Sie die BigQuery-Schreibinteroperabilität oder die Tabellenverwaltung (automatische Speicheroptimierung) für Ihre Apache Iceberg-Tabellen im Lakehouse-Laufzeitkatalog aktivieren. Diese Optionen dienen als Grundeinstellungen, die die Möglichkeiten für Vorgänge in der Tabelle erweitern.

Durch Konfigurieren bestimmter Tabelleneigenschaften können Sie die Schreibinteroperabilität mit BigQuery DML oder die automatische Tabellenverwaltung (Speicheroptimierung) aktivieren.

Wenn Sie Tabellen im Lakehouse-Laufzeitkatalog verwenden, ist es hilfreich, die verschiedenen Tabellentypen und ihre Aktivierungsfunktionen zu kennen. Weitere Informationen zur Verwendung von Apache Iceberg-Tabellen finden Sie unter Übersicht über Apache Iceberg Tabellen.

Hinweis

  1. Prüfen Sie, ob die Abrechnung für Ihr Google Cloud Projekt aktiviert ist.

  2. Aktivieren Sie die BigLake API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Informationen zum Zuweisen von Rollen.

    API aktivieren

  3. Richten Sie den Lakehouse-Laufzeit katalog mit dem Apache Iceberg REST-Katalogendpunkt ein.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt und Ihren Speicher-Bucket zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren von Tabellenoptionen benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Hinweise zur Konfiguration

Beachten Sie beim Konfigurieren von Tabellenoptionen die folgenden Anforderungen und Standardverhaltensweisen:

Unterstützte Iceberg-Tabellen

Es werden nur Apache Iceberg V2-Tabellen (GA) und V3-Tabellen (Vorschau) unterstützt. Iceberg V1-Tabellen werden nicht unterstützt. Informationen zum Upgrade vorhandener V1-Tabellen finden Sie unter Iceberg V1 Tabellen auf V2 upgraden.

Anforderung für die Bereitstellung von Anmeldedaten

Wenn Sie die automatische Tabellenverwaltung aktivieren möchten, muss die Bereitstellung von Anmeldedaten im Lakehouse-Laufzeitkatalog auf Katalogebene aktiviert sein. Hintergrundjobs für die Tabellenverwaltung verwenden das Dienstkonto für die Bereitstellung von Anmeldedaten, um sich zu authentifizieren und zugrunde liegende Speicherdatendateien zu aktualisieren.

BigQuery DML aktivieren

Durch Aktivieren von BigQuery-Datenbearbeitungssprachenanweisungen (Data Manipulation Language, DML) wird die Schreibinteroperabilität von BigQuery für Apache Iceberg-Tabellen ermöglicht, die mit Open-Source-Engines erstellt wurden.

Zu den unterstützten Anweisungen gehören INSERT, UPDATE, DELETE und MERGE, sowie Standard-DDL Anweisungen wie CREATE TABLE, ALTER TABLE und DROP TABLE, mit Ausnahme der Anweisungen, die in Apache Iceberg-Tabellen in BigQuery nicht unterstützt werden.

BigQuery DML für neue Tabellen aktivieren

Wenn Sie eine Tabelle erstellen aus BigQuery, sind BigQuery DML und die automatische Tabellenverwaltung standardmäßig aktiviert. Wenn Sie eine Tabelle aus Open-Source-Engines erstellen, konfigurieren Sie die Tabelleneigenschaft gcp.biglake.bigquery-dml.enabled = true mit der DDL-Syntax Ihrer Engine.

Beispiel in Spark SQL :

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

BigQuery DML für vorhandene Tabellen aktivieren

Wenn Sie BigQuery DML für eine vorhandene Tabelle aktivieren möchten, aktualisieren Sie die Tabelle eigenschaft.

Beispiel in Spark SQL :

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

BigQuery DML deaktivieren

Wenn Sie BigQuery DML deaktivieren, ist die Tabelle für BigQuery schreibgeschützt und die automatische Tabellenverwaltung wird beendet.

Beispiel in Spark SQL :

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

Tabellenverwaltung aktivieren

Die Tabellenverwaltung automatisiert Hintergrundprozesse, um den Speicher zu optimieren und den Lebenszyklus von Daten und Metadaten zu verwalten, z. B. Komprimierung und Garbage Collection.

Mit der Tabellenverwaltung können Sie die folgenden Vorgänge ausführen:

  • Ablauf von Snapshots und Garbage Collection:Mit dem Ablauf von Snapshots werden die Aufbewahrung und das Löschen von Daten- und Metadatendateien aus Tabellen-Snapshots verwaltet. Dieser Vorgang wird nach jeder Datenänderung automatisch im Hintergrund ausgeführt. Snapshots laufen basierend auf den vom Nutzer konfigurierten Iceberg-Tabelleneigenschaften history.expire.max-snapshot-age-ms und history.expire.min-snapshots-to-keep in der Tabelle ab. Dabei werden abgelaufene Snapshot-Einträge aus der Datei metadata.json entfernt und anschließend werden Daten- und Metadatendateien gelöscht, die nur zu den abgelaufenen Snapshots gehörten und nicht mehr von aktiven Snapshots referenziert werden.

    • Einschränkung: Der Ablauf von Snapshots und die zugehörige Garbage Collection werden übersprungen, wenn die Tabelle Tags oder Branches verwendet. Weitere Informationen finden Sie unter Beschränkungen.

    • Einschränkung: Das Entfernen verwaister Dateien wird nicht von der automatischen Tabellenverwaltung übernommen. Weitere Informationen finden Sie unter Beschränkungen.

  • Zusammenführen (Komprimierung) : Mit dem Zusammenführen wird die Form der Daten beibehalten, indem kleine Dateien zu größeren Dateien zusammengeführt werden. Dieser Vorgang wird nach jeder Datenänderung automatisch im Hintergrund ausgeführt. Dateien werden für die Komprimierung ausgewählt, wenn ihre durchschnittliche unkomprimierte Größe weniger als 50% der Zieldateigröße von 256 MB beträgt. Bei jedem Zusammenführungsvorgang wird ein neuer Tabellen-Snapshot erstellt. Zusammenführungsjobs werden in der Regel nach allen laufenden DML Vorgängen ausgeführt und wiederholt. Um jedoch eine unbegrenzte Verzögerung der Speicher optimierung zu vermeiden, wird alle 24 Stunden ein Zusammenführungsjob erzwungen, wenn Daten für die Zusammenführung infrage kommen.

  • Jobs für die Tabellenverwaltung beobachten:Alle Hintergrundjobs für die Tabellenverwaltung werden in der Ansicht INFORMATION_SCHEMA.JOBS von BigQuery protokolliert. Sie können diese Ansicht abfragen, um diese Vorgänge zu verfolgen, ähnlich wie bei der Beobachtung anderer BigQuery-Jobs. Weitere Informationen zum Abfragen von Job informationen finden Sie unter Jobs zur Speicheroptimierung von Iceberg-Tabellen abrufen.

    Die Häufigkeit von Jobs für die Tabellenverwaltung hängt direkt mit der Aktivität der Datenänderung zusammen. Häufige kleine Einfügungen oder Aktualisierungen lösen häufigere Hintergrundaufgaben aus. Wenn keine Schreibvorgänge in die Tabelle erfolgen, kann es vorkommen, dass keine Hintergrundjobs ausgeführt werden. Umgekehrt können hohe Schreibvolumina zu einer stärkeren Jobaktivität in INFORMATION_SCHEMA führen.

Tabellenverwaltung für neue Tabellen aktivieren

Wenn Sie eine Tabelle erstellen aus BigQuery, sind DML und die automatische Tabellenverwaltung standardmäßig aktiviert. Wenn Sie eine Tabelle aus Open-Source-Engines erstellen, konfigurieren Sie die Eigenschaft gcp.biglake.table-management.enabled. Wenn Sie die Tabellenverwaltung aktivieren, wird automatisch BigQuery DML aktiviert, falls es noch nicht aktiviert ist.

Beispiel in Spark SQL :

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

Tabellenverwaltung für vorhandene Tabellen aktivieren

Wenn Sie die Tabellenverwaltung für eine vorhandene Tabelle aktivieren möchten, aktualisieren Sie die Tabelleneigenschaft.

Beispiel in Spark SQL :

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

Tabellenverwaltung deaktivieren

Wenn Sie die Tabellenverwaltung deaktivieren, werden keine zukünftigen Hintergrundjobs zur Optimierung mehr in die Warteschlange gestellt. Aktive Jobs werden jedoch abgeschlossen. Durch Deaktivieren der Tabellenverwaltung wird BigQuery DML nicht deaktiviert.

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);

BigQuery 

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");

Beschränkungen

Zu den Beschränkungen für verwaltete Funktionen (z. B. BigQuery-Schreibinteroperabilität und automatische Tabellenverwaltung) gehören:

Allgemeine Beschränkungen

  • Verwaltete Funktionen werden nur für Apache Iceberg-Tabellen unterstützt, die im Lakehouse-Laufzeitkatalog mit dem Apache Iceberg REST-Katalogendpunkt erstellt wurden.
  • Alle vorhandenen Beschränkungen für Apache Iceberg-Tabellen, die von BigQuery verwaltet werden, gelten für Vorgänge, bei denen verwaltete Funktionen aktiviert sind.
  • Verwaltete Funktionen werden für Tabellen mit Apache Iceberg-Formatversion 3 nicht unterstützt. Nur Tabellen mit Formatversion 2 (Iceberg v2-Spezifikation) können für verwaltete Funktionen aktiviert werden.
  • Verwaltete Funktionen werden für Tabellen mit erweiterter Partitionierung nicht unterstützt, z. B. Partitionierung nach STRING, Partitionierung mit mehreren Spalten oder Partitionierungsevolution.
  • Verwaltete Funktionen werden für Tabellen nicht unterstützt, die mit Sortierreihenfolgen konfiguriert sind (z. B. mit der Prozedur WRITE ORDER BY oder durch Festlegen von write.distribution.mode = range).
  • Verwaltete Funktionen werden für Iceberg v2-Tabellen im Merge-on-Read-Modus nicht unterstützt. Nur Tabellen, die den Copy-on-Write-Modus für Aktualisierungen, Löschvorgänge und Zusammenführungen verwenden, können für verwaltete Funktionen aktiviert werden.
  • Verwaltete Funktionen unterstützen keine Datendateien, die mit den Codecs gzip, lz4 oder brotli komprimiert wurden (write.parquet.compression.codec). Für Datendateien werden nur die Komprimierungstypen zstd und snappy unterstützt.
  • Verwaltete Funktionen werden für Tabellen nicht unterstützt, wenn das Schema verschachtelte Primärschlüsselkennungen (identifier-field-ids) enthält, die auf verschachtelte Pfade oder Felder in einer Struktur verweisen.
  • Verwaltete Funktionen werden für Tabellen mit benutzerdefinierten Speicherorten für Daten oder Metadaten (write.data.path und write.metadata.path) nicht unterstützt. Der Standardpfad des Cloud Storage-Bucket ist erforderlich, um Daten- und Metadatendateien zu speichern.
  • BigQuery-Clustering wird für Apache Iceberg-Tabellen, die vom Lakehouse-Laufzeitkatalog verwaltet werden, nicht unterstützt.
  • Wenn eine Tabelle mit dem Datentyp NUMERIC in BigQuery erstellt wird, schlagen alle Schemaaktualisierungen von Spark fehl, da Spark NUMERIC als NUMERIC(38,9) liest. Als Problemumgehung können Sie beim Erstellen von Tabellen mit dem NUMERIC Typ in BigQuery die Genauigkeit explizit auf NUMERIC(38,9) festlegen.
  • Bekanntes Problem:Das Löschen einer Spalte in BigQuery mit DDL (ALTER TABLE ... DROP COLUMN) und das anschließende Hinzufügen einer Spalte mit demselben Namen wird nicht unterstützt.

Beschränkungen bei der Zeitreise

  • Wenn die Tabellenverwaltung aktiviert ist, beträgt der maximal empfohlene Wert für die Eigenschaft history.expire.max-snapshot-age-ms 7 Tage.
  • Konfigurationen auf BigQuery-Projekt- oder Dataset-Ebene für die Zeitreise gelten nicht. Nur Iceberg-Tabelleneigenschaften und -Standardwerte sind aktiv.

Beschränkungen bei der Tabellenverwaltung

  • Der Ablauf von Snapshots wird für die gesamte Tabelle übersprungen, wenn die Tabelle Snapshots mit Tags oder Branches enthält. Die mit ALTER... RETAIN x DAYS festgelegte benutzerdefinierte Aufbewahrungsdauer wird ignoriert und alle für die history.expire.max-ref-age-ms Eigenschaft festgelegten Werte werden ignoriert. Open-Source-Engines können weiterhin den Ablauf von Snapshots durchführen.
  • Bei der automatischen Tabellenverwaltung laufen Schemas oder Partitionsspezifikationen nicht ab. Die Datei metadata.json behält den vollständigen Verlauf von Schemas und Partitionsspezifikationen bei, auch wenn keine Snapshots auf diese Schema-IDs verweisen.

  • Verwaiste Dateien, die von BigQuery oder Open-Source-Engines erstellt wurden, werden nicht von der automatischen Tabellenverwaltung bereinigt. Open-Source-Engines können verwaiste Dateien bereinigen, z. B. mit der Spark Prozedur remove_orphan_files wobei die Option prefix_listing auf true gesetzt ist.

  • Die Zusammenführung unterstützt keine Z-Sortierung und lineare Sortierung. Wenn Ihre Tabelle diese Eigenschaften enthält, wird nicht garantiert, dass das Layout nach der Zusammenführung beibehalten wird. Wenn Ihre Tabellen diese Eigenschaften enthalten, sollten Sie die Tabellenverwaltung nicht aktivieren.

Beschränkungen bei der Partitionierung

  • Beim Erstellen oder Registrieren von Tabellen aus Open-Source-Engines unterstützen verwaltete Funktionen nur die Partitionierung für die Feldtypen DATE, TIMESTAMP und TIMESTAMPTZ mit den Transformationen hour, day, month und year (mit Ausnahme der Transformation hour für DATE-Felder).
  • Verwaltete Funktionen werden für Tabellen mit IDENTITY-Transformationen nicht unterstützt. Nutzer müssen die Transformation explizit angeben.
  • CREATE OR REPLACE -Befehle für Tabellen mit verwalteten Funktionen werden nur unterstützt, wenn sie dieselbe Partitionsspezifikation verwenden. Die folgenden Ersetzungen werden nicht unterstützt:
    • Ersetzen einer nicht partitionierten Tabelle durch eine partitionierte Tabelle.
    • Ersetzen einer partitionierten Tabelle durch eine nicht partitionierte Tabelle.
    • Ersetzen einer partitionierten Tabelle durch eine Tabelle mit einer anderen Partitionsspezifikation.
  • Benutzerdefinierte Namen für Partitionierungsfelder werden nicht unterstützt. Tabellen, die aus Open-Source-Engines erstellt oder registriert wurden, müssen der Standardkonvention für die Benennung von Partitionierungsfeldern der Engine folgen (Anhängen von _ und dem Namen der Transformation, z. B. _hour, _day, _month, oder _year). Für ein Feld mit dem Namen time_date, das die Transformation DAY verwendet, ist der erwartete Wert für das Partitionierungsfeld beispielsweise: json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

Beschränkungen bei benutzerdefinierten Iceberg-Tabelleneigenschaften

Die folgenden Eigenschaften für das Tabellenverhalten können nicht auf andere als die Standardwerte konfiguriert werden, wenn verwaltete Funktionen aktiviert sind. Standardwerte sind fest codiert, wenn eine verwaltete Funktion aktiviert ist:

Attribut Standardwert Details
format-version 2 Verwaltete Funktionen unterstützen nur Iceberg v2-Tabellen.
write.format.default parquet Tabellen unterstützen nur Datendateien im Parquet-Format.
write.data.path table location + /data Der Standardpfad des Cloud Storage-Bucket, der für den Lakehouse REST-Katalog konfiguriert ist, wird zum Schreiben von Datendateien verwendet.
write.metadata.path table location + /metadata Der Standardpfad des Cloud Storage-Bucket, der für den Lakehouse REST-Katalog konfiguriert ist, wird zum Schreiben von Metadatendateien verwendet.
write.delete.mode copy-on-write BigQuery-Schreibvorgänge und Jobs für die Tabellenverwaltung unterstützen nur Copy-on-Write.
write.update.mode copy-on-write BigQuery-Schreibvorgänge und Jobs für die Tabellenverwaltung unterstützen nur Copy-on-Write.
write.merge.mode copy-on-write BigQuery-Schreibvorgänge und Jobs für die Tabellenverwaltung unterstützen nur Copy-on-Write.
write.delete.isolation-level Strenge Konflikterkennung Änderungen, die die Datei metadata.json ändern (einschließlich Datenkonflikte, Metadatenkonflikte, Phantomlesevorgänge oder nicht konfliktierende gleichzeitige Schreibvorgänge), führen dazu, dass die gleichzeitige Transaktion fehlschlägt und wiederholt wird.
write.update.isolation-level Strenge Konflikterkennung Gleiches Verhalten wie bei write.delete.isolation-level.
write.merge.isolation-level Strenge Konflikterkennung Gleiches Verhalten wie bei write.delete.isolation-level.

Die folgenden Eigenschaften können beim Erstellen oder Ändern von Tabellen aus Open-Source-Engines konfiguriert werden:

Attribut Standardwert Details
write.parquet.compression-codec zstd BigQuery-Schreibvorgänge und Speicheroptimierung unterstützen nur die Komprimierungsformate zstd und snappy. Andere Komprimierungsformate wie gzip, brotli und lz4 werden nicht unterstützt.
write.metadata.compression-codec null Kann auf null oder gzip konfiguriert werden.
history.expire.max-snapshot-age-ms 432000000 (5 Tage) Kann auf eine beliebige positive Ganzzahl konfiguriert werden. Bei aktivierter Tabellenverwaltung werden jedoch bis zu 7 Tage (604800000 ms) empfohlen. Bei Jobs für die Tabellenverwaltung werden Snapshots gelöscht, die älter als die angegebene Dauer sind.
history.expire.min-snapshots-to-keep 1 Kann auf eine beliebige positive Ganzzahl konfiguriert werden. Bei Jobs für die Tabellenverwaltung wird mindestens diese Anzahl von Snapshots beibehalten.

Andere Apache Iceberg-Schreibattribute wie write.target-file-size-bytes und write.parquet.page-size-bytes können über Open-Source-Engines konfiguriert werden. BigQuery-Schreibvorgänge und Jobs für die Tabellenverwaltung halten sich jedoch möglicherweise nicht daran.

Nächste Schritte