Zugriff auf Apache Iceberg™-Tabellen mit einer externen Engine über Snowflake Horizon Catalog

Greifen Sie auf Snowflake-verwaltete Apache Iceberg™-Tabellen durch Verwendung einer externen Abfrage-Engine über Snowflake Horizon Catalog zu. Um diese Interoperabilität mit externen Engines sicherzustellen, ist Apache Polaris™ in Horizon Catalog integriert. Darüber hinaus stellt Horizon Catalog die Apache Iceberg™ REST API (Horizon Iceberg REST Catalog API) zur Verfügung. Diese API ermöglicht den Zugriff auf Tabellen durch Verwendung externer Abfrage-Engines.

Sie können Horizon Catalog, der in allen Ihren bestehenden Snowflake-Konten verfügbar ist, verwenden, um in von Snowflake verwalteten Iceberg-Tabellen mit externen Abfrage-Engines zu lesen und zu schreiben. Wenn Sie Horizon Catalog verwenden, müssen Sie keine von Snowflake verwalteten Iceberg-Tabellen über Snowflake Open Catalog synchronisieren oder ein separates Snowflake Open Catalog-Konto erstellen, um mit externen Abfrage-Engines auf von Snowflake verwaltete Iceberg-Tabellen zuzugreifen.

Iceberg-Tabellen abfragen

Durch die Verbindung einer externen Abfrage-Engine mit Iceberg-Tabellen über Horizon Catalog können Sie die folgenden Aufgaben durchführen:

  • Sie können eine externe Abfrage-Engine verwenden, die das offene Iceberg REST-Protokoll, wie z. B. Apache Spark™, für die Abfrage dieser Tabellen unterstützt.

  • Sie können über einen einzigen Horizon Catalog-Endpunkt alle bestehenden und neuen von Snowflake verwalteten Iceberg-Tabellen in einem neuen oder bestehenden Snowflake-Konto abfragen.

  • Sie können die Tabellen mit Ihren vorhandenen Benutzenden, Rollen, Richtlinien und Authentifizierungsmethoden in Snowflake abfragen.

  • Sie können automatische Anmeldeinformationen verwenden.

Weitere Informationen zum Snowflake Horizon Catalog finden Sie unter Snowflake Horizon Catalog.

Schreiben in Iceberg-Tabellen

Das Schreiben in Iceberg-Tabellen mithilfe einer externen Abfrage-Engine über Horizon Catalog ist in der öffentlichen Vorschau. Um in Tabellen zu schreiben, befolgen Sie den Workflow für den Zugriff auf Iceberg-Tabellen unter Verwendung einer externen Abfrage-Engine. Stellen Sie bei der Konfiguration der Zugriffssteuerung sicher, dass Sie :ref:` Schreibzugriff auf Ihre Tabellen konfigurieren<label-tables_iceberg_query_using_external_query_engine_snowflake_horizon_configure_write_access>`.

Dann können Sie in Iceberg-Tabellen schreiben.

Die folgende Abbildung zeigt externe Abfrage-Engines, die in von Snowflake verwaltete Iceberg-Tabellen über Horizon Catalog lesen und schreiben, und Snowflake beim Schreiben und Lesen in diesen Tabellen:

Abbildung mit externen Abfrage-Engines, die von Snowflake verwaltete Iceberg-Tabellen über Horizon Catalog lesen, und mit Snowflake beim Schreiben und  Lesen in diesen Tabellen.

Rechnungsstellung

  • Die Horizon Iceberg REST Catalog-API ist in allen Snowflake-Editionen verfügbar.

  • Die API-Anfragen werden mit 0,5 Credits pro Million Aufrufe abgerechnet und als Cloud-Services berechnet.

  • Für den regionsübergreifenden Datenzugriff gelten regionsübergreifende Standardgebühren für ausgehende Daten, wie in der Snowflake Service Consumption Table angegeben.

Bemerkung

Die Abrechnung für dieses Feature ist ab Mitte 2026 geplant; Änderungen vorbehalten.

Unterstützte externe Engines und Kataloge

Die folgenden Tabellen sind zwar nicht vollständig, aber sie zeigen viele externe Engines und Kataloge, die in die Horizon Iceberg REST Catalog API integriert sind. Diese Integration ermöglicht den Zugriff auf von Snowflake verwaltete Iceberg-Tabellen über externe Systeme.

Unterstützte externe Engines

Die folgenden externen Abfrage-Engines sind in die Horizon Iceberg REST Catalog API integriert:

Produkt

Zugriff über Horizon Catalog auf von Snowflake verwaltete Iceberg-Tabellen

Apache Doris™

Apache Flink™

Apache Spark™

Dremio

DuckDB

PyIceberg

StarRocks

Trino

Unterstützte externe Kataloge

Die folgenden externen Kataloge lassen sich in die Horizon Iceberg REST Catalog API integrieren:

Produkt

Zugriff über Horizon Catalog auf von Snowflake verwaltete Iceberg-Tabellen

Kommentar

Apache Polaris™

AWS Glue

Anweisungen zum Konfigurieren dieser Integration finden Sie im AWS Big Data-Blog zum Zugriff auf Snowflake Horizon Catalog-Daten über den Katalogverbund im AWS Glue Data Catalog.

Palantir Foundry

Anweisungen zum Konfigurieren dieser Integration finden Sie unter Iceberg-Tabellen (nur virtuelle Tabellen) in der Palantir-Dokumentation.

Databricks Unity-Katalog

Nicht angekündigt

Google BigLake Metastore

In der Entwicklung

Microsoft Fabric / Synapse

In der Entwicklung

Voraussetzungen

Rufen Sie den Kontobezeichner für Ihr Snowflake-Konto ab, das die gewünschten Iceberg-Tabellen für den Zugriff enthält. Eine Anweisung dazu finden Sie unter Kontobezeichner. Sie geben diesen Bezeichner an, wenn Sie eine externe Abfrage-Engine mit Ihren Iceberg-Tabellen verbinden möchten.

