Accéder aux tables Apache Iceberg™ avec un moteur externe via Snowflake Horizon Catalog¶

Interroger des tables Iceberg¶

En connectant un moteur de requête externe à des tables Iceberg via Horizon Catalog, vous pouvez effectuer les tâches suivantes :

• Utiliser n’importe quel moteur de requête externe qui prend en charge le protocole REST Iceberg ouvert pour interroger ces tables, comme Apache Spark™.

• Interrogez des tables Iceberg gérées par Snowflake existantes et nouvelles dans un compte Snowflake nouveau ou existant à l’aide d’un seul point de terminaison Horizon Catalog.

• Interrogez les tables en utilisant vos utilisateurs, rôles, politiques et authentifications existants dans Snowflake.

• Utilisez des identifiants de connexion distribués.

Pour plus d’informations sur Snowflake Horizon Catalog, voir Catalogue Snowflake Horizon.

Écriture dans les tables Iceberg¶

L’écriture dans les tables Iceberg en utilisant un moteur de requête externe via Horizon Catalog est en aperçu public. Pour écrire dans des tables, suivez le workflow pour l’accès aux tables Iceberg via un moteur de requête externe . Lorsque vous configurez le contrôle d’accès, assurez-vous de configurer l’accès en écriture à vos tables.

Ensuite écrivez dans les tables Iceberg.

Le schéma suivant montre des moteurs de requête externes lisant et écrivant dans les tables Iceberg gérées par Snowflake via Horizon Catalog et Snowflake lisant et écrivant dans ces tables :

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 auxquelles vous souhaitez accéder. 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.

Workflow pour accéder aux tables Iceberg à l’aide d’un moteur de requête externe¶

Pour accéder aux 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. Interrogez les tables Iceberg ou:ref:écrivez dans les tables Iceberg <label-tables_iceberg_query_using_external_query_engine_snowflake_horizon_write_to_iceberg_tables>

É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 y accéder 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 auxquelles vous souhaitez accéder 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 plus d’informations, consultez les sections suivantes :

• Configurer l’accès en lecture à vos tables Iceberg

• Configurer l’accès en écriture à vos tables Iceberg

CREATE OR REPLACE ROLE data_engineer;

GRANT USAGE ON DATABASE iceberg_test_db TO ROLE data_engineer;
GRANT USAGE 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 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 accéder aux 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 : Accéder aux tables Iceberg¶

Cette section comprend des exemples de code permettant d’utiliser Apache Spark™ pour interroger et écrire dans des tables Iceberg.

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

spark.sql("CREATE TABLE MY_TABLE (COLUMN1 INT) USING ICEBERG").show();

spark.sql("INSERT INTO MY_TABLE VALUES (600)").show()

spark.sql("ALTER TABLE MY_TABLE ADD COLUMN COLUMN2 INT").show()

spark.sql("UPDATE MY_TABLE SET COLUMN2 = 10 WHERE COLUMN1 = 100").show()

spark.sql("DELETE FROM MY_TABLE WHERE COLUMN2 = 10").show()

spark.sql("TRUNCATE TABLE MY_TABLE").show()

spark.sql("ALTER TABLE MY_TABLE RENAME TO MY_NEW_TABLE")

spark.sql("DROP TABLE MY_TABLE")

Considérations relatives à l’accès des tables Iceberg avec un moteur de requête externe¶

Cette section répertorie les considérations relatives à l’accès, à l’interrogation et à l’écriture dans les 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.

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

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

• Clouds :

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

  • FedRAMP (modéré) : Cette fonctionnalité est prise en charge pour les tables Iceberg gérées par Snowflake qui sont stockées sur les déploiements FedRAMP (modérés) sur AWS Gov Commercial (US) dans les régions us-east-1 et us-west-2.

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

      Note

      L’écriture dans les volumes externes chiffrés par KMS n’est pas prise en charge.

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

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

• Iceberg

  • 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

  • La lecture des tables Iceberg v2 est prise en charge.

  • La lecture des tables Iceberg V3 (avant-première publique) est prise en charge pour les fonctionnalités suivantes :

    • Type de données de variante

    • Lignée de lignes

    Toutes les autres fonctionnalités Iceberg V3, y compris les valeurs par défaut et le type de données géographique, ne sont pas prises en charge.

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

• Tables clonées et converties :

  • La lecture des tables clonées ou converties n’est pas prise en charge avec les identifiants de connexion distribués. Pour lire ces tables, utilisez un accès direct au stockage d’objets.

Tenez compte des points suivants lorsque vous écrivez sur les tables Iceberg avec un moteur de requête externe :

• Opérations de table :

  • Vous ne pouvez pas spécifier un emplacement de base avec votre instruction CREATETABLE.

    Lorsque vous créez une table gérée par Snowflake sans spécifier d’emplacement de base, Snowflake construit le chemin suivant pour votre table : STORAGE_BASE_URL/database/schema/table_name.randomId/[data | metadata]/

  • CREATE TABLE AS SELECT (CTAS) depuis un moteur externe n’est pas pris en charge.

  • Les suppressions d’égalité ne sont pas prises en charge.

  • Vous ne pouvez pas écrire dans des tables en utilisant des suppressions au niveau des lignes ; seul le mode copie sur écriture est pris en charge.

  • La création de balises et de branches Iceberg n’est pas prise en charge.

  • Les écritures du moteur externe ne sont prises en charge que sur la version 2 d’Iceberg. L’écriture dans des tables Iceberg version 3 (v3) (avant-première publique) n’est actuellement pas prise en charge.

  • L’écriture dans les volumes externes chiffrés par KMS n’est pas prise en charge.

  • L’écriture dans des tables dynamiques dans Snowflake n’est pas prise en charge.

  • L’écriture dans des tables Iceberg partagées n’est pas prise en charge.

  • L’enregistrement des tables Iceberg n’est pas pris en charge.

• Opérations de maintenance

  • Vous ne pouvez pas restaurer une table sur un instantané précédent.

  • L’opération d’expiration de l’instantané n’est pas prise en charge.

  • Vous ne pouvez pas mettre à niveau une table Iceberg de v2 vers v3.

• Tables clonées et converties :

  • L’écriture dans des tables clonées ou converties n’est pas prise en charge avec les identifiants de connexion distribués. Pour écrire dans ces tables, connectez votre moteur de requête externe directement au stockage d’objets dans lequel vos tables sont stockées.

  • Vous ne pouvez pas écrire dans une table Iceberg qui a été convertie de gérée en externe à gérée par Snowflake.

• Flux :

  • Sur les tables Iceberg V2, les opérations de copie sur écriture font que les flux standard représentent une ligne mise à jour ou déplacée comme un enregistrement DELETE suivi d’un enregistrement INSERT pour la même ligne.

• Politiques de contrôle d’accès détaillées :

  • L’écriture dans des tables disposant de politiques de contrôle d’accès détaillées ou de balises n’est pas prise en charge.