Iceberg-Optionen

Diese Seite listet die Optionen der iceberg-Erweiterung auf: die von den Iceberg-Funktionen akzeptierten Parameter, die Optionen der Anweisungen ATTACH und CREATE SECRET zum Verbinden mit einem Katalog sowie die globalen Einstellungen.

ATTACH-Optionen

Damit ein Iceberg-Katalog (nicht nur eine einzelne Tabelle) dem System bekannt ist, müssen Sie die Anweisung ATTACH verwenden. Die an ATTACH übergebenen Optionen sind in Kategorien unterteilt:

Parameter	Typ	Standard	Beschreibung
ENDPOINT	VARCHAR	NULL	URL-Endpunkt für die Kommunikation mit dem REST Catalog.
DEFAULT_SCHEMA	VARCHAR	NULL	Das Standard-Schema (Namespace), das für den angehängten Katalog verwendet wird.
ACCESS_DELEGATION_MODE	VARCHAR	vended_credentials	Zugriffsdelegationsmodus. Zulässige Werte sind vended_credentials und none.
SUPPORT_NESTED_NAMESPACES	BOOLEAN	false	Auf true setzen für Kataloge, die verschachtelte Namespaces unterstützen.
STAGE_CREATE_TABLES	BOOLEAN	true	Steuert, ob DuckDB gestuftes CREATE TABLE verwendet. Für Kataloge deaktivieren, die kein gestuftes Anlegen von Tabellen unterstützen.
DISABLE_MULTI_TABLE_COMMIT	BOOLEAN	false	Deaktiviert den Endpunkt für Multi-Table-Transaktionen/Commit. Für Kataloge aktivieren, die diesen Endpunkt ablehnen.
SKIP_CREATE_TABLE_METADATA_UPDATES	BOOLEAN	false	Überspringt nachfolgende Metadatenaktualisierungen nach nicht gestuftem CREATE TABLE. Für Kataloge aktivieren, die Metadaten beim Anlegen der Tabelle vollständig initialisieren und nachfolgende Aktualisierungen ablehnen.
REMOVE_FILES_ON_DELETE	BOOLEAN	true	Wenn deaktiviert, werden Dateien (Daten und Metadaten), die während der Transaktion erzeugt wurden, bei ROLLBACK oder Wiederholungen von COMMIT nicht aufgeräumt.
PURGE_REQUESTED	BOOLEAN	false	Sendet den Parameter PurgeRequested beim Löschen einer Tabelle.
ENCODE_ENTIRE_PREFIX	BOOLEAN	false	URL-kodiert das gesamte Pfadpräfix bei der Kommunikation mit dem Katalog.
MAX_TABLE_STALENESS	INTERVAL	NULL	Verhindert unnötige Anfragen an den Iceberg REST Catalog. Akzeptiert menschenlesbare Intervallzeichenketten wie 10 minutes, 30 seconds oder 1 year.

Einige Parameter aktivieren andere; siehe die Liste der zugehörigen zusätzlichen Parameter unter dieser Tabelle.

Parameter	Typ	Standard	Zulässige Optionen	Beschreibung
ENDPOINT_TYPE	VARCHAR	NULL	S3_TABLES, GLUE	Eine gängige Kennung eines Iceberg-Katalogtyps, setzt bestimmte Standardparameter.
AUTHORIZATION_TYPE	VARCHAR	OAUTH2	OAUTH2, SIGV4	Die Autorisierungsschicht des anzuhängenden Iceberg-Katalogs.

Endpunkttyp

Für häufig verwendete Iceberg-Kataloganbieter kann der Parameter ENDPOINT_TYPE genutzt werden, um bestimmte Parameter auf Standardwerte zu setzen. Er dient als Kurzform für die Verbindung mit diesen Katalogen.

S3 Tables

Die Parameter, die durch den ENDPOINT_TYPE S3_TABLES gesetzt werden, sind:

Parameter	Wert
AUTHORIZATION_TYPE	SIGV4
SIGV4_REGION	Der Abschnitt REGION des ARN, der als ATTACH-Pfad angegeben wird.
ENDPOINT	⟨REGION⟩.s3tables.amazonaws.com/iceberg{:.language-sql .highlight}
REMOVE_FILES_ON_DELETE	false (sofern nicht explizit gesetzt)
STAGE_CREATE_TABLES	false (sofern nicht explizit gesetzt)
PURGE_REQUESTED	true (sofern nicht explizit gesetzt)

Glue

Bei Verwendung des ENDPOINT_TYPE GLUE muss der Parameter SECRET vom Typ VARCHAR auf den Pfad eines vorhandenen S3/AWS-SECRET gesetzt werden. Die Parameter, die durch den ENDPOINT_TYPE GLUE gesetzt werden, sind:

