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. Verbinden Sie eine externe Abfrage-Engine mit Iceberg-Tabellen über Horizon Catalog.

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

You specify this access token later when you connect an external query engine to Iceberg tables through Horizon Catalog.

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

• External OAuth

• Schlüsselpaar-Authentifizierung

• Programmatic access token (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>'

Step 4: Verify access token permissions¶

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"

Step 5: Connect an external query engine to Iceberg tables through Horizon Catalog¶

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 dazu finden Sie unter folgenden Themen:

• 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

Step 6: Query Iceberg tables¶

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 Azure für alle öffentlichen Cloudregionen gespeichert sind. S3-kompatibler Speicher, der kein AWS-Speicher ist, wird noch nicht unterstützt.

• Sie können eine Iceberg-Tabelle nicht über die REST API von Horizon Iceberg abfragen, wenn die folgenden Richtlinien für fein abgestufte Zugriffssteuerung (FGAC) für die Tabelle definiert sind:

  • Zeilenzugriffsrichtlinien

  • Sicherheit auf Spaltenebene

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