Tabellenoptionen konfigurieren

Sie können Tabellenoptionen im Lakehouse-Laufzeitkatalog verwenden, um die BigQuery-DML-Schreibinteroperabilität und die Tabellenverwaltung (automatische Speicheroptimierung) für Ihre Apache Iceberg-Tabellen zu aktivieren.

Weitere Informationen zu unterstützten Tabellenformaten und Opt-in-Funktionen im Lakehouse-Laufzeitkatalog finden Sie unter Tabellentypen vergleichen und Ü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, falls sie noch nicht aktiviert ist.

    Erforderliche Rollen zum Aktivieren von APIs

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    API aktivieren

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

Erforderliche Rollen

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

  • Tabelleneigenschaften im Modus für die Bereitstellung von Anmeldedaten konfigurieren: BigLake-Bearbeiter (roles/biglake.editor) – das Projekt
  • Tabellenattribute im Modus ohne Bereitstellung von Anmeldedaten konfigurieren:
    • BigLake Editor (roles/biglake.editor) – das Projekt
    • Storage Object User (roles/storage.objectUser) – der Cloud Storage-Bucket

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.

Überlegungen zur Konfiguration

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

Unterstützte Iceberg-Tabellen

Obwohl der Lakehouse-Laufzeitkatalog Apache Iceberg V2- (GA) und V3-Tabellen (Vorabversion) unterstützt, werden verwaltete Funktionen (BigQuery-DML und Tabellenverwaltung) nur für Iceberg V2-Tabellen unterstützt. Iceberg V1-Tabellen werden nicht unterstützt. Informationen zum Upgrade vorhandener V1-Tabellen finden Sie unter Iceberg-V1-Tabellen auf V2 aktualisieren.

Anforderung für die Bereitstellung von Anmeldedaten

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

BigQuery-DML aktivieren

Wenn Sie BigQuery-Datenbearbeitungssprache (DML)-Anweisungen aktivieren, wird die Schreibinteroperabilität von BigQuery für Apache Iceberg-Tabellen freigeschaltet, die mit Open-Source-Engines erstellt wurden.

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

BigQuery-DML für neue Tabellen aktivieren

Wenn Sie eine Tabelle in BigQuery erstellen, sind BigQuery-DML und die Tabellenverwaltung standardmäßig aktiviert. Wenn Sie eine Tabelle aus Open-Source-Engines erstellen, konfigurieren Sie das Tabellenattribut 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 das Tabellenattribut.

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, wird die Tabelle für BigQuery schreibgeschützt und die 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. durch Komprimierung und automatische Speicherbereinigung.

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

  • Snapshot-Ablauf und automatische Speicherbereinigung: Der Snapshot-Ablauf verwaltet die Aufbewahrung und das Löschen von Daten- und Metadatendateien aus Tabellen-Snapshots. Dies geschieht nach jeder Datenänderung automatisch im Hintergrund. Snapshots laufen gemäß den vom Nutzer konfigurierten Iceberg-Tabellenattributen history.expire.max-snapshot-age-ms und history.expire.min-snapshots-to-keep für die Tabelle ab. Abgelaufene Snapshot-Einträge werden entfernt, indem eine zusätzliche Snapshot-Definition in einer neuen Metadatendatei erstellt wird, die keine Verweise auf die entfernten Snapshots enthält.

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

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

  • Zusammenführen (Kompaktierung): Das Zusammenführen ist für die Beibehaltung der Form der Daten verantwortlich, indem kleine Dateien zu größeren Dateien zusammengeführt werden. Coalesce 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. Coalesce-Jobs werden in der Regel nach allen laufenden DML-Vorgängen zurückgestellt und wiederholt. Um jedoch eine unbegrenzte Verzögerung der Speicheroptimierung zu verhindern, wird alle 24 Stunden ein Zusammenführungsjob erzwungen, wenn Daten für die Zusammenführung infrage kommen.

  • Jobs zur Tabellenverwaltung überwachen: Alle Hintergrundjobs zur Tabellenverwaltung werden in der Ansicht INFORMATION_SCHEMA.JOBS in BigQuery protokolliert. Sie können diese Ansicht abfragen, um diese Vorgänge zu verfolgen, ähnlich wie Sie andere BigQuery-Jobs überwachen. Weitere Informationen zum Abfragen von Jobinformationen finden Sie unter Jobs zur Iceberg-Speicheroptimierung abrufen.

    Die Häufigkeit von Tabellenverwaltungsjobs korreliert direkt mit der Datenänderungsaktivität. Häufige kleine Einfügungen oder Aktualisierungen lösen häufigere Hintergrundaufgaben aus. Wenn keine Schreibvorgänge in der Tabelle stattfinden, kann es vorkommen, dass keine Hintergrundjobs ausgeführt werden. Umgekehrt kann ein hohes Schreibvolumen zu mehr sichtbarer Jobaktivität in INFORMATION_SCHEMA führen.