Tipp

Um Ihren Kontobezeichner mit SQL abzurufen, können Sie den folgenden Befehl ausführen:

SELECT CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME();

(Optional) Private Konnektivität

Für eine sichere Konnektivität sollten Sie die eingehende und ausgehende private Konnektivität für Ihr Snowflake-Konto konfigurieren, während Sie auf den Endpunkt des Horizon Catalog zugreifen.

Bemerkung

Private Konnektivität wird nur für von Snowflake verwaltete Iceberg-Tabellen unterstützt, die auf Amazon S3 oder Azure Storage (ADLS) gespeichert sind.

Workflow für den Zugriff auf Iceberg-Tabellen mithilfe einer externen Abfrage-Engine

Um auf Iceberg-Tabellen mithilfe einer externen Abfrage-Engine zuzugreifen, führen Sie die folgenden Schritte durch:

  1. Iceberg-Tabellen erstellen

  2. Zugriffssteuerung konfigurieren

  3. Zugriffstoken für die Authentifizierung besorgen

  4. Berechtigungen für Zugriffstoken überprüfen

  5. (Optional) Datenschutzrichtlinien konfigurieren

  6. Externe Abfrage-Engine mit Iceberg-Tabellen über Horizon Catalog verbinden

  7. Iceberg-Tabellen abfragen oder in Iceberg-Tabellen schreiben

Schritt 1: Iceberg-Tabellen erstellen

Wichtig

Wenn Sie bereits über Snowflake-verwaltete Iceberg-Tabellen verfügen, auf die Sie zugreifen möchten, können Sie diesen Schritt überspringen.

In diesem Schritt erstellen Sie von Snowflake verwaltete Iceberg-Tabellen, die Snowflake als Katalog verwenden, sodass Sie sie mit einer externen Abfrage-Engine darauf zugreifen können. Anleitungen finden Sie unter den folgenden Themen:

Schritt 2: Zugriffssteuerung konfigurieren

Wichtig

Wenn Sie bereits Rollen haben, die mit Zugriff auf die Iceberg-Tabellen konfiguriert sind, auf die Sie zugreifen möchten, können Sie diesen Schritt überspringen.

In diesem Schritt konfigurieren Sie die Zugriffssteuerung für die von Snowflake verwalteten Iceberg-Tabellen, auf die Sie mit einer externen Abfrage-Engine zugreifen möchten. Sie können zum Beispiel die folgenden Rollen in Snowflake einrichten:

  • Die data_engineer-Rolle, die Zugriff auf alle Schemas und alle von Snowflake verwalteten Iceberg-Tabellen in einer Datenbank hat.

  • Die data_analyst-Rolle, die Zugriff auf ein Schema in der Datenbank und innerhalb dieses Schemas nur Zugriff auf zwei von Snowflake verwaltete Iceberg-Tabellen hat.

Weitere Informationen finden Sie in den folgenden Abschnitten:

Lesezugriff auf Ihre Iceberg-Tabellen konfigurieren

Um Iceberg-Tabellen abzufragen, muss die Rolle, mit welcher der Vorgang durchgeführt wird, auch die SELECT-Berechtigung für die Iceberg-Tabelle und die USAGE-Berechtigung für die übergeordnete Datenbank und das Schema haben. Ein Beispiel für die Gewährung dieser Berechtigungen für eine Rolle finden Sie unter:ref:label-tables_iceberg_query_using_external_query_engine_snowflake_horizon_set_up_service_account_user.

Wichtig

Die Rolle mit der OWNERSHIP-Berechtigung für eine Iceberg-Tabelle muss die USAGE-Berechtigung für das mit der Tabelle verbundene externe Volume beibehalten. Wenn die Eigentümerrolle keine USAGE-Berechtigung für das externe Volume hat, schlägt jede Lese- oder Schreiboperation der Tabelle fehl, bei der nach automatischen Anmeldeinformationen gefragt wird.

Beispiel: Einen Dienstkontobenutzer einrichten

Im folgenden Beispiel wird ein Dienstkontobenutzender in Snowflake mit schreibgeschütztem Zugriff auf eine Iceberg-Tabelle eingerichtet:

  • Erstellt eine``data_engineer``-Rolle.

  • Gewährt die data_engineer-RolleUSAGE- und MONITOR-Berechtigungen für die iceberg_test_db-Datenbank und deren public-Schema.

  • Gewährt SELECT-Berechtigungen für die``test_table``-Iceberg-Tabelle.

  • Erstellt einen Dienstbenutzer mit dem Namen``horizon_rest_srv_account_user`` und weist diesem Benutzer die data_engineer-Rolle zu.

CREATE OR REPLACE ROLE data_engineer;

GRANT USAGE ON DATABASE iceberg_test_db TO ROLE data_engineer;
GRANT USAGE ON SCHEMA iceberg_test_db.public TO ROLE data_engineer;

GRANT SELECT ON TABLE iceberg_test_db.public.test_table TO ROLE data_engineer;

CREATE OR REPLACE USER horizon_rest_srv_account_user TYPE=SERVICE DEFAULT_ROLE=data_engineer;

GRANT ROLE data_engineer TO USER horizon_rest_srv_account_user;

(Optional) Zukünftige Berechtigungszuweisungen auf Iceberg-Tabellen anwenden

Um den Zugriff auf alle neuen Iceberg-Tabellen zu gewährleisten, die in einem Schema erstellt wurden, verwenden Sie die Syntax GRANT …ONFUTUREICEBERGTABLES.

Im folgenden Beispiel wird der Rolle data_engineer Zugriff auf alle Iceberg-Tabellen gewährt, die unter einem Schema namens my_schema erstellt wurden.

GRANT SELECT ON FUTURE ICEBERG TABLES IN SCHEMA my_db.my_schema TO ROLE data_engineer;

