Tables de requêtes Apache Iceberg™ avec un moteur externe via Snowflake Horizon Catalog¶

Facturation¶

• API REST Iceberg de Horizon Catalog est disponible dans toutes les éditions de Snowflake.

• Les requêtes API sont facturées à 0,5 crédit par million d’appels et sont facturées comme des services Cloud.

• Pour l’accès aux données interrégionales, des frais standard de sortie des données interrégionales, comme indiqué dans la Table de consommation du service Snowflake sont applicables.

Avant de commencer¶

Récupérez l’identificateur de compte de votre compte Snowflake contenant les tables Iceberg que vous souhaitez interroger. Pour obtenir des instructions, voir Identificateurs de compte. Vous spécifiez cet identificateur lorsque vous connectez un moteur de requête externe à vos tables Iceberg.

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

Connectivité privée (en option)¶

Pour une connectivité sécurisée, envisagez de configurer la connectivité privée entrante et sortante pour votre compte Snowflake lorsque vous accédez au point de terminaison Horizon Catalog.

Procédure d’interrogation des tables Iceberg à l’aide d’un moteur de requête externe¶

Pour interroger des tables Iceberg en utilisant un moteur de requête externe, procédez comme suit :

1. Créez des tables Iceberg.

2. Configurez le contrôle d’accès.

3. Obtenez un jeton d’accès pour l’authentification.

4. Verify access token permissions.

5. (Facultatif) Configurez des politiques de protection des données.

6. Connectez un moteur de requête externe aux tables Iceberg via Horizon Catalog.

7. Interrogez des tables Iceberg.

Étape 1 : Créer des tables Iceberg¶

Dans cette étape, vous créez des tables Iceberg gérées par Snowflake qui utilisent Snowflake comme catalogue, afin de pouvoir les interroger avec un moteur de requête externe. Pour obtenir des instructions, reportez-vous aux rubriques suivantes :

• Tutoriel : Créer votre première table Apache Iceberg™ : Un tutoriel qui montre comment créer une base de données, créer une table Iceberg gérée par Snowflake et charger des données dans la table.

• Créer une table Iceberg gérée par Snowflake : Exemple de code pour créer une table Iceberg gérée par Snowflake.

Étape 2 : Configurer le contrôle d’accès¶

Dans cette étape, vous configurez le contrôle d’accès pour les tables Iceberg gérées par Snowflake que vous souhaitez interroger avec un moteur de requête externe. Par exemple, vous pouvez configurer les rôles suivants dans Snowflake :

• Rôle DATA_ENGINEER, qui a accès à tous les schémas et à toutes les tables Iceberg gérées par Snowflake dans une base de données.

• Rôle DATA_ANALYST, qui a accès à un schéma de la base de données et a accès uniquement à deux tables Iceberg gérées par Snowflake dans ce schéma.

Pour obtenir des instructions, voir Configuration du contrôle d’accès. Pour plus d’informations sur le contrôle d’accès dans Snowflake, voir Aperçu du contrôle d’accès.

Étape 3 : Obtenir un jeton d’accès pour l’authentification¶

Dans cette étape, vous obtenez un jeton d’accès, que vous devez avoir pour vous authentifier auprès du point de terminaison Horizon Catalog de votre compte Snowflake. Vous devez obtenir un jeton d’accès pour chaque utilisateur (service ou humain) et rôle configuré avec accès aux tables Iceberg gérées par Snowflake. Par exemple, vous devez obtenir un jeton d’accès pour un utilisateur avec le rôle DATA_ENGINEER et un autre utilisateur avec le rôle DATA_ANALYST.

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

Vous pouvez obtenir un jeton d’accès en utilisant l’une des options d’authentification suivantes :

• OAuth externe

• Authentification par paire de clés

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

À cette étape, vous vérifiez les autorisations pour le jeton d’accès que vous avez obtenu à l’étape précédente.

• Vérifier l’accès au point de terminaison IRC Horizon

• Récupérer les métadonnées d’une table

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"

(Facultatif) Étape 5 : Configurer des politiques de protection des données¶

Dans cette étape, vous configurez des politiques de protection des données pour les tables Iceberg. Si vous n’avez pas de tables à protéger à l’aide de politiques de données Snowflake, vous pouvez passer à l’étape suivante.

Pour obtenir des instructions sur la configuration des politiques de protection des données, consultez Configurer des politiques de protection des données sur les tables Iceberg accessibles via l’API REST Horizon Iceberg et en utilisant Apache Spark™.

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

In this step, you connect an external query engine to Iceberg tables through Horizon Catalog. With this connection, you can query the tables by using the external query engine.

Les moteurs externes utilisent le point de terminaison Apache Iceberg™ REST exposé par Snowflake. Pour votre compte Snowflake, ce point de terminaison a le format suivant :

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

The example code in this step shows how to set up a connection in Spark, and the example code is in PySpark. For more information, see the following sections:

• Se connecter à l’aide de OAuth externe ou de l’authentification par paire de clés

• Se connecter à l’aide d’un jeton d’accès programmatique (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 7: Query Iceberg tables¶

Cette étape fournit les exemples de code suivants pour utiliser Apache Spark™ afin d’interroger des tables Iceberg :

• Afficher les espaces de noms

• Utiliser des espaces de noms

• Afficher les tables

• Interroger une table

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

Considérations relatives à l’interrogation de tables Iceberg avec un moteur de requête externe¶

Tenez compte des points suivants lorsque vous interrogez des tables Iceberg avec un moteur de requête externe :

• Pour les tables dans Snowflake :

  • Seules les tables Iceberg gérées par Snowflake sont prises en charge.

  • Les requêtes sur des tables Iceberg distantes ou gérées en externe, y compris les tables Delta Direct et Parquet Direct et les tables natives Snowflake, ne sont pas prises en charge.

• Vous pouvez effectuer des requêtes, mais pas écrire dans des tables Iceberg.

• Les lectures externes ne sont prises en charge que sur la version 2 ou antérieure d’Iceberg.

• This feature is only supported for Snowflake-managed Iceberg tables that are stored on Amazon S3, Google Cloud, or Microsoft Azure for all public cloud regions. S3-compatible non-AWS storage is not yet supported.

• Les tables protégées par les politiques de données à granularité fine suivantes sont accessibles via l’API REST Horizon Iceberg et en utilisant Apache Spark™ :

  • Masking policies

  • Politiques de masquage basées sur les balises

  • Politiques d’accès aux lignes

• Les rôles Snowflake qui incluent le caractère tiret (-) dans le nom de rôle ne sont pas pris en charge lorsque vous accédez aux tables Iceberg via le point de terminaison Horizon Catalog.

• L’octroi explicite de l’accès au point de terminaison Horizon Catalog à vos comptes de stockage n’est pas pris en charge. Nous vous recommandons d’utiliser une connexion privée pour sécuriser la connexion entre les moteurs externes et Horizon Catalog, ainsi qu’entre Horizon Catalog et le compte de stockage.