Iceberg REST Catalogs

Diese Seite behandelt die Verbindung mit Iceberg REST Catalogs: Authentifizierung, den vollständigen Satz der ATTACH-Optionen und Einrichtungsanweisungen für bestimmte Kataloge. Die Grundlagen zum Anhängen und Abfragen eines Katalogs finden Sie unter Katalogverwaltete Tabellen; für Schreiboperationen siehe Schreiben nach Iceberg.

Wenn Sie einen von Amazon verwalteten Iceberg REST Catalog anhängen, folgen Sie bitte den Anweisungen zum Anhängen an Amazon S3 Tables oder Amazon SageMaker Lakehouse.

Für alle anderen Iceberg REST Catalogs können Sie den folgenden Anweisungen folgen. Fragen zu bestimmten Katalogen finden Sie im Abschnitt Beispiele.

Die meisten Iceberg REST Catalogs authentifizieren sich über OAuth2. Sie können den bestehenden DuckDB-Secret-Workflow nutzen, um Anmeldedaten für den OAuth2-Dienst zu speichern.

CREATE SECRET iceberg_secret (
    TYPE iceberg,
    CLIENT_ID '⟨admin⟩',
    CLIENT_SECRET '⟨password⟩',
    OAUTH2_SERVER_URI '⟨http://iceberg_rest_catalog_url.com/v1/oauth/tokens⟩'
);

Wenn Sie bereits ein Bearer-Token haben, können Sie es direkt an Ihre CREATE SECRET-Anweisung übergeben

CREATE SECRET iceberg_secret (
    TYPE iceberg,
    TOKEN '⟨bearer_token⟩'
);

Sie können den Iceberg-Katalog mit der folgenden ATTACH-Anweisung anhängen.

LOAD httpfs;
ATTACH '⟨warehouse⟩' AS iceberg_catalog (
   TYPE iceberg,
   SECRET iceberg_secret, -- pass a specific secret name to prevent ambiguity
   ENDPOINT '⟨https://rest_endpoint.com⟩'
);

Um die verfügbaren Tabellen anzuzeigen, führen Sie aus

SHOW ALL TABLES;

`ATTACH`-Optionen

Ein REST Catalog mit OAuth2-Autorisierung kann auch allein mit einer ATTACH-Anweisung angehängt werden. Die vollständige Liste der ATTACH-Optionen für einen REST Catalog finden Sie unten.

Parameter	Typ	Standard	Beschreibung
`ENDPOINT_TYPE`	`VARCHAR`	`NULL`	Wird zum Anhängen von S3-Tables- oder Glue-Katalogen verwendet. Zulässige Werte sind `GLUE` und `S3_TABLES`. Kann nicht mit `ENDPOINT` oder `AUTHORIZATION_TYPE` kombiniert werden.
`ENDPOINT`	`VARCHAR`	`NULL`	URL-Endpunkt für die Kommunikation mit dem REST Catalog. Kann nicht zusammen mit `ENDPOINT_TYPE` verwendet werden.
`SECRET`	`VARCHAR`	`NULL`	Name des Secrets, das für die Kommunikation mit dem REST Catalog verwendet wird.
`CLIENT_ID`	`VARCHAR`	`NULL`	`CLIENT_ID`, der für das Secret verwendet wird.
`CLIENT_SECRET`	`VARCHAR`	`NULL`	`CLIENT_SECRET`, der für das Secret verwendet wird.
`DEFAULT_REGION`	`VARCHAR`	`NULL`	Standardregion für die Kommunikation mit der Speicherschicht.
`DEFAULT_SCHEMA`	`VARCHAR`	`NULL`	Das Standard-Schema (Namespace), das für den angehängten Katalog verwendet wird.
`OAUTH2_SERVER_URI`	`VARCHAR`	`NULL`	OAuth2-Server-URL zum Abrufen eines Bearer-Tokens.
`AUTHORIZATION_TYPE`	`VARCHAR`	`OAUTH2`	Autorisierungsschema. Übergeben Sie `SigV4` für Kataloge, die SigV4-Autorisierung erfordern, oder `none` für Kataloge ohne Authentifizierung. Kann nicht mit `ENDPOINT_TYPE` kombiniert werden.
`ACCESS_DELEGATION_MODE`	`VARCHAR`	`vended_credentials`	Zugriffsdelegationsmodus. Zulässige Werte sind `vended_credentials` und `none`.
`EXTRA_HTTP_HEADERS`	`MAP`	`NULL`	Zusätzliche HTTP-Header, die mit REST-Catalog-Anfragen gesendet werden.
`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`	Steuert, ob DuckDB Speicherdateien entfernt, wenn eine Tabelle gelöscht wird.
`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`.