Weitere Informationen zur Zugriffssteuerung in Snowflake finden Sie unter folgenden Themen:

Schreibzugriff auf Ihre Iceberg-Tabellen konfigurieren

In der folgenden Tabelle sind die Berechtigungen beschrieben, die für Schreiboperationen auf Iceberg-Tabellen erforderlich sind:

Operation

Erforderliche Berechtigungen

Datenbearbeitungssprache (DML)-Operationen

Wichtig

Eine Rolle, die zur Ausführung der Operation verwendet wird, muss alle der folgenden Berechtigungen haben:

  • SELECT-, UPDATE-, TRUNCATE-, INSERT- und DELETE-Berechtigungen für die Tabelle

  • USAGE-Berechtigung für das übergeordnete Schema, unter dem die Tabelle verschachtelt ist

  • USAGE-Berechtigung für die übergeordnete Datenbank oder das übergeordnete Schema, unter dem die Tabelle verschachtelt ist

CREATE ICEBERG TABLE

Eine Rolle, die zur Ausführung der Operation verwendet wird, muss die folgenden Berechtigungen haben:

  • Berechtigung CREATE ICEBERG TABLE für das Schema

  • USAGE-Berechtigung für das externe Volume

CREATE SCHEMA

Eine Rolle, die zur Ausführung der Operation verwendet wird, muss die Berechtigung CREATE SCHEMA für die übergeordnete Datenbank haben.

Umbenennen einer Tabelle

Eine Rolle, die zur Ausführung der Operation verwendet wird, muss die OWNERSHIP-Berechtigung für die Tabelle haben.

Wichtig

Um die Tabelle in ein neues Schema zu verschieben, stellen Sie sicher, dass Ihre Rolle auch die CREATE ICEBERG TABLE-Berechtigung für das Zielschema hat.

Alle anderen Operationen für eine Tabelle

Eine Rolle, die zur Ausführung der Operation verwendet wird, muss die OWNERSHIP-Berechtigung für die Tabelle zusätzlich zu den Berechtigungen für das Schema und die Datenbank haben. Sie müssen zum Beispiel über diese Berechtigungen verfügen, um die Operation ALTER ICEBERG TABLE … ADD COLUMN oder ALTER ICEBERG TABLE … DROP COLUMN auszuführen.

Weitere Informationen zur Zugriffssteuerung in Snowflake finden Sie unter folgenden Themen:

Schritt 3: Zugriffstoken für die Authentifizierung besorgen

In diesem Schritt erhalten Sie ein Zugriffstoken, das Sie beim Authentifizieren des Horizon Catalog-Endpunkts für Ihr Snowflake-Konto benötigen. Sie benötigen ein Zugriffstoken für jeden Benutzenden –Service oder Mensch – und für jede Rolle, die mit Zugriff auf von Snowflake verwaltete Iceberg-Tabellen konfiguriert ist. Sie benötigen zum Beispiel ein Zugriffstoken für einen Benutzer mit DATA_ENGINEER-Rolle und einen anderen Benutzer mit einer DATA_ANALYST-Rolle.

Sie geben dieses Zugriffstoken später beim Verbinden einer externen Abfrage-Engine mit Iceberg-Tabellen über Horizon Catalog an.

Sie können ein Zugriffstoken erhalten, indem Sie eine der folgenden Authentifizierungsoptionen verwenden:

External OAuth

Wenn Sie External OAuth verwenden, generieren Sie ein Zugriffstoken für Ihren Identitätsanbieter. Eine Anweisung dazu finden Sie unter Übersicht zu External OAuth.

Bemerkung

Für External OAuth können Sie auch Ihre Verbindung zur Engine mit automatischer Tokenaktualisierung konfigurieren, anstatt ein Zugriffstoken anzugeben.

Schlüsselpaar-Authentifizierung

Wenn Sie die Schlüsselpaar-Authentifizierung verwenden, signieren Sie ein JSON Web Token (JWT) mit Ihrem privaten Schlüssel.

Die folgenden Schritte beschreiben, wie Sie ein Zugriffstoken für die Schlüsselpaar-Authentifizierung generieren:

  1. Schlüsselpaar-Authentifizierung konfigurieren

  2. Den Benutzenden eine Rolle zuweisen

  3. Ein JSON-Web-Token (JWT) generieren

  4. Zugriffstoken generieren

Schritt 1: Schlüsselpaar-Authentifizierung konfigurieren

In diesem Schritt werden Sie die folgenden Aufgaben ausführen:

  • Privaten Schlüssel generieren

  • Öffentlichen Schlüssel generieren

  • Private und öffentliche Schlüssel sicher speichern

  • Erteilen Sie die Berechtigung, einem Snowflake Benutzer einen öffentlichen Schlüssel zuzuweisen.

  • Snowflake-Benutzern einen öffentlichen Schlüssel zuweisen

  • Fingerabdruck des öffentlichen Schlüssels des Benutzers überprüfen

Eine Anweisung dazu finden Sie unter Konfigurieren der Schlüsselpaar-Authentifizierung.

Schritt 2: Den Benutzenden eine Rolle zuweisen

Um den Benutzenden der Schlüsselpaar-Authentifizierung die Snowflake-Rolle zuzuweisen, die über Berechtigungen für die Tabellen verfügt, auf die Sie zugreifen möchten, führen Sie den Befehl GRANT ROLE aus. Um beispielsweise dem Benutzer my_service_user die Rolle ENGINEER zuzuweisen, führen Sie die folgenden Befehle aus:

GRANT ROLE ENGINEER to user my_service_user;

Schritt 3: Ein JSON-Web-Token (JWT) generieren

In diesem Schritt verwenden Sie SnowSQL, um ein JSON-Web-Token (JWT) für die Schlüsselpaar-Authentifizierung zu generieren.

Bemerkung

