Tabellenoptionen konfigurieren

Durch das 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 die Konfiguration 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 Opt-in-Funktionen 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, falls sie noch nicht aktiviert ist.

    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-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 Speicher-Bucket zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren von Tabellenoptionen benötigen:

  • Tabelleneigenschaften im Credential Vending Mode konfigurieren: BigLake Editor (roles/biglake.editor): das Projekt
  • Tabelleneigenschaften 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.

Konfigurationsaspekte

Beachten Sie die folgenden Anforderungen und Standardverhalten, wenn Sie Tabellenoptionen konfigurieren:

Unterstützte Iceberg-Tabellen

Es werden nur Apache Iceberg-Tabellen der Version 2 (GA) und Version 3 (Vorschau) unterstützt. Iceberg V1-Tabellen werden nicht unterstützt. Informationen zum Aktualisieren vorhandener V1-Tabellen finden Sie unter Iceberg-V1-Tabellen auf V2 aktualisieren.

Anforderung für die Bereitstellung von Anmeldedaten

Wenn Sie die automatische Tabellenverwaltung aktivieren möchten, muss für Ihren Lakehouse-Laufzeitkatalog credential vending auf Katalogebene aktiviert sein. Hintergrundjobs für die Tabellenverwaltung verwenden das Konto des Credential Vending Service, um die zugrunde liegenden Speicherdatendateien zu authentifizieren und zu aktualisieren.

BigQuery-DML aktivieren

Wenn Sie BigQuery-Datenbearbeitungssprache (DML)-Anweisungen aktivieren, können Sie Daten aus BigQuery in Apache Iceberg-Tabellen schreiben, 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 in BigQuery erstellen, sind BigQuery DML und die automatische 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 für 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 Tabelleneigenschaft.

Beispiel für 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 automatische Tabellenverwaltung wird beendet.

Beispiel für 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 folgende Vorgänge ausführen:

  • Ablauf von Snapshots und automatische Speicherbereinigung:Der Ablauf von Snapshots steuert die Aufbewahrung und das Löschen von Daten- und Metadatendateien aus Tabellen-Snapshots. Dies geschieht automatisch im Hintergrund nach jeder Datenänderung. Snapshots laufen basierend auf den nutzerkonfigurierten Iceberg-Tabelleneigenschaften history.expire.max-snapshot-age-ms und history.expire.min-snapshots-to-keep für die Tabelle ab. Dabei werden abgelaufene Snapshot-Einträge entfernt, indem eine weitere Snapshot-Definition erstellt wird, die in einer neuen Metadatendatei manifestiert wird, die keine Verweise auf die entfernten Snapshots mehr enthält.

    • Einschränkung: Das Ablaufen von Snapshots und die zugehörige automatische Speicherbereinigung werden übersprungen, wenn in der Tabelle Tags oder Branches verwendet werden. Weitere Informationen finden Sie unter Einschränkungen.

    • Einschränkung: Das Entfernen verwaister Dateien wird nicht durch die automatische Tabellenverwaltung abgedeckt. Weitere Informationen finden Sie unter Einschränkungen.

  • Zusammenführen (Kompaktierung): Beim Zusammenführen wird die Form der Daten beibehalten, indem kleine Dateien in größere Dateien zusammengeführt werden. Die Zusammenführung 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ührungs-Vorgang wird ein neuer Tabellensnapshot erstellt. Zusammenführungsjobs werden in der Regel nach allen laufenden DML-Vorgängen wiederholt. Um jedoch zu verhindern, dass die Speicheroptimierung auf unbestimmte Zeit nicht ausgeführt wird, wird alle 24 Stunden ein Zusammenführungsjob erzwungen, wenn Daten für die Zusammenführung infrage kommen.

  • Jobs zur Verwaltung von Monitoring-Tabellen:Alle Hintergrundjobs zur Tabellenverwaltung werden in der BigQuery-Ansicht INFORMATION_SCHEMA.JOBS 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 Iceberg-Speicheroptimierungsjobs abrufen.

    Die Häufigkeit von Tabellenverwaltungsjobs hängt direkt mit der Datenänderungsaktivität 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 kann ein hohes Schreibvolumen zu einer stärker sichtbaren Jobaktivität in INFORMATION_SCHEMA führen.

Tabellenverwaltung für neue Tabellen aktivieren

Wenn Sie eine Tabelle aus BigQuery erstellen, sind DML und die automatische 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, sofern dies noch nicht geschehen ist.

Beispiel für 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.

