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.

Bevor Sie beginnen¶

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

Private Konnektivität (optional)¶

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. Erstellen Sie Iceberg-Tabellen.

2. Konfigurieren Sie die Zugriffssteuerung.

3. Besorgen Sie sich ein Zugriffstoken für die Authentifizierung.

4. Überprüfen Sie die Zugriffsberechtigungen für das Token.

5. (Optional) Konfigurieren Sie Datenschutzrichtlinien.

6. Verbinden Sie eine externe Abfrage-Engine mit Iceberg-Tabellen über Horizon Catalog.

7. Fragen Sie Iceberg-Tabellen ab.

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.

Eine Anweisung dazu finden Sie unter Konfigurieren der Zugriffssteuerung. Weitere Informationen zur Zugriffssteuerung in Snowflake finden Sie unter Übersicht zur Zugriffssteuerung.

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

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:

• Für Tabellen in Snowflake:

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

  • Abfragen von entfernten oder extern verwalteten Iceberg-Tabellen, einschließlich Delta Direct- und Parquet Direct-Tabellen sowie nativer Snowflake-Tabellen, werden nicht unterstützt.

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

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

• Auf Tabellen, die durch die folgenden fein abgestuften Datenrichtlinien geschützt sind, kann über die Horizon Iceberg REST API und mit Apache Spark™ zugegriffen werden:

  • Maskierungsrichtlinien

  • Tag-basierte Maskierungsrichtlinien

  • Zeilenzugriffsrichtlinien

• Snowflake-Rollen, die einen Bindestrich (-) im Rollennamen enthalten, werden nicht unterstützt, wenn Sie über den Horizon Catalog-Endpunkt auf Iceberg-Tabellen zugreifen.

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