Verwenden Sie SnowSQL, um ein JWT zu generieren:

snowsql --private-key-path "<private_key_file>" \
  --generate-jwt \
  -h "<account_identifier>.snowflakecomputing.com" \
  -a "<account_locator>" \
  -u "<user_name>"

Wobei:

  • <private_key_file> is the path to your private key file that corresponds to the public key assigned to your Snowflake user. For example: /Users/jsmith/.ssh/rsa_key.p8.

  • <account_identifier> gibt den Kontobezeichner für Ihr Snowflake-Konto an, im Format <organization_name>-<account_name>. Informationen darüber, wie Sie Ihren Kontobezeichner finden, erhalten Sie unter Unterstützte externe Engines und Kataloge. Ein Beispiel für einen Kontobezeichner ist myorg-myaccount.

  • <account_locator> ist der Konto-Locator Ihres Snowflake-Kontos.

    Informationen zum Suchen des Konto-Locators finden Sie unter Snowflake-Kontoinformationen in Snowsight suchen. Sehen Sie sich den Konto-Locator im Dialogfeld Account Details an.

  • <user_name> ist der Benutzername für eine(n) Snowflake-Benutzende(n), wobei dieser/diesem Benutzenden der öffentliche Schlüssel zugewiesen ist.

Schritt 4: Zugriffstoken generieren

Wichtig

Um ein Zugriffstoken zu generieren, müssen Sie zuerst ein JWT generieren. Sie müssen zunächst ein JWT generieren, weil Sie das JWT zum Generieren des Zugriffstoken benötigen.

Verwenden Sie einen curl-Befehl zum Generieren eines Zugriffstoken:

curl -i --fail -X POST "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens" \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=client_credentials' \
 --data-urlencode 'scope=session:role:<role>' \
 --data-urlencode 'client_secret=<JWT_token>'

Wobei:

  • <account_identifier> gibt den Kontobezeichner für Ihr Snowflake-Konto an, im Format <organization_name>-<account_name>. Informationen darüber, wie Sie Ihren Kontobezeichner finden, erhalten Sie unter Unterstützte externe Engines und Kataloge. Ein Beispiel für einen Kontobezeichner ist myorg-myaccount.

  • <role> ist die Snowflake-Rolle, der Zugriff auf Iceberg-Tabellen wie ENGINEER gewährt wird.

  • <JWT_token> ist das JWT, das Sie im vorherigen Schritt generiert haben.

Programmgesteuertes Zugriffstoken (PAT)

Wenn Sie PATs verwenden, generieren Sie ein PAT zur Authentifizierung.

Zuerst generieren Sie ein PAT, das Sie für das Verbinden einer externen Abfrage-Engine mit Iceberg-Tabellen verwenden. Dann generieren Sie ein Zugriffstoken, das Sie nur zur Überprüfung der Berechtigungen für Ihr PAT verwenden.

Schritt 1: PAT generieren

Eine Anleitung zum Konfigurieren und Generieren einer PAT finden Sie unter Verwenden von programmatische Zugriffstoken für die Authentifizierung.

Im folgenden Beispiel wird ein programmgesteuertes Zugriffstoken (PAT) für den Dienstkontobenutzenden, den Sie im vorherigen Schritt erstellt haben, unter Verwendung des ALTER USER … ADD PROGRAMMATIC ACCESS TOKEN (PAT)-Befehls erstellt:

ALTER USER IF EXISTS HORIZON_REST_SRV_ACCOUNT_USER
ADD PAT HORIZON_REST_SRV_ACCOUNT_USER_PAT
  DAYS_TO_EXPIRY = 7
  ROLE_RESTRICTION = 'DATA_ENGINEER'
  COMMENT = 'HORIZON REST API PAT FOR SERVICE ACCOUNT';

Schritt 2: Ein Zugriffstoken für Ihr PAT generieren

In diesem Schritt generieren Sie ein Zugriffstoken für Ihr PAT.

Achtung

Sie geben das Zugriffstoken, das Sie in diesem Schritt generieren, nur an, wenn Sie die Berechtigungen für Ihr PAT überprüfen. Wenn Sie eine externe Abfrage-Engine mit Iceberg-Tabellen verbinden, müssen Sie Ihr PAT angeben, den Sie im vorherigen Schritt generiert haben, nicht das Zugriffstoken, das Sie in diesem Schritt generieren.

Verwenden Sie einen curl-Befehl, um ein Zugriffstoken für Ihr PAT zu generieren:

curl -i --fail -X POST "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens" \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=client_credentials' \
 --data-urlencode 'scope=session:role:<role>' \
 --data-urlencode 'client_secret=<PAT_token>'

Wobei:

  • <account_identifier> gibt den Kontobezeichner für Ihr Snowflake-Konto an, im Format <organization_name>-<account_name>. Informationen darüber, wie Sie Ihren Kontobezeichner finden, erhalten Sie unter Unterstützte externe Engines und Kataloge. Ein Beispiel für einen Kontobezeichner ist myorg-myaccount.

  • <role> ist die Snowflake-Rolle, die Ihrem PAT gewährt wird. Sie hat Zugriff auf die Iceberg-Tabellen, die Sie abfragen oder darin schreiben möchten, wie z. B. ENGINEER.

  • <PAT_token> ist der Wert für das PAT-Token, das Sie im vorherigen Schritt generiert haben.

Schritt 4: Berechtigungen für Zugriffstoken überprüfen

In diesem Schritt überprüfen Sie die Berechtigungen für das Zugriffstoken, die Sie im vorherigen Schritt erhalten haben.

Überprüfen des Zugriffs auf den Horizon IRC-Endpunkt

Verwenden Sie einen curl-Befehl, um zu überprüfen, ob Sie die Berechtigung haben, auf Ihren Horizon IRC-Endpunkt zuzugreifen:

curl -i --fail -X GET "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog/v1/config?warehouse=<database_name>" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"