Beispiel für 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 Hintergrundoptimierungsjobs mehr in die Warteschlange gestellt. Aktive Jobs werden jedoch abgeschlossen. Wenn Sie die Tabellenverwaltung deaktivieren, wird die BigQuery-Datenbearbeitungssprache (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

Einschränkungen für verwaltete Funktionen (z. B. BigQuery-Schreibvorgänge und automatische Tabellenverwaltung):

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 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 im Format Version 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 der Prozedur 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öschvorgänge und Zusammenführungen verwenden, können für verwaltete Funktionen aktiviert werden.
  • Für verwaltete Funktionen werden keine Datendateien unterstützt, 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. Für Daten- und Metadatendateien ist der Standardspeicherort für Cloud Storage-Bucket erforderlich.
  • 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 NUMERIC in Spark als NUMERIC(38,9) gelesen wird. Als Workaround 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 sofortige erneute 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 Property history.expire.max-snapshot-age-ms 7 Tage.
  • Konfigurationen auf BigQuery-Projekt- oder ‑Datasetebene für Time Travel 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 das Attribut history.expire.max-ref-age-ms festgelegten Werte werden ignoriert. Open-Source-Engines können weiterhin Snapshots löschen.
  • Bei der automatischen Tabellenverwaltung laufen Schemas oder Partitionsspezifikationen nicht ab. In der Datei metadata.json wird der vollständige Verlauf von Schemas und Partitionsspezifikationen beibehalten, auch wenn keine Snapshots auf diese Schema-IDs verweisen.

  • Von BigQuery oder Open-Source-Engines erstellte verwaiste Dateien werden nicht durch die automatische 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 festgelegt ist.

  • Die Funktion „Coalesce“ unterstützt keine Z-Reihenfolge und lineare Sortierung. Wenn Ihre Tabelle diese Eigenschaften enthält, ist nicht garantiert, dass das Layout nach dem Zusammenführen beibehalten wird. Wenn Ihre Tabellen diese Attribute 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 Partitionierungen für die Feldtypen DATE, DATETIME und TIMESTAMP mit den Transformationen hour, day, month und year (mit Ausnahme der hour-Transformation für DATE-Felder) sowie INTEGER-Feldtypen 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.
    • Eine partitionierte Tabelle wird durch eine nicht partitionierte Tabelle ersetzt.
    • Ersetzen einer partitionierten Tabelle durch eine Tabelle mit einer anderen Partitionierungsspezifikation.
  • Benutzerdefinierte Namen für Partitionsfelder werden nicht unterstützt. Für Tabellen, die mit Open-Source-Engines erstellt oder registriert wurden, muss die Standardbenennungskonvention für das Partitionsfeld der Engine eingehalten werden. Dabei wird _ und der Name der Transformation angehängt, 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 des Partitionsfelds 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 Werte 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 Für Tabellen werden nur Datendateien im Parquet-Format unterstützt.
write.data.path table location + /data Der für den Apache Iceberg REST-Katalogendpunkt konfigurierte Standardpfad für Cloud Storage-Bucket wird zum Schreiben von Datendateien verwendet.
write.metadata.path table location + /metadata Der für den Apache Iceberg REST-Katalog-Endpunkt konfigurierte Standardpfad für den Cloud Storage-Bucket wird zum Schreiben von Metadatendateien verwendet.
write.delete.mode copy-on-write Für BigQuery-Schreibvorgänge und Tabellenverwaltungsjobs wird nur „Copy-on-Write“ unterstützt.
write.update.mode copy-on-write Für BigQuery-Schreibvorgänge und Tabellenverwaltungsjobs wird nur „Copy-on-Write“ unterstützt.
write.merge.mode copy-on-write Für BigQuery-Schreibvorgänge und Tabellenverwaltungsjobs wird nur „Copy-on-Write“ unterstützt.
write.delete.isolation-level Strenge Konflikterkennung Änderungen, die die Datei metadata.json modifizieren (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 Strenge Konflikterkennung Das Verhalten ist dasselbe wie bei write.delete.isolation-level.
write.merge.isolation-level Strenge Konflikterkennung Gleiches Verhalten wie bei 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 Die Optimierung von BigQuery-Schreibvorgängen und ‑Speicher unterstützt 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. Wenn die Tabellenverwaltung aktiviert ist, wird jedoch ein Wert von bis zu 7 Tagen (604.800.000 ms) empfohlen. Bei Jobs zur 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 zur Tabellenverwaltung 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 ihnen jedoch möglicherweise nicht.

Nächste Schritte