Wählen Sie aus, ob die Tabellenverwaltung aktiviert werden soll.

Für Apache Iceberg-Tabellen, die vom Lakehouse-Laufzeitkatalog verwaltet und über den Apache Iceberg REST-Katalogendpunkt bereitgestellt werden, können Sie entweder die Tabellenverwaltung aktivieren oder die Tabellenwartung (z. B. Komprimierung und Ablauf von Snapshots) selbst mit Open-Source- oder Drittanbieter-Engines verwalten.

Aktivieren Sie die Tabellenverwaltung (gcp.biglake.table-management.enabled = true), wenn alle folgenden Bedingungen erfüllt sind:

  • Sie möchten eine automatisierte Hintergrunddateikomprimierung (Zusammenführung) und einen automatisierten Snapshot-Ablauf sowie eine automatische Speicherbereinigung nach DML- oder Open-Source-Streaming-Schreibvorgängen.

  • Ihr Katalog verwendet den Modus für die Bereitstellung von Anmeldedaten.

  • Ein Snapshot-Aufbewahrungs- und Zeitreisefenster von bis zu 7 Tagen (standardmäßig 5 Tage) erfüllt Ihre Anforderungen.

  • Ihre Tabelle erfüllt die Anforderungen für verwaltete Funktionen (siehe Einschränkungen).

Lassen Sie die Tabellenverwaltung deaktiviert (Standardeinstellung für Tabellen, die aus Open-Source-Engines erstellt wurden, oder legen Sie gcp.biglake.table-management.enabled = false fest) und verwalten Sie die Tabellenwartung selbst, wenn eine der folgenden Bedingungen zutrifft:

  • Sie führen benutzerdefinierte Komprimierungs- oder Wartungsverfahren in Open-Source-Engines wie Apache Spark, Apache Flink oder Trino aus, insbesondere wenn Ihre Tabellen auf Z-Order- oder linearen Sortierlayouts basieren, die von der Zusammenführung nicht beibehalten werden.

  • Ihre Tabellen verwenden Apache Iceberg-Snapshot-Tags oder -Zweige (was dazu führt, dass die Tabellenverwaltung den Ablauf von Snapshots überspringt) oder erfordern eine Snapshot-Aufbewahrung und Zeitreisen von mehr als 7 Tagen.

  • Ihr Katalog verwendet Endnutzer-Anmeldedaten (direkte IAM-Berechtigungen für Cloud Storage) anstelle des Modus für die Bereitstellung von Anmeldedaten.

  • Ihre Tabellen verwenden Features, die von verwalteten Funktionen nicht unterstützt werden (in diesem Fall müssen sowohl die Tabellenverwaltung als auch BigQuery-DML deaktiviert bleiben), z. B. Apache Iceberg-Formatversion 3, Merge-on-Read-Modus, Partitionierung mit mehreren Spalten oder IDENTITY oder benutzerdefinierte Speicherpfade für Daten und Metadaten. Eine vollständige Liste der nicht unterstützten Funktionen finden Sie unter Einschränkungen.