Wobei:

  • <account_identifier> gibt den Kontobezeichner für Ihr Snowflake-Konto an, im Format <organization_name>-<account_name>. Informationen darüber, wie Sie Ihren Kontobezeichner finden, erhalten Sie unter Unterstützte externe Engines und Kataloge. Ein Beispiel für einen Kontobezeichner ist myorg-myaccount.

  • <access_token> ist das von Ihnen generierte Zugriffstoken. Bei einem PAT ist dieser Wert das Zugriffstoken, das Sie generiert haben, nicht das persönliche Zugriffstoken (PAT), die Sie generiert haben.

  • <database_name> ist der Name der Datenbank, die die Iceberg-Tabellen enthält, auf die Sie zugreifen möchten.

    Wichtig

    Wenn Ihre Datenbank ohne Anführungszeichen um den Namen erstellt wurde, müssen Sie den Datenbanknamen in Großbuchstaben angeben, auch wenn er mit Kleinbuchstaben erstellt wurde.

Beispiel Rückgabewert:

{
  "defaults": {
    "default-base-location": ""
  },
  "overrides": {
    "prefix": "MY-DATABASE"
  }
}

Abrufen der Metadaten für eine Tabelle

Sie können auch eine GET-Anforderung erstellen, um die Metadaten für eine Tabelle abzurufen. Snowflake verwendet den Vorgang loadTable, um Tabellendaten aus Ihrem REST-Katalog zu laden.

curl -i --fail -X GET "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog/v1/<database_name>/namespaces/<namespace_name>/tables/<table_name>" \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json"

Wobei:

  • <account_identifier> gibt den Kontobezeichner für Ihr Snowflake-Konto an, im Format <organization_name>-<account_name>. Informationen darüber, wie Sie Ihren Kontobezeichner finden, erhalten Sie unter Unterstützte externe Engines und Kataloge. Ein Beispiel für einen Kontobezeichner ist myorg-myaccount.

  • <database_name> ist die Datenbank der Tabelle, deren Metadaten Sie abrufen möchten.

  • <namespace_name> ist der Namespace der Tabelle, deren Metadaten Sie abrufen möchten.

  • <table_name> ist die Tabelle, deren Metadaten Sie abrufen möchten.

  • <access_token> ist das von Ihnen generierte Zugriffstoken. Bei einem PAT ist dieser Wert das Zugriffstoken, das Sie generiert haben, nicht das persönliche Zugriffstoken (PAT), die Sie generiert haben.

Wichtig

Wenn Ihre Datenbank, Ihr Namespace oder Ihre Tabelle ohne Anführungszeichen um den Namen erstellt wurden, müssen Sie den Namen der Datenbank, der Namespaces oder der Tabelle in Großbuchstaben angeben, auch wenn das Objekt mit Kleinbuchstaben erstellt wurde.

(Optional) Schritt 5: Konfigurieren von Datenschutzrichtlinien

In diesem Schritt konfigurieren Sie Datenschutzrichtlinien für Iceberg-Tabellen. Wenn Sie keine Tabellen haben, die Sie mit Snowflake-Datenrichtlinien schützen müssen, können Sie mit dem nächsten Schritt fortfahren.

Bemerkung

Auf Tabellen, die durch Datenschutzrichtlinien geschützt sind, kann über die Horizon Iceberg REST API und durch Verwendung von Apache Spark™ zugegriffen werden.

Eine Anleitung zum Konfigurieren von Datenschutzrichtlinien finden Sie unter Konfigurieren von Datenschutzrichtlinien für Iceberg-Tabellen, auf die über die Horizon Iceberg REST API und mit Apache Spark™ zugegriffen wird.

Schritt 6: Externe Abfrage-Engine mit Iceberg-Tabellen über Horizon Catalog verbinden

In diesem Schritt verbinden Sie eine externe Abfrage-Engine mit Iceberg-Tabellen über Horizon Catalog. Diese Verbindung ermöglicht es Ihnen, die Tabellen mithilfe der externen Abfrage-Engine abzufragen.

Die externen Engines verwenden den Apache Iceberg™ REST-Endpunkt, der von Snowflake bereitgestellt wird. Für Ihr Snowflake-Konto hat dieser Endpunkt das folgende Format:

https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog

Der Beispielcode in diesem Schritt zeigt, wie eine Verbindung in Spark eingerichtet wird, und der Beispielcode ist in PySpark. Weitere Informationen finden Sie in den folgenden Abschnitten:

Verbindung mit External OAuth oder Schlüsselpaar-Authentifizierung herstellen

Verwenden Sie eine der folgenden Konfigurationen für die Verbindung:

Verbinden mit einer externen Abfrage-Engine, ohne Datenrichtlinien durchzusetzen

  • Sie können die externe Abfrage-Engine mit Iceberg-Tabellen verbinden, indem Sie externes OAuth oder die Schlüsselpaar-Authentifizierung verwenden. Verwenden Sie den folgenden Beispielcode.

Dieser Code setzt keine Datenschutzrichtlinien durch:

# Snowflake Horizon Catalog Configuration, change as per your environment

CATALOG_URI = "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog"
HORIZON_SESSION_ROLE = f"session:role:<role>"
CATALOG_NAME = "<database_name>" #provide in UPPER CASE

# Cloud Service Provider Region Configuration (where the Iceberg data is stored)
REGION = "eastus2"

# Paste the External Oauth Access token that you generated in Snowflake here
ACCESS_TOKEN = "<your_access_token>"

# Iceberg Version
ICEBERG_VERSION = "1.9.1"

