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 grundlegende Einstellungen, 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 Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (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-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.

Konfigurationshinweise

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 automatische Speicherbereinigung.

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

  • Ablauf von Snapshots und automatische Speicherbereinigung: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 entfernt, indem eine weitere Snapshot-Definition erstellt wird, die durch eine neue Metadatendatei manifestiert wird, die keine Verweise mehr 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 Branches verwendet. Weitere Informationen finden Sie unter Einschränkungen.

    • Einschränkung: Das Entfernen verwaister Dateien wird nicht von der automatischen Tabellenverwaltung übernommen. Weitere Informationen finden Sie unter Einschrä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ühren 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 das Zusammenführen 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 Sie andere BigQuery-Jobs beobachten. 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. Es kann vorkommen, dass es keine Hintergrundjobs gibt, wenn keine Schreibvorgänge in der Tabelle ausgeführt werden. Umgekehrt können hohe Schreibvolumen 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 BigQuery DML automatisch aktiviert, falls sie 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 Einschrä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 Einschrä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 nicht für Tabellen mit erweiterter Partitionierung unterstützt, z. B. Partitionierung nach STRING, Partitionierung mit mehreren Spalten oder Partitionierungsevolution.
  • Verwaltete Funktionen werden nicht für Tabellen 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 nicht für Iceberg v2-Tabellen im Merge-on-Read-Modus 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 nicht für Tabellen unterstützt, wenn das Schema verschachtelte Primärschlüssel-IDs (identifier-field-ids) enthält, die auf verschachtelte Pfade oder Felder in einer Struktur verweisen.
  • Verwaltete Funktionen werden nicht für Tabellen mit benutzerdefinierten Speicherorten für Daten oder Metadaten (write.data.path und write.metadata.path) 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.

Einschrä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 werden nicht angewendet. Nur Iceberg-Tabelleneigenschaften 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. 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 ausfü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.

  • Das Zusammenführen unterstützt keine Z-Sortierung und lineare Sortierung. Wenn Ihre Tabelle diese Eigenschaften enthält, wird das Layout nach dem Zusammenführen möglicherweise nicht beibehalten. Wenn Ihre Tabellen diese Eigenschaften enthalten, sollten Sie die Tabellenverwaltung nicht aktivieren.

Einschränkungen bei der Partitionierung

  • Beim Erstellen oder Registrieren von Tabellen aus Open-Source-Engines werden bei verwalteten Funktionen nur die Partitionierung für die Feldtypen DATE, DATETIME und TIMESTAMP mit den Transformationen hour, day, month und year (mit Ausnahme der Transformation hour für DATE-Felder) sowie für die Feldtypen INTEGER unterstützt.
  • 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 }

Einschrä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 für den Lakehouse REST-Katalog konfigurierte Standardpfad des Cloud Storage-Bucket wird verwendet, um Datendateien zu schreiben.
write.metadata.path table location + /metadata Der für den Lakehouse REST-Katalog konfigurierte Standardpfad des Cloud Storage-Bucket wird verwendet, um Metadatendateien zu schreiben.
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, wird aber bei aktivierter Tabellenverwaltung auf 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, aber BigQuery-Schreibvorgänge und Jobs für die Tabellenverwaltung halten sich möglicherweise nicht daran.

Nächste Schritte