Zum Inhalt springen
DuckDBDuckDBDuckDB
Deutsch

Kataloge

Die iceberg-Erweiterung unterstützt das Anhängen von Iceberg REST Catalogs. Das Anhängen eines Katalogs ist für das Schreiben nach Iceberg erforderlich. Bevor Sie einen Iceberg REST Catalog anhängen, müssen Sie die iceberg-Erweiterung gemäß den Anweisungen im Überblick installieren.

Der Abschnitt unten beschreibt den allgemeinen Weg, einen Iceberg REST Catalog anzuhängen. Anweisungen zu einer bestimmten Katalogimplementierung finden Sie unter Amazon S3 Tables, AWS Glue, Cloudflare R2 Data Catalog, Apache Polaris, Lakekeeper, SeaweedFS und Google Cloud BigLake.

Einen Iceberg REST Catalog anhängen

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;

Ein REST Catalog mit OAuth2-Autorisierung kann auch allein mit einer ATTACH-Anweisung angehängt werden. Die vollständige Liste der ATTACH- und CREATE SECRET-Optionen finden Sie auf der Seite Iceberg-Optionen.

Amazon S3 Tables

Die iceberg-Erweiterung unterstützt das Lesen von Iceberg-Tabellen, die in Amazon S3 Tables gespeichert sind.

Sie können DuckDB Ihre AWS-Anmeldedaten und -Konfiguration anhand des Standardprofils in Ihrem Verzeichnis ~/.aws erkennen lassen, indem Sie mit dem Secrets Manager folgendes Secret anlegen:

CREATE SECRET (
    TYPE s3,
    PROVIDER credential_chain
);

Alternativ können Sie die Werte manuell setzen:

CREATE SECRET (
    TYPE s3,
    KEY_ID '⟨key_id⟩',
    SECRET '⟨secret⟩',
    REGION '⟨region⟩'
);

Die vollständige Palette der Anmeldedaten-Optionen (angenommene Rollen, SSO, Web Identity und mehr) finden Sie in der aws-Erweiterung.

Verbinden Sie sich anschließend mit dem Katalog über Ihre S3-Tables-ARN (verfügbar in der AWS Management Console) und die Option ENDPOINT_TYPE s3_tables:

ATTACH '⟨s3_tables_arn⟩' AS my_s3_tables_catalog (
   TYPE iceberg,
   ENDPOINT_TYPE s3_tables
);

Warning ENDPOINT_TYPE s3_tables baut immer einen Endpunkt der Form s3tables.⟨region⟩.amazonaws.com/iceberg. Das ist für jede Region falsch, deren Endpunkt nicht das einfache Suffix amazonaws.com verwendet — insbesondere die AWS-China-Regionen (cn-north-1, cn-northwest-1), die amazonaws.com.cn verwenden. Für solche Regionen hängen Sie den Katalog an, indem Sie einen expliziten ENDPOINT (mit dem richtigen Host für Ihre Region) zusammen mit AUTHORIZATION_TYPE 'sigv4' übergeben, statt ENDPOINT_TYPE zu verwenden.

Um zu prüfen, ob das Anhängen funktioniert hat, listen Sie alle Tabellen auf:

SHOW ALL TABLES;

Sie können eine Tabelle wie folgt abfragen:

SELECT count(*)
FROM my_s3_tables_catalog.⟨namespace_name⟩.⟨table_name⟩;

AWS Glue (Amazon SageMaker Lakehouse)

Die iceberg-Erweiterung unterstützt das Lesen von Iceberg-Tabellen über den Katalog Amazon SageMaker Lakehouse (auch bekannt als AWS Glue).

Legen Sie mit dem Secrets Manager ein S3-Secret an:

CREATE SECRET (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN sts,
    ASSUME_ROLE_ARN 'arn:aws:iam::⟨account_id⟩:role/⟨role⟩',
    REGION 'us-east-2'
);

In diesem Beispiel verwenden wir ein STS-Token, aber andere Authentifizierungsmethoden werden unterstützt.

Verbinden Sie sich anschließend mit dem Katalog:

ATTACH '⟨account_id⟩' AS glue_catalog (
    TYPE ICEBERG,
    ENDPOINT 'glue.⟨REGION⟩.amazonaws.com/iceberg',
    AUTHORIZATION_TYPE 'sigv4'
);

Oder alternativ:

ATTACH '⟨account_id⟩' AS glue_catalog (
    TYPE ICEBERG,
    ENDPOINT_TYPE 'glue'
);

Warning Wie bei Amazon S3 Tables baut ENDPOINT_TYPE glue immer einen Endpunkt der Form glue.⟨region⟩.amazonaws.com/iceberg, der für Regionen falsch ist, die nicht das einfache Suffix amazonaws.com verwenden (insbesondere die AWS-China-Regionen cn-north-1 und cn-northwest-1, die amazonaws.com.cn verwenden). Für solche Regionen hängen Sie mit einem expliziten ENDPOINT (mit dem richtigen Host) zusammen mit AUTHORIZATION_TYPE 'sigv4' an, statt ENDPOINT_TYPE zu verwenden.

Die Warehouse-Kennung (das erste Argument von ATTACH) akzeptiert die folgenden Formen:

Warehouse Bedeutung
: Der Standardkatalog des Kontos des Aufrufers.
⟨account_id⟩ Eine 12-stellige AWS-Konto-ID.
⟨account_id⟩:⟨catalog⟩ Ein benannter Katalog im angegebenen Konto.
⟨catalog⟩/⟨sub_catalog⟩ Ein verschachtelter (föderierter) Katalog.
⟨account_id⟩:⟨catalog⟩/⟨sub_catalog⟩ Ein verschachtelter Katalog im angegebenen Konto.

Um zu prüfen, ob das Anhängen funktioniert hat, listen Sie alle Tabellen auf:

SHOW ALL TABLES;

Sie können eine Tabelle wie folgt abfragen:

SELECT count(*)
FROM glue_catalog.⟨namespace_name⟩.⟨table_name⟩;

Wenn Sie einen von S3 Tables föderierten Katalog haben, können Sie eine Tabelle mit der üblichen CREATE TABLE-Syntax anlegen;

CREATE TABLE glue_catalog.⟨namespace_name⟩.⟨table_name⟩ (a INTEGER, b VARCHAR);

Wenn der Katalog nicht von S3 Tables föderiert ist, müssen Sie möglicherweise eine Tabelleneigenschaft location übergeben. Das geht mit der Klausel WITH.

CREATE TABLE glue_catalog.⟨namespace_name⟩.⟨table_name⟩ (a INTEGER, b VARCHAR)
WITH (
    'location' = 's3://path/to/location'
);

Mehr zur Klausel WITH erfahren Sie unter Tabellen anlegen.

Cloudflare R2 Data 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;

Apache 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:

Terminal window
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;

Note: 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.

Dies ist eine inoffizielle Website und nicht mit DuckDB verbunden. Offizielle Seite:duckdb.org.duckdb.ubitools.com · Übersetzt und erstellt mit Astro und daisyUI