def create_spark_session():
  """Create and configure Spark session for Snowflake Iceberg access."""
  spark = (
      SparkSession.builder
      .appName("SnowflakeIcebergReader")
      .master("local[*]")

# JAR Dependencies for Iceberg and Azure
      .config(
          "spark.jars.packages",
          f"org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:{ICEBERG_VERSION},"
          f"org.apache.iceberg:iceberg-aws-bundle:{ICEBERG_VERSION}"
          # for Azure storage, use the below package and comment above azure bundle
          # f"org.apache.iceberg:iceberg-azure-bundle:{ICEBERG_VERSION}"
      )

      # Iceberg SQL Extensions
      .config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions")
      .config("spark.sql.defaultCatalog", CATALOG_NAME)

      # Horizon REST Catalog Configuration
      .config(f"spark.sql.catalog.{CATALOG_NAME}", "org.apache.iceberg.spark.SparkCatalog")
      .config(f"spark.sql.catalog.{CATALOG_NAME}.type", "rest")
      .config(f"spark.sql.catalog.{CATALOG_NAME}.uri", CATALOG_URI)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.warehouse", CATALOG_NAME)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.token", ACCESS_TOKEN)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.scope", HORIZON_SESSION_ROLE)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.client.region", REGION)

      # Required for vended credentials
      .config(f"spark.sql.catalog.{CATALOG_NAME}.header.X-Iceberg-Access-Delegation", "vended-credentials")
      .config("spark.sql.iceberg.vectorization.enabled", "false")
      .getOrCreate()
  )
  spark.sparkContext.setLogLevel("ERROR")
  return spark

Wobei:

  • <account_identifier> ist Ihr Snowflake-Kontobezeichner für das Snowflake-Konto, das die Iceberg-Tabellen enthält, auf die Sie zugreifen möchten. Wie Sie diesen Bezeichner finden, erfahren Sie unter Unterstützte externe Engines und Kataloge.

  • <your_access_token> ist Ihr -Zugriffstoken, das Sie erhalten haben. Wie Sie es erhalten, erfahren Sie unter Schritt 3: Zugriffstoken für die Authentifizierung besorgen.

    Bemerkung

    Für External OAuth können Sie auch Ihre Verbindung zur Engine mit automatischer Tokenaktualisierung konfigurieren, anstatt ein Zugriffstoken anzugeben.

  • <database_name> ist der Name der Datenbank in Ihrem Snowflake-Konto, die von Snowflake verwaltete Iceberg-Tabellen enthält, auf die Sie zugreifen möchten.

    Bemerkung

    Die Eigenschaft .warehouse in Spark erwartet Ihren Snowflake-*Datenbank*namen, nicht den Namen Ihres Snowflake-Warehouses.

  • <role> ist die Rolle in Snowflake, die mit Zugriff auf die Iceberg-Tabellen konfiguriert ist, auf die Sie zugreifen möchten. Beispiel: DATA_ENGINEER.

Wichtig

Standardmäßig ist das Codebeispiel für Apache Iceberg™-Tabellen eingerichtet, die auf Amazon S3 gespeichert sind. Wenn Ihre Iceberg-Tabellen auf Azure Storage (ADLS) gespeichert sind, führen Sie die folgenden Schritte aus:

  1. Versehen Sie die folgende Zeile mit Kommentarmarkierungen: f"org.apache.iceberg:iceberg-aws-bundle:{ICEBERG_VERSION}"

  2. Entfernen Sie die Kommentarmarkierungen in der folgenden Zeile: # f"org.apache.iceberg:iceberg-azure-bundle:{ICEBERG_VERSION}"

Verbinden mit einer externen Abfrage-Engine mit Durchsetzung der Datenrichtlinien

Verbinden über ein programmgesteuertes Zugriffstoken (PAT)

Verwenden Sie eine der folgenden Konfigurationen für die Verbindung:

Verbinden mit einer externen Abfrage-Engine, ohne Datenrichtlinien durchzusetzen

  • Verwenden Sie den folgenden Beispielcode, um die externe Abfrage-Engine mit Iceberg-Tabellen zu verbinden, indem Sie ein programmgesteuertes Zugriffstoken (PAT) verwenden.

Dieser Code setzt keine Datenschutzrichtlinien durch:

# Snowflake Horizon Catalog Configuration, change as per your environment

CATALOG_URI = "https://<account_identifier>.snowflakecomputing.com/polaris/api/catalog"
HORIZON_SESSION_ROLE = f"session:role:<role>"
CATALOG_NAME = "<database_name>" #provide in UPPER CASE

# Cloud Service Provider Region Configuration (where the Iceberg data is stored)
REGION = "eastus2"

# Paste the PAT you generated in Snowflake here
PAT_TOKEN = "<your_PAT_token>"

# Iceberg Version
ICEBERG_VERSION = "1.9.1"

def create_spark_session():
  """Create and configure Spark session for Snowflake Iceberg access."""
  spark = (
      SparkSession.builder
      .appName("SnowflakeIcebergReader")
      .master("local[*]")

# JAR Dependencies for Iceberg and Azure
      .config(
          "spark.jars.packages",
          f"org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:{ICEBERG_VERSION},"
          f"org.apache.iceberg:iceberg-aws-bundle:{ICEBERG_VERSION}"
          # for Azure storage, use the below package and comment above azure bundle
          # f"org.apache.iceberg:iceberg-azure-bundle:{ICEBERG_VERSION}"
      )

      # Iceberg SQL Extensions
      .config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions")
      .config("spark.sql.defaultCatalog", CATALOG_NAME)

      # Horizon REST Catalog Configuration
      .config(f"spark.sql.catalog.{CATALOG_NAME}", "org.apache.iceberg.spark.SparkCatalog")
      .config(f"spark.sql.catalog.{CATALOG_NAME}.type", "rest")
      .config(f"spark.sql.catalog.{CATALOG_NAME}.uri", CATALOG_URI)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.warehouse", CATALOG_NAME)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.credential", PAT_TOKEN)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.scope", HORIZON_SESSION_ROLE)
      .config(f"spark.sql.catalog.{CATALOG_NAME}.client.region", REGION)

      # Required for vended credentials
      .config(f"spark.sql.catalog.{CATALOG_NAME}.header.X-Iceberg-Access-Delegation", "vended-credentials")
      .config("spark.sql.iceberg.vectorization.enabled", "false")
      .getOrCreate()
  )
  spark.sparkContext.setLogLevel("ERROR")
  return spark