Beim Anhängen eines AWS-Katalogs mit ENDPOINT_TYPE (s3_tables oder glue) wendet DuckDB AWS-geeignete Standardwerte an: stage_create_tables und remove_files_on_delete werden false und purge_requested wird true, sofern Sie sie nicht explizit setzen.

Die folgenden Optionen können nur an eine CREATE SECRET-Anweisung übergeben werden und erfordern, dass AUTHORIZATION_TYPE OAUTH2 ist:

Parameter	Typ	Standard	Beschreibung
`OAUTH2_GRANT_TYPE`	`VARCHAR`	`NULL`	Grant Type beim Anfordern eines OAuth-Tokens.
`OAUTH2_SCOPE`	`VARCHAR`	`NULL`	Angefragter Scope für das zurückgegebene OAuth Access Token.

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);

Beispiele für bestimmte Kataloge

DuckDB kann eine Reihe von Iceberg REST Catalogs anhängen. Die von AWS verwalteten Kataloge haben eigene Einrichtungsseiten, weil sie AWS-Anmeldedaten und SigV4-Autorisierung erfordern:

Die übrigen Kataloge werden direkt auf dieser Seite konfiguriert:

Cloudflare R2 Catalog

Um einen von R2 Cloudflare verwalteten Katalog anzuhängen, folgen Sie den folgenden Schritten.

CREATE SECRET r2_secret (
    TYPE iceberg,
    TOKEN '⟨r2_token⟩'
);

Ein Token können Sie gemäß den Schritten API-Token anlegen in „Getting started“ erzeugen. Hängen Sie den Katalog anschließend mit den folgenden Befehlen an.

ATTACH '⟨warehouse⟩' AS my_r2_catalog (
    TYPE iceberg,
    ENDPOINT '⟨catalog-uri⟩'
);

Die Variablen für warehouse und catalog-uri finden Sie in den Einstellungen des R2 Object Storage Catalog (R2 Object Store, Catalog name, Settings).

Nachdem Sie den R2 Data Catalog angehängt haben, legen Sie ein Schema an. Sie können es mit dem Befehl USE als Standard setzen:

CREATE SCHEMA my_r2_catalog.my_schema;
USE my_r2_catalog.my_schema;

Polaris

Um einen Polaris-Katalog anzuhängen, verwenden Sie die folgenden Befehle:

CREATE SECRET polaris_secret (
    TYPE iceberg,
    CLIENT_ID '⟨admin⟩',
    CLIENT_SECRET '⟨password⟩',
);

ATTACH 'quickstart_catalog' AS polaris_catalog (
    TYPE iceberg,
    ENDPOINT '⟨polaris_rest_catalog_endpoint⟩',
    ACCESS_DELEGATION_MODE 'vended_credentials'
);

Lakekeeper

Um einen Lakekeeper-Katalog anzuhängen, funktionieren die folgenden Befehle.

CREATE SECRET lakekeeper_secret (
    TYPE iceberg,
    CLIENT_ID '⟨admin⟩',
    CLIENT_SECRET '⟨password⟩',
    OAUTH2_SCOPE '⟨scope⟩',
    OAUTH2_SERVER_URI '⟨lakekeeper_oauth_url⟩'
);

ATTACH '⟨warehouse⟩' AS lakekeeper_catalog (
    TYPE iceberg,
    ENDPOINT '⟨lakekeeper_irc_url⟩',
    SECRET '⟨lakekeeper_secret⟩'
);

SeaweedFS

SeaweedFS-Table-Buckets liefern beide Hälften einer Iceberg-Bereitstellung: Der eingebettete Iceberg REST Catalog stellt die Tabellenmetadaten bereit, und der Table-Bucket speichert die Tabellendaten als Parquet-Dateien hinter demselben SeaweedFS-S3-Gateway. Speichern Sie die OAuth2-Anmeldedaten des Katalogs in einem Iceberg-Secret und die S3-Anmeldedaten in einem S3-Secret, damit DuckDB die Parquet-Dateien über dasselbe Gateway lesen kann:

CREATE SECRET seaweedfs_secret (
    TYPE iceberg,
    CLIENT_ID '⟨access_key⟩',
    CLIENT_SECRET '⟨secret_key⟩',
    OAUTH2_SERVER_URI 'http://⟨seaweedfs_host⟩:8181/v1/oauth/tokens'
);

CREATE SECRET seaweedfs_storage (
    TYPE s3,
    KEY_ID '⟨access_key⟩',
    SECRET '⟨secret_key⟩',
    ENDPOINT '⟨seaweedfs_host⟩:8333',
    URL_STYLE 'path',
    USE_SSL false
);