Tabellenverwaltung für neue Tabellen aktivieren

Wenn Sie eine Tabelle in BigQuery erstellen, sind DML und Tabellenverwaltung standardmäßig aktiviert. Wenn Sie eine Tabelle aus Open-Source-Engines erstellen, konfigurieren Sie das Attribut gcp.biglake.table-management.enabled. Wenn Sie die Tabellenverwaltung aktivieren, wird BigQuery-DML automatisch aktiviert, falls dies noch nicht geschehen 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 das Tabellenattribut.

Spark SQL 

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

BigQuery 

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

Tabellenverwaltung deaktivieren

Wenn Sie die Tabellenverwaltung deaktivieren, werden zukünftige Hintergrundoptimierungsjobs nicht mehr in die Warteschlange gestellt. Aktive Jobs werden jedoch abgeschlossen. Wenn Sie die Tabellenverwaltung deaktivieren, 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 Einschränkungen für verwaltete Funktionen (z. B. BigQuery-Schreibinteroperabilität und 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 bestehenden Einschränkungen für von BigQuery verwaltete Apache Iceberg-Tabellen gelten für Vorgänge mit aktivierten verwalteten Funktionen.
  • Verwaltete Funktionen werden für Tabellen mit Apache Iceberg-Formatversion 3 nicht unterstützt. Nur Tabellen der 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 nach mehreren Spalten oder Partitionsentwicklung.
  • Verwaltete Funktionen werden für Tabellen, die mit Sortierreihenfolgen konfiguriert sind (z. B. mit dem Verfahren WRITE ORDER BY oder der Einstellung write.distribution.mode = range), nicht unterstützt.
  • 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öschungen 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 (write.parquet.compression-codec) komprimiert wurden. 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 Daten- oder Metadatenspeicherorten (write.data.path und write.metadata.path) nicht unterstützt. Der Cloud Storage-Standardspeicherort 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 Behelfslösung können Sie beim Erstellen von Tabellen mit dem Typ NUMERIC 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 sofortige Hinzufügen einer Spalte mit demselben Namen wird nicht unterstützt.

Einschränkungen bei Zeitreisen

  • Wenn die Tabellenverwaltung aktiviert ist, beträgt der maximal zulässige Wert für das Attribut history.expire.max-snapshot-age-ms 30 Tage (2592000000 ms) und der maximal empfohlene Wert 7 Tage (604800000 ms). Der maximal zulässige Wert für das Attribut history.expire.min-snapshots-to-keep ist 100.
  • BigQuery-Konfigurationen auf Projektebene oder Dataset-Ebene für Zeitreisen gelten nicht. Nur Iceberg-Tabellenattribute und Standardwerte sind aktiv.

Einschrä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. Benutzerdefinierte Aufbewahrung, die mit ALTER... RETAIN x DAYS festgelegt wurde, wird ignoriert. Alle Werte, die für das Attribut history.expire.max-ref-age-ms festgelegt wurden, werden ignoriert. Open-Source-Engines können weiterhin Snapshot-Abläufe ausführen.
  • Bei der Tabellenverwaltung laufen Schemas oder Partitionsspezifikationen nicht ab. Die Datei metadata.json enthält den vollständigen Verlauf der Schemas und Partitionsspezifikationen, auch wenn keine Snapshots auf diese Schema-IDs verweisen.

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

  • Coalesce unterstützt keine Z-Sortierung und keine lineare Sortierung. Wenn Ihre Tabelle diese Attribute enthält, kann nicht garantiert werden, dass das Layout nach der Ausführung von „coalesce“ beibehalten wird. Wenn Ihre Tabellen diese Attribute enthalten, aktivieren Sie die Tabellenverwaltung nicht.

Einschrä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, DATETIME und TIMESTAMP mit den Transformationen hour, day, month und year (außer der Transformation hour für DATE-Felder) sowie für den Feldtyp INTEGER.
  • Verwaltete Funktionen werden für Tabellen mit IDENTITY-Transformationen nicht unterstützt. Sie 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:
    • Nicht partitionierte Tabelle durch eine partitionierte Tabelle ersetzen.
    • Partitionierte Tabelle durch eine nicht partitionierte Tabelle ersetzen
    • Ersetzen einer partitionierten Tabelle durch eine Tabelle mit einer anderen Partitionierungsspezifikation.
  • Benutzerdefinierte Namen für Partitionsfelder werden nicht unterstützt. Tabellen, die von Open-Source-Engines erstellt oder registriert werden, müssen der Standardnamenskonvention für Partitionsfelder der Engine folgen (Anhängen von _ und dem Transformationsnamen, z. B. _hour, _day, _month oder _year). Für ein Feld mit dem Namen time_date, das die Transformation DAY verwendet, lautet der erwartete Partitionsfeldwert beispielsweise: json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

Einschränkungen bei benutzerdefinierten Iceberg-Tabellenattributen

Die folgenden Eigenschaften für das Tabellenverhalten können nicht auf nicht standardmäßige Werte konfiguriert werden, wenn verwaltete Funktionen aktiviert sind. Standardwerte sind hartcodiert, 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 für den Apache Iceberg REST-Katalogendpunkt konfigurierte Standardpfad des Cloud Storage-Bucket wird zum Schreiben von Datendateien verwendet.
write.metadata.path table location + /metadata Der für den Apache Iceberg REST-Katalogendpunkt konfigurierte Standard-Cloud Storage-Bucket-Pfad wird zum Schreiben von Metadatendateien verwendet.
write.delete.mode copy-on-write BigQuery-Schreibvorgänge und Tabellenverwaltungsjobs unterstützen nur Copy-on-Write.
write.update.mode copy-on-write BigQuery-Schreibvorgänge und Tabellenverwaltungsjobs unterstützen nur Copy-on-Write.
write.merge.mode copy-on-write BigQuery-Schreibvorgänge und Tabellenverwaltungsjobs unterstützen nur Copy-on-Write.
write.delete.isolation-level Strikte Konflikterkennung Änderungen, die die Datei metadata.json ändern (einschließlich Datenkonflikten, Metadatenkonflikten, Phantom-Lesevorgängen oder nicht in Konflikt stehenden gleichzeitigen Schreibvorgängen), führen dazu, dass die gleichzeitige Transaktion fehlschlägt und wiederholt wird.
write.update.isolation-level Strikte Konflikterkennung Gleiches Verhalten wie write.delete.isolation-level.
write.merge.isolation-level Strikte Konflikterkennung Gleiches Verhalten wie write.delete.isolation-level.

Die folgenden Attribute 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 die Speicheroptimierung unterstützen nur die Komprimierungsformate zstd und snappy. Andere Komprimierungsformate (z. B. 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 nicht negative Ganzzahl bis zu 2592000000 (30 Tage) konfiguriert werden, wenn die Tabellenverwaltung aktiviert ist. Empfohlen werden bis zu 7 Tage (604800000 ms). Bei Tabellenverwaltungsjobs werden Snapshots gelöscht, die älter als die angegebene Dauer sind.
history.expire.min-snapshots-to-keep 1 Kann auf eine beliebige nicht negative Ganzzahl bis zu 100 konfiguriert werden, wenn die Tabellenverwaltung aktiviert ist. Bei Tabellenverwaltungsjobs wird mindestens diese Anzahl von Snapshots beibehalten.

Andere Apache Iceberg-Schreibeigenschaften wie write.target-file-size-bytes und write.parquet.page-size-bytes können über Open-Source-Engines konfiguriert werden. BigQuery-Schreibvorgänge und Tabellenverwaltungsjobs entsprechen diesen jedoch möglicherweise nicht.

Nächste Schritte