Wobei:

  • <account_identifier> ist Ihr Snowflake-Kontobezeichner für das Snowflake-Konto, das die Iceberg-Tabellen enthält, auf die Sie zugreifen möchten. Wie Sie diesen Bezeichner finden, erfahren Sie unter Unterstützte externe Engines und Kataloge.

  • <your_PAT_token> ist das PAT, das Sie erhalten haben. Wie Sie es erhalten, erfahren Sie unter Schritt 3: Zugriffstoken für die Authentifizierung besorgen.

  • <role> ist die Rolle in Snowflake, die mit Zugriff auf die Iceberg-Tabellen konfiguriert ist, auf die Sie zugreifen möchten. Beispiel: DATA_ENGINEER.

  • <database_name> ist der Name der Datenbank in Ihrem Snowflake-Konto, die von Snowflake verwaltete Iceberg-Tabellen enthält, auf die Sie zugreifen möchten.

    Bemerkung

    Die Eigenschaft .warehouse in Spark erwartet Ihren Snowflake-*Datenbank*namen, nicht den Namen Ihres Snowflake-Warehouses.

Wichtig

Standardmäßig ist das Codebeispiel für Apache Iceberg™-Tabellen eingerichtet, die auf Amazon S3 gespeichert sind. Wenn Ihre Iceberg-Tabellen auf Azure Storage (ADLS) gespeichert sind, führen Sie die folgenden Schritte aus:

  1. Versehen Sie die folgende Zeile mit Kommentarmarkierungen: f"org.apache.iceberg:iceberg-aws-bundle:{ICEBERG_VERSION}"

  2. Entfernen Sie die Kommentarmarkierungen in der folgenden Zeile: # f"org.apache.iceberg:iceberg-azure-bundle:{ICEBERG_VERSION}"

Verbinden mit einer externen Abfrage-Engine mit Durchsetzung der Datenrichtlinien

Schritt 7: Auf Iceberg-Tabellen zugreifen

Dieser Abschnitt enthält Codebeispiele für die Verwendung von Apache Spark™ zum Abfragen und Schreiben in Iceberg-Tabellen.

Iceberg-Tabellen abfragen

Dieser Abschnitt enthält die folgenden Code-Beispiele für die Verwendung von Apache Spark™ zur Abfrage von Iceberg-Tabellen:

  • Namespaces anzeigen

  • Namespaces verwenden

  • Tabellen anzeigen

  • Eine Tabelle abfragen

Namespaces anzeigen

spark.sql("show namespaces").show()

Namespace verwenden

spark.sql("use namespace <your_schema_name_in_snowflake>")

Tabellen anzeigen

spark.sql("show tables").show()

Eine Tabelle abfragen

spark.sql("use namespace spark_demo")
spark.sql("select * from <your_table_name_in_snowflake>").show()

Schreiben in Iceberg-Tabellen

Dieser Abschnitt enthält die folgenden Code-Beispiele für die Verwendung von Apache Spark™ zum Schreiben in Iceberg-Tabellen:

  • CREATE TABLE

  • INSERT INTO <table>

  • ALTER TABLE … ADD COLUMN

  • UPDATE TABLE … WHERE

  • DELETE TABLE … WHERE

  • TRUNCATE TABLE

  • RENAME-TABLE

  • DROP TABLE

CREATE TABLE

spark.sql("CREATE TABLE MY_TABLE (COLUMN1 INT) USING ICEBERG").show();

INSERT INTO <table>

spark.sql("INSERT INTO MY_TABLE VALUES (600)").show()

ALTER TABLE … ADD COLUMN

spark.sql("ALTER TABLE MY_TABLE ADD COLUMN COLUMN2 INT").show()

UPDATE TABLE … WHERE

spark.sql("UPDATE MY_TABLE SET COLUMN2 = 10 WHERE COLUMN1 = 100").show()

DELETE TABLE … WHERE

spark.sql("DELETE FROM MY_TABLE WHERE COLUMN2 = 10").show()

TRUNCATE TABLE

spark.sql("TRUNCATE TABLE MY_TABLE").show()

RENAME-TABLE

spark.sql("ALTER TABLE MY_TABLE RENAME TO MY_NEW_TABLE")

DROP TABLE

spark.sql("DROP TABLE MY_TABLE")

Überlegungen zum Zugriff auf Iceberg-Tabellen mit einer externen Abfrage-Engine

In diesem Abschnitt werden die Hinweise zum Zugriff auf, Abfragen und Schreiben in Iceberg-Tabellen mit einer externen Abfrage-Engine aufgeführt.