Parameter	Wert
AUTHORIZATION_TYPE	SIGV4
ENDPOINT	⟨REGION⟩.glue.amazonaws.com/iceberg{:.language-sql .highlight} unter Verwendung der Region aus dem gefundenen SECRET
REMOVE_FILES_ON_DELETE	false (sofern nicht explizit gesetzt)
STAGE_CREATE_TABLES	false (sofern nicht explizit gesetzt)
PURGE_REQUESTED	true (sofern nicht explizit gesetzt)

Autorisierung

Um die Autorisierungsschicht für die Verbindung mit einem Iceberg REST Catalog zu konfigurieren, müssen Sie den Parameter AUTHORIZATION_TYPE übergeben. Dies sind die unterstützten Optionen:

OAUTH2-Autorisierungsoptionen

Die zusätzlichen Parameter, die bereitgestellt werden können, wenn AUTHORIZATION_TYPE auf OAUTH2 gesetzt ist, sind die folgenden.

Parameter	Typ	Standard	Beschreibung
SECRET	VARCHAR	NULL	Der Pfad zu einem SECRET vom Typ ICEBERG, aus dem CLIENT_ID und CLIENT_SECRET gelesen werden.
CLIENT_ID	VARCHAR	NULL	CLIENT_ID, der in der OAuth2-Autorisierungsanfrage verwendet wird.
CLIENT_SECRET	VARCHAR	NULL	CLIENT_SECRET, der in der OAuth2-Autorisierungsanfrage verwendet wird.
OAUTH2_SERVER_URI	VARCHAR	NULL	Der Endpunkt des zu kontaktierenden OAuth2-Servers.
OAUTH2_GRANT_TYPE	VARCHAR	NULL	Der zu verwendende grant_type.
OAUTH2_SCOPE	VARCHAR	NULL	Der zu verwendende scope.
DEFAULT_REGION	VARCHAR	NULL	Die Region, die vended credentials hinzugefügt wird, falls der Katalog keine liefert.
TOKEN	VARCHAR	NULL	Das Bearer-Token, das statt einer Anfrage an den Server verwendet wird. (deaktiviert das Aktualisieren)

SIGV4-Autorisierungsoptionen

Die zusätzlichen Parameter, die bereitgestellt werden können, wenn AUTHORIZATION_TYPE auf SIGV4 gesetzt ist, sind die folgenden.

Parameter	Typ	Standard	Beschreibung
SECRET	VARCHAR	NULL	Das S3- oder AWS-SECRET, das zum Signieren verwendet wird.
SIGV4_SERVICE	VARCHAR	NULL	Überschreibt den SERVICE zum Signieren von Anfragen, andernfalls wird er aus dem Parameter ENDPOINT abgeleitet.
SIGV4_REGION	VARCHAR	NULL	Überschreibt die REGION zum Signieren von Anfragen, andernfalls wird sie aus dem Parameter ENDPOINT abgeleitet.
EXTRA_HTTP_HEADERS	MAP(VARCHAR, VARCHAR)	NULL	Zusätzliche Header (Schlüssel-Wert), die mit der Signieranfrage gesendet werden.

ICEBERG-SECRET-Optionen

Jede im Abschnitt ATTACH-Optionen und seinen Unterabschnitten genannte Option kann beim Anlegen eines ICEBERG-SECRET verwendet werden. Wenn ein solches ICEBERG-SECRET existiert, kann es von nachfolgenden ATTACH-Anweisungen abgeleitet oder explizit über die ATTACH-Option SECRET angegeben werden.

Arbeiten mit einem angehängten Katalog

Sobald ein Katalog angehängt ist, können Sie den vollständigen Satz von Lese- und Schreiboperationen auf seinen Tabellen ausführen:

• Lesen und Metadaten: SELECT, Time Travel mit der Klausel AT sowie die Funktionen iceberg_metadata, iceberg_snapshots und Statistikfunktionen. Siehe die Referenz der Funktionen und Einstellungen.
• Schreiben: CREATE/DROP SCHEMA und TABLE, Partitionierung, INSERT, UPDATE, DELETE, MERGE INTO, ALTER TABLE, Tabelleneigenschaften und COPY FROM DATABASE. Siehe Schreiben nach Iceberg.

Metadatenfunktionen akzeptieren einen vollständig qualifizierten Tabellennamen, z. B.:

SELECT * FROM iceberg_snapshots(my_catalog.default.t);

Einstellungen

Einstellung	Typ	Standard	Beschreibung
unsafe_enable_version_guessing	BOOLEAN	false	Erlaubt der Erweiterung, die neueste Metadatenversion zu raten, wenn keine Version oder Hint-Datei angegeben ist.
iceberg_default_format_version	INTEGER	2	Setzt die standardmäßige format_version, die beim Anlegen einer neuen Tabelle verwendet wird.
iceberg_unsafe_skip_puffin_verification	BOOLEAN	false	Beim Lesen von V3 Deletion Vectors die Puffin-Dateiprüfung überspringen (für Kompatibilität mit Dateien älterer Versionen).

Scan-Optionen

Die folgenden Parameter können an iceberg_scan, iceberg_column_stats, iceberg_metadata, iceberg_partition_stats, iceberg_snapshots übergeben werden:

