Abfragen von Apache Iceberg™-Tabellen mit einer externen Engine über Snowflake Horizon Catalog¶

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.

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.

Voraussetzungen¶

Rufen Sie den Kontobezeichner für Ihr Snowflake-Konto ab, das die abzufragenden Iceberg-Tabellen 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.

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.

Workflow für das Abfragen von Iceberg-Tabellen mithilfe einer externen Abfrage-Engine¶

Um Iceberg-Tabellen mithilfe einer externen Abfrage-Engine abzufragen, führen Sie die folgenden Schritte aus:

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

Schritt 1: Iceberg-Tabellen erstellen¶

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

• Tutorial: Ihre erste Apache Iceberg™-Tabelle erstellen: In diesem Tutorial wird erläutert, wie Sie eine Datenbank erstellen, eine von Snowflake verwaltete Iceberg-Tabelle erstellen und Daten in die Tabelle laden.

• Eine von Snowflake verwaltete Iceberg-Tabelle erstellen: Beispielcode für das Erstellen einer von Snowflake verwalteten Iceberg-Tabelle.

Schritt 2: Zugriffssteuerung konfigurieren¶

In diesem Schritt konfigurieren Sie die Zugriffssteuerung für die von Snowflake verwalteten Iceberg-Tabellen, die Sie mit einer externen Abfrage-Engine abfragen 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.

GRANT USAGE ON EXTERNAL VOLUME my_ext_vol TO ROLE data_engineer;

CREATE OR REPLACE ROLE data_engineer;

GRANT USAGE ON EXTERNAL VOLUME my_ext_vol TO ROLE data_engineer;

GRANT USAGE,MONITOR ON DATABASE iceberg_test_db TO ROLE data_engineer;
GRANT USAGE,MONITOR 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;

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

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

• Schlüsselpaar-Authentifizierung

• Programmgesteuertes Zugriffstoken (PAT)

GRANT ROLE ENGINEER to user my_service_user;

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

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>'

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

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>'

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

• Abrufen der Metadaten für eine Tabelle

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"

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

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"

(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.

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

• Verbinden über ein programmgesteuertes Zugriffstoken (PAT)

# 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

# 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

Schritt 7: Iceberg-Tabellen abfragen¶

Dieser Schritt 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

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

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

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

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

Überlegungen zum Abfragen von Iceberg-Tabellen mit einer externen Abfrage-Engine¶

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

• Iceberg

  • Für Tabellen in Snowflake:

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

    • 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

  • Sie können Iceberg-Tabellen abfragen, aber nicht darin schreiben.

  • Die externen Lesevorgänge werden nur auf Iceberg Version 2 oder früher unterstützt.

• Zugriffssteuerung:

  • Auf Tabellen, die durch die folgenden fein abgestuften Datenrichtlinien geschützt sind, kann über Apache Spark™ über Snowflake Horizon Catalog zugegriffen werden:

    • Maskierungsrichtlinien

    • Tag-basierte Maskierungsrichtlinien

    • Zeilenzugriffsrichtlinien

    Weitere Informationen dazu finden Sie unter Durchsetzen von Datenschutzrichtlinien bei der Abfrage von Apache Iceberg™-Tabellen von Apache Spark™.

• 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.

• Freigabeangebote:

  • Iceberg-Tabellen, die Sie über Automatische Ausführung für Freigabeangebote freigeben, sind nicht über die Horizon Iceberg REST-Katalog-API des Verbraucherkontos zugänglich.

• Clouds:

  • 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.

  • 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.

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

    • Virtuelles Azure-Netzwerk (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.