Beachten Sie die folgenden Punkte, wenn Sie mit einer externen Abfrage-Engine auf Iceberg-Tabellen zugreifen:

  • Iceberg

    • Für Tabellen in Snowflake:

      • Es werden nur von Snowflake verwaltete Iceberg-Tabellen unterstützt.

  • Freigabeangebote:

  • Netzwerke und private Konnektivität:

    • Die Verwendung von Netzwerkrichtlinien, die auf Benutzerebene festgelegt wurden, wird mit diesem Feature nicht unterstützt.

    • Für Von Snowflake verwaltete Netzwerkregeln werden statische Ausgangs-IP-Adressen nicht unterstützt.

    • Das explizite Gewähren von Zugriff auf Ihre Speicherkonten für den Horizon Catalog-Endpunkt wird nicht unterstützt. Wir empfehlen die Verwendung von privater Konnektivität für eine sichere Konnektivität von externen Engines zum Horizon Catalog und von Horizon Catalog zu Ihrem Speicherkonto.

  • Clouds:

    • Kommerziell: Diese Funktion wird nur für von Snowflake verwaltete Iceberg-Tabellen unterstützt, die in Amazon S3, Google Cloud oder Microsoft Azure für alle kommerziellen Cloudregionen gespeichert sind. S3-kompatibler Speicher, der kein AWS-Speicher ist, wird noch nicht unterstützt.

    • FedRAMP (Moderate): Dieses Feature wird für von Snowflake verwaltete Iceberg-Tabellen unterstützt, die auf FedRAMP (Moderate)- Bereitstellungen auf AWS Commercial Gov (US) in den Regionen us-east-1 und us-west-2 gespeichert sind.

    • Für Iceberg-Tabellen, die auf Amazon S3 gespeichert sind:

      • Wenn Sie SSE-KMS-Verschlüsselung verwenden möchten, wenden Sie sich an den Kundensupport oder an Ihr Kundenbetreuerteam, um Unterstützung beim Aktivieren des Zugriffs zu erhalten.

        Bemerkung

        Das Schreiben in KMS-verschlüsselte externe Volumes wird nicht unterstützt.

    • Für Iceberg-Tabellen, die auf Azure gespeichert sind:

      • Azure Virtual Network (VNet) wird nicht unterstützt.

  • Authentifizierung:

    • Bei der Schlüsselpaar-Authentifizierung wird die Schlüsselpaar-Rotation nicht unterstützt.

    • Workload Identity Federation wird von diesem Feature nicht unterstützt.

Beachten Sie die folgenden Punkte, wenn Sie Iceberg-Tabellen mit einer externen Abfrage-Engine abfragen (lesen):

  • Iceberg

    • Die Abfrage der folgenden Tabellen wird nicht unterstützt:

      • Remotetabellen

      • Native Snowflake-Tabellen

      • Extern verwaltete Iceberg-Tabellen, einschließlich Delta-basierte Iceberg-Tabellen und Snowflake-verwaltete Iceberg-Tabellen, die Sie mit Daten aus Iceberg-kompatiblen Parquet-Datendateien unter Verwendung des Tabellenbefehls COPY INTO geladen haben

    • Das Lesen von Iceberg v2-Tabellen wird unterstützt.

    • Das Lesen von Iceberg V3-Tabellen (öffentliche Vorschau) wird für die folgenden Funktionen unterstützt:

      • Variant-Datentyp

      • Zeilenherkunft

      Alle anderen Funktionen von Iceberg V3, einschließlich der Standardwerte und des Datentyps Geography, werden nicht unterstützt.

  • Zugriffssteuerung:

  • Geklonte und konvertierte Tabellen:

    • Das Lesen von geklonten oder konvertierten Tabellen wird mit automatischen Anmeldeinformationen nicht unterstützt. Um diese Tabellen zu lesen, verwenden Sie den direkten Zugriff auf den Objektspeicher.

Beachten Sie die folgenden Punkte, wenn Sie Iceberg-Tabellen mit einer externen Abfrage-Engine abfragen:

  • Tabellenoperationen:

    • Sie können keinen Basisspeicherort mit Ihrer CREATE TABLE-Anweisung angeben.

      Wenn Sie eine von Snowflake verwaltete Tabelle erstellen, ohne einen Speicherort anzugeben, erstellt Snowflake den folgenden Pfad für Ihre Tabelle: STORAGE_BASE_URL/database/schema/table_name.randomId/[data | metadata]/

    • CREATE TABLE AS SELECT (CTAS) von einer externen Engine wird nicht unterstützt.

    • Gleichheitslöschungen werden nicht unterstützt.

    • Sie können nicht in Tabellen schreiben, indem Sie Löschvorgänge auf Zeilenebene verwenden. Es wird nur der Modus „Copy-on-Write“ unterstützt.

    • Das Erstellen von Iceberg-Tags und -Zweigen wird nicht unterstützt.

    • Schreibvorgänge der externen Engine werden nur auf Iceberg Version 2 unterstützt. Das Schreiben in Tabellen der Iceberg-Version 3 (v3) (öffentliche Vorschau) wird derzeit nicht unterstützt.

    • Das Schreiben in KMS-verschlüsselte externe Volumes wird nicht unterstützt.

    • Das Schreiben in dynamische Tabellen in Snowflake wird nicht unterstützt.

    • Das Schreiben in freigegebene Iceberg-Tabellen wird nicht unterstützt.

    • Die Registrierung von Iceberg-Tabellen wird nicht unterstützt.

  • Wartungsoperationen

    • Sie können eine Tabelle nicht auf einen früheren Snapshot zurücksetzen.

    • Die Operation zum Ablaufen von Snapshots wird nicht unterstützt.

    • Sie können eine Iceberg-Tabelle nicht von v2 auf v3 aktualisieren.

  • Geklonte und konvertierte Tabellen:

    • Das Schreiben in geklonte oder konvertierte Tabellen wird mit automatischen Anmeldeinformationen nicht unterstützt. Um in diese Tabellen zu schreiben, verbinden Sie Ihre externe Abfrage-Engine direkt mit dem Objektspeicher, in dem Ihre Tabellen gespeichert sind.

    • Sie können nicht in eine Iceberg-Tabelle schreiben, die von einer extern verwalteten in eine von Snowflake verwaltete Tabelle konvertiert wurde.

  • Streams:

    • Bei Iceberg V2-Tabellen führen Copy-on-Write-Operationen dazu, dass Standardstreams eine aktualisierte oder verschobene Zeile als DELETE-Datensatz gefolgt von einemINSERT-Datensatz für dieselbe Zeile darstellen.

  • Fein abgestufte Richtlinien für die Zugriffssteuerung:

    • Das Schreiben in Tabellen, die über fein abgestufte Zugriffssteuerungsrichtlinien oder Tags verfügen, wird nicht unterstützt.