ATTACH '⟨table_bucket_name⟩' AS seaweedfs_catalog (
    TYPE iceberg,
    ENDPOINT 'http://⟨seaweedfs_host⟩:8181',
    SECRET seaweedfs_secret
);

Lesen und Schreiben funktionieren mit den Standard-ATTACH-Optionen, einschließlich CREATE SCHEMA, CREATE TABLE, INSERT und DROP TABLE:

CREATE SCHEMA seaweedfs_catalog.sales;
CREATE TABLE seaweedfs_catalog.sales.orders (id BIGINT, region VARCHAR, amount DOUBLE);
INSERT INTO seaweedfs_catalog.sales.orders VALUES (1, 'NA', 12.5), (2, 'EU', 40.0), (3, 'APAC', 99.9);

SELECT region, sum(amount) AS total
FROM seaweedfs_catalog.sales.orders
GROUP BY region
ORDER BY total DESC;

DROP TABLE seaweedfs_catalog.sales.orders;

Google Cloud BigLake

Um einen Google Cloud BigLake-Katalog anzuhängen, können Sie zusätzliche HTTP-Header verwenden, um das GCP-Projekt für die Abrechnung anzugeben.

Holen Sie zuerst Ihr Google-Cloud-Zugriffstoken:

gcloud auth application-default print-access-token

Legen Sie anschließend ein Secret mit dem Token und zusätzlichen Headern an:

CREATE SECRET biglake_secret (
    TYPE iceberg,
    TOKEN '⟨your_access_token⟩',
    EXTRA_HTTP_HEADERS MAP {
        'x-goog-user-project': '⟨your_gcp_project_id⟩'
    }
);

Hängen Sie den BigLake-Katalog an:

ATTACH '⟨gs://your-biglake-bucket⟩' AS biglake_catalog (
    TYPE iceberg,
    ENDPOINT 'https://biglake.googleapis.com/iceberg/v1/restcatalog',
    SECRET biglake_secret
);

Beispiel mit dem öffentlichen BigLake-Datensatz:

CREATE SECRET biglake_public_secret (
    TYPE iceberg,
    TOKEN '⟨your_access_token⟩',
    EXTRA_HTTP_HEADERS MAP {
        'x-goog-user-project': '⟨your_gcp_project_id⟩'
    }
);

ATTACH 'gs://biglake-public-nyc-taxi-iceberg' AS biglake_public (
    TYPE iceberg,
    ENDPOINT 'https://biglake.googleapis.com/iceberg/v1/restcatalog',
    SECRET biglake_public_secret
);

-- Query the data
SELECT count(*) FROM biglake_public.public_data.nyc_taxicab;

Google-Cloud-Zugriffstoken laufen nach 1 Stunde ab. Bei länger laufenden Sitzungen müssen Sie das Token regelmäßig aktualisieren.

Kataloge mit eingeschränkter REST-Spec-Unterstützung

Einige Kataloge implementieren nur eine Teilmenge der Iceberg-REST-Catalog-Spezifikation. Nutzen Sie die folgenden Kompatibilitätsoptionen, um das Verhalten von DuckDB für diese Kataloge anzupassen.

Katalogverhalten	Zu setzende Option
Unterstützt kein gestuftes CREATE TABLE	`STAGE_CREATE_TABLES false`
Lehnt den Endpunkt für Multi-Table-Transaktionen/Commit ab	`DISABLE_MULTI_TABLE_COMMIT true`
Initialisiert Metadaten bei CREATE TABLE vollständig und lehnt nachfolgende Metadatenaktualisierungen ab	`SKIP_CREATE_TABLE_METADATA_UPDATES true`
Erlaubt DuckDB nicht, Speicherdateien bei DROP TABLE zu entfernen	`REMOVE_FILES_ON_DELETE false`

Um beispielsweise einen Unity Catalog Horizon-Endpunkt anzuhängen, der keine gestuften Creates unterstützt, den Endpunkt transactions/commit ablehnt und Metadaten sowie Speicherbereinigung selbst verwaltet:

ATTACH '⟨warehouse⟩' AS horizon_catalog (
    TYPE iceberg,
    ENDPOINT '⟨catalog_endpoint⟩',
    STAGE_CREATE_TABLES false,
    DISABLE_MULTI_TABLE_COMMIT true,
    SKIP_CREATE_TABLE_METADATA_UPDATES true,
    REMOVE_FILES_ON_DELETE false
);

Einschränkungen

DuckDB unterstützt Iceberg REST Catalogs, die auf S3, S3 Tables und Google Cloud Storage (GCS) basieren. Die Unterstützung anderer Speicher-Backends ist noch nicht verfügbar.