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.

Moteurs et catalogues externes pris en charge¶

Les tableaux suivants, bien que non exhaustifs, présentent de nombreux moteurs et catalogues externes qui s’intègrent dans l’API Horizon Iceberg REST Catalog. Cette intégration permet d’accéder aux tables Iceberg gérées par Snowflake via des systèmes externes.

Conditions préalables¶

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

(Facultatif) Connectivité privée¶

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éer des tables Iceberg

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

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

4. Vérifier les autorisations du jeton d’accès

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

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

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

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;

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

Vous spécifierez ce jeton d’accès plus tard lorsque vous connectez un moteur de requête externe aux tables Iceberg via 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

• Jeton d’accès programmatique (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>'

Étape 4 : Vérifier les autorisations du jeton d’accès¶

À 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™.

Étape 6 : Connecter un moteur de requête externe aux tables Iceberg via Horizon Catalog¶

Dans cette étape, vous connectez un moteur de requête externe aux tables Iceberg via Horizon Catalog. Grâce à cette connexion, vous pouvez interroger les tables en utilisant le moteur de requête externe.

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

L’exemple de code dans cette étape montre comment établir une connexion dans Spark. L’exemple de code est dans PySpark. Pour plus d’informations, consultez les sections suivantes :

• 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

Étape 7 : Interroger des tables Iceberg¶

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 :

• Iceberg

  • Pour les tables dans Snowflake :

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

    • La requête dans les tables suivantes n’est pas prise en charge :

      • Tables distantes

      • Tables natives Snowflake

      • Tables Iceberg gérées en externe, y compris les tables Iceberg basées sur Delta et les tables Iceberg gérées par Snowflake que vous avez chargées avec des données provenant de fichiers de données Parquet compatibles avec Iceberg en utilisant la commande de table COPY INTO

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

• Contrôle d’accès :

  • Les tables protégées par les politiques de données à granularité fine suivantes sont accessibles via Apache Spark™ via Snowflake Horizon Catalog :

    • Politiques de masquage

    • Politiques de masquage basées sur les balises

    • Politiques d’accès aux lignes

    Pour plus d’informations, voir Renforcer les politiques de protection des données lors de l’interrogation de tables Apache Iceberg™ Apache Spark™.

• Réseau et connexion privée :

  • L’utilisation de politiques réseau définies au niveau de l’utilisateur n’est pas prise en charge avec cette fonctionnalité.

  • Pour Règles réseau gérées par Snowflake, les adresses IP de sortie statiques ne sont pas prises en charge.

  • 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 votre compte de stockage.

• Annonces :

  • Les tables Iceberg que vous partagez via l’exécution automatique pour les annonces ne sont pas accessibles via l’API Horizon Iceberg REST Catalog du compte consommateur.

• Clouds :

  • Cette fonctionnalité n’est prise en charge que pour les tables Iceberg gérées par Snowflake et stockées sur Amazon S3, Google Cloud ou Azure pour toutes les régions de Cloud. Le stockage non AWS compatible avec S3 n’est pas encore pris en charge.

  • Pour les tables Iceberg stockées sur Amazon S3 :

    • Si vous voulez utiliser le chiffrement SSE-KMS, contactez le support client ou l’équipe de votre compte pour obtenir de l’aide sur l’activation de l’accès.

  • Pour les tables Iceberg stockées sur Azure :

    • Le réseau virtuel Azure (VNet) n’est pas pris en charge.

• Authentification :

  • Pour l’authentification par paire de clés, la rotation de la paire de clés n’est pas prise en charge.

  • La fédération d’identité de charge de travail n’est pas prise en charge avec cette fonctionnalité.