Parameter	Typ	Standard	Beschreibung
allow_moved_paths	BOOLEAN	false	Erlaubt das Scannen verschobener Iceberg-Tabellen
metadata_compression_codec	VARCHAR	''	Behandelt Metadatendateien als gzip, wenn auf 'gzip' gesetzt
snapshot_from_id	UBIGINT	NULL	Auf den Snapshot mit einer bestimmten id zugreifen
snapshot_from_timestamp	TIMESTAMP	NULL	Auf den Snapshot mit einem bestimmten timestamp zugreifen
version	VARCHAR	'?'	Liefert eine explizite Versionszeichenkette, Hint-Datei oder Raten
version_name_format	VARCHAR	'v%s%s.metadata.json,%s%s.metadata.json'	Steuert, wie Versionen in Metadatendateinamen umgewandelt werden

iceberg_snapshots nimmt weder allow_moved_paths, snapshot_from_id noch snapshot_from_timestamp als Parameter entgegen.

Metadatenversionen auswählen

Standardmäßig sucht die iceberg-Erweiterung nach einer Datei version-hint.text, um die passende Metadatenversion zu bestimmen. Das kann überschrieben werden, indem den Funktionen der iceberg-Erweiterung über den Parameter version explizit eine Versionsnummer übergeben wird:

SELECT *
FROM iceberg_snapshots(
    'data/iceberg/lineitem_iceberg',
    version = '1'
);

Standardmäßig suchen iceberg-Funktionen sowohl nach Dateien v{version}.metadata.json als auch {version}.metadata.json, bzw. nach v{version}.gz.metadata.json und {version}.gz.metadata.json, wenn metadata_compression_codec = 'gzip' angegeben ist. Andere Kompressionscodecs werden nicht unterstützt.

Wenn über den Parameter version eine beliebige Textdatei angegeben wird, wird sie geöffnet und als Version-Hint-Datei behandelt:

SELECT *
FROM iceberg_snapshots(
    'data/iceberg/lineitem_iceberg',
    version = 'version-hint.txt'
);

Die iceberg-Erweiterung öffnet diese Datei und verwendet den gesamten Inhalt der Datei als angegebene Versionsnummer. Beachten Sie, dass der gesamte Inhalt der Datei version-hint.txt als wörtlicher Versionsname behandelt wird, ohne Kodierung, Escaping oder Trimming. Dazu gehören alle Leerzeichen oder unsicheren Zeichen, die explizit formatiert in Dateinamen der unten beschriebenen Logik übernommen werden.

Arbeiten mit alternativen Metadaten-Namenskonventionen

Die iceberg-Erweiterung kann unterschiedliche Metadaten-Namenskonventionen verarbeiten, indem sie über den Parameter version_name_format als kommagetrennte Liste von Formatzeichenketten angegeben werden. Jede Formatzeichenkette muss zwei Parameter %s enthalten. Der erste ist die Position der Versionsnummer im Metadatendateinamen, der zweite die Position der Dateiendung, die durch metadata_compression_codec vorgegeben wird. Das oben beschriebene Verhalten wird durch den Standardwert "v%s%s.metadata.gz,%s%smetadata.gz bereitgestellt. Wenn Sie eine anders benannte Metadatendatei hätten, z. B. rev-2.metadata.json.gz, kann die Tabelle mit der folgenden Anweisung gelesen werden:

SELECT *
FROM iceberg_snapshots(
    'data/iceberg/alternative_metadata_gz_naming',
    version = '2',
    version_name_format = 'rev-%s.metadata.json%s',
    metadata_compression_codec = 'gzip'
);

Metadatenversionen „raten“

Standardmäßig muss entweder eine Tabellenversionsnummer oder eine Datei version-hint.text angegeben werden, damit die iceberg-Erweiterung eine Tabelle lesen kann. Das wird typischerweise von einem externen Datenkatalog bereitgestellt. Falls keines von beiden vorhanden ist, kann die iceberg-Erweiterung versuchen, die neueste Version zu raten, indem ? als Parameter version übergeben wird:

SELECT count(*)
FROM iceberg_scan(
    'data/iceberg/lineitem_iceberg_no_hint',
    version = '?',
    allow_moved_paths = true
);

Als „neueste“ Version gilt der Dateiname, der beim Sortieren der Dateinamen lexikografisch am größten ist. Kollationen werden nicht berücksichtigt. Dieses Verhalten ist standardmäßig nicht aktiviert, da es potenziell ACID-Garantien verletzen kann. Es kann aktiviert werden, indem unsafe_enable_version_guessing auf true gesetzt wird. Wenn das gesetzt ist, versuchen iceberg-Funktionen standardmäßig, die neueste Version zu raten, bevor sie fehlschlagen.

SET unsafe_enable_version_guessing = true;
SELECT count(*)
FROM iceberg_scan(
    'data/iceberg/lineitem_iceberg_no_hint',
    allow_moved_paths = true
);