Activer l’accès externe aux données des tables en streaming et des vues matérialisées

Si vous avez activé l’accès externe aux données à Unity Catalog, vous pouvez ajouter un accès externe aux données pour les vues matérialisées gérées par pipeline ainsi que pour les vues matérialisées et les tables de streaming autonomes. Cela permet aux clients Delta et Iceberg externes d’accéder à vos jeux de données via les API REST catalogue Unity et Iceberg, sans nécessiter de copie complète des données.

L’accès externe aux données fonctionne pour les ensembles de données gérés par des pipelines Lakeflow ainsi que pour les vues matérialisées autonomes et les tables de streaming.

Capacités

L’accès externe aux données expose les mêmes données disponibles dans Azure Databricks pour les vues matérialisées et tables de streaming gérées par pipeline et autonomes, sans créer de doublon des données. Cela donne les caractéristiques suivantes pour les performances et les fonctionnalités :

Aucune copie de données n’est requise : L’accès externe est activé sans dupliquer le jeu de données complet.
Accès externe via des API : Lisez les vues matérialisées et les tables de diffusion en continu à l’aide des API Delta Lake ou Iceberg.
Cohérence de lecture après écriture: Les lecteurs externes peuvent accéder à des données à jour après une mise à jour de l’ensemble de données, garantissant l’absence de données obsolètes. Les mises à jour sont disponibles immédiatement lors de l’actualisation.
Objet table unique : Les jeux de données apparaissent en externe sous forme de tables gérées portant le même nom que le jeu de données source dans les API du catalogue Unity.
Coût faible : Étant donné que le jeu de données complet n’est pas copié, la surcharge pour fournir un accès externe est faible.

Requirements

Les conditions requises pour vos jeux de données sont les suivantes :

Catalogue Unity : Vos tables de diffusion en continu et vues matérialisées doivent utiliser le catalogue Unity.
Version de Databricks Runtime : Vous devez utiliser Databricks Runtime 17.3 et versions ultérieures.
Mode de publication par défaut : La lisibilité externe n’est prise en charge que dans le mode de publication par défaut. Pour utiliser la lisibilité externe, migrez vers le mode de publication par défaut. Les fonctionnalités qui dépendent de métadonnées externes, telles que la vue matérialisée CDF, fonctionneront en mode de publication hérité.

Les conditions requises pour vos clients sont les suivantes :

Version de l’API Delta : Le client doit prendre en charge les API Delta Lake 4.0.0 ou ultérieures, y compris les vecteurs de suppression, et doit utiliser les API du catalogue Unity pour l’accès.
Version de l’API Iceberg : Le client peut également accéder à l’aide des API du catalogue Iceberg qui prennent en charge la spécification Iceberg v3.
Privilèges Unity Catalog : le principal qui lit les jeux de données de manière externe doit disposer du privilège EXTERNAL USE SCHEMA sur le schéma et du privilège SELECT sur la table.

Note

Si votre client ne prend pas en charge ces exigences, vous pouvez également utiliser le mode de compatibilité, qui prend en charge tous les clients Delta et Iceberg, mais nécessite la création d’une copie complète du jeu de données.

Comment activer l’accès pour un jeu de données

Il y a deux étapes pour permettre un accès externe à un jeu de données.

Activez les métadonnées externes en utilisant soit la configuration du pipeline, soit une propriété de table. Le paramètre défini au niveau de la table prime sur la configuration du pipeline lorsque les deux sont définis, et il est pris en charge à la fois pour les tables de streaming et les vues matérialisées, qu’elles soient gérées par pipeline ou autonomes.
- Configuration du pipeline : Définissez pipelines.externalMetadata.enabled sur true pour activer les métadonnées externes pour tous les ensembles de données du pipeline. Les vues matérialisées autonomes et les tables de streaming créées avec Databricks SQL n’ont pas de configuration pipeline ; Utilisez plutôt une propriété de table.
  
  Interface utilisateur des paramètres de pipeline
  
  Dans les paramètres du pipeline, suivez les étapes suivantes :
  1. Ouvrez votre pipeline, puis cliquez sur Paramètres.
  2. Sous Configuration, ajoutez une paire clé-valeur : Clépipelines.externalMetadata.enabled, Valeurtrue.
  3. Cliquez sur Enregistrer.
  Configuration JSON du pipeline
  
  Dans la configuration section de votre pipeline JSON, ajoutez :
```
{
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}
```
- Propriété du tableau : Ajoutez la propriété suivante à la définition de la table de streaming ou de la vue matérialisée. Pour les pipelines Lakeflow Connect, voir Définir les propriétés de la table Delta.
```
CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES('pipelines.externalMetadata.enabled' = 'true')
```
Après avoir enregistré la configuration, exécutez ou redémarrez le pipeline pour appliquer les modifications :
- Pipelines déclenchés : exécutez le pipeline une seule fois.
- Pipelines en continu: Arrêtez et redémarrez le pipeline.
Pour les objets SQL Databricks autonomes, utilisez CREATE OR REPLACE MATERIALIZED VIEW ou CREATE OR REFRESH STREAMING TABLE avec la propriété de table. L’instruction créer ou actualiser applique la propriété.

Si vous prévoyez de lire le jeu de données avec un client Iceberg moderne, ajoutez les propriétés UniForm Iceberg V3 suivantes en plus de la propriété de métadonnées externes. Pour les pipelines Lakeflow Connect, voir Définir les propriétés de la table Delta.

Propriété	Utilisation
`'pipelines.externalMetadata.enabled' = 'true'`	Activez l’accès externe à la table. Ce réglage au niveau de la table prime sur la configuration du pipeline lorsque les deux sont définis.
`'delta.columnMapping.mode' = 'name'`	Le mappage de colonnes est requis pour Iceberg.
`'delta.enableRowTracking' = 'true'`	Activez le suivi des lignes pour la lecture dans Iceberg.
`'delta.universalFormat.enabledFormats' = 'iceberg'`	Activer la lecture Iceberg.
`'delta.enableIcebergCompatV3' = 'true'`	Utilisez Iceberg V3 pour la lecture d’Iceberg.

CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableRowTracking' = 'true',
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg',
  'pipelines.externalMetadata.enabled' = 'true')

Pour les vues matérialisées, vous pouvez utiliser la syntaxe équivalente USING ICEBERG à la place.

CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

Pour les ensembles de données gérés par pipeline, utilisez les instructions de mise à jour de pipeline ci-dessus pour appliquer les propriétés Iceberg. Pour les objets SQL Databricks autonomes, relancez la définition de l’objet avec les propriétés mises à jour. Utilisez CREATE OR REPLACE MATERIALIZED VIEW pour une vue matérialisée ou CREATE OR REFRESH STREAMING TABLE pour une table de flux. Pour voir les propriétés de votre jeu de données, utilisez les DESCRIBE DETAIL instructions SQL.DESCRIBE EXTENDED

Dépannage de l’accès externe aux données

Si vous pensez que les métadonnées externes sont obsolètes, un principal disposant du MODIFY privilège sur la table peut déclencher manuellement la mise à jour des métadonnées lors du calcul en cluster partagé en utilisant Databricks Runtime 17.3 ou supérieur :

REPAIR TABLE <catalog>.<schema>.<table-name> SYNC METADATA;

Vous pouvez vérifier la présence des métadonnées Iceberg dans l’interface utilisateur de l’Explorateur de catalogue, sur la page des détails de la table. Sinon, exécutez les commandes suivantes dans l’éditeur SQL ou dans un notebook Azure Databricks :

DESCRIBE DETAIL <catalog>.<schema>.<table-name>;
DESCRIBE EXTENDED <catalog>.<schema>.<table-name>;

Pour une table de streaming, comparez la version des métadonnées Iceberg avec la dernière version de la table de streaming. La comparaison des versions pour les vues matérialisées n’est pas encore disponible.

Lecture de données à partir de clients externes

Les sections suivantes fournissent des exemples de lecture de votre jeu de données provenant de différents clients et environnements.

Pour les détails de configuration, voir accès client Delta et accès client Iceberg.

Utiliser l’API REST Unity avec le lecteur Delta Spark

Utilisez Apache Spark™ version 4.0 ou ultérieure. Vous pouvez télécharger à partir de https://spark.apache.org/downloads.html.

En fonction de votre fournisseur de cloud, exécutez la commande suivante pour démarrer un interpréteur de commandes Spark SQL avec Delta 4.0 et le catalogue Unity.

AWS

bin/spark-sql \
    --packages org.apache.spark:spark-hadoop-cloud_2.13:4.0.0,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.s3.impl=org.apache.hadoop.fs.s3a.S3AFileSystem \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

Azure

bin/spark-sql \
    --packages org.apache.hadoop:hadoop-azure:3.3.6,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

GCP

bin/spark-sql \
    --packages io.unitycatalog:unitycatalog-spark_2.13:0.3.1  \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFileSystem \
    --conf spark.hadoop.fs.AbstractFileSystem.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFS \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

À partir de l’interpréteur de commandes SQL, vous pouvez désormais accéder à votre jeu de données avec Spark SQL. Par exemple:
```
spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;
```

Utiliser le lecteur Snowflake Iceberg

Dans Snowflake, vous pouvez utiliser le lecteur Iceberg. Cela nécessite la prise en charge d’Iceberg v3 dans Snowflake.

Configurez le catalogue REST Iceberg dans Snowflake.

CREATE OR REPLACE CATALOG INTEGRATION my_uc_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<uc-catalog-name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<PAT>'
  )
  ENABLED = TRUE;

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = 'my_uc_int'
  CATALOG_TABLE_NAME = '<uc-table-name>';

Accédez à votre jeu de données depuis Snowflake SQL.

ALTER ICEBERG TABLE my_table REFRESH;
SELECT * FROM my_table;

Utiliser le catalogue REST Iceberg avec le lecteur Spark Iceberg

Utilisez Apache Spark™ version 4.0 ou ultérieure. Vous pouvez télécharger à partir de https://spark.apache.org/downloads.html.

Dans AWS, exécutez la commande suivante pour démarrer un interpréteur de commandes Spark SQL avec Iceberg v3.

bin/spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-4.0_2.13:1.10.0,org.apache.iceberg:iceberg-aws-bundle:1.10.0 \
  --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
  --conf spark.sql.catalog.<uc-catalog-name>=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.<uc-catalog-name>.io-impl=org.apache.iceberg.aws.s3.S3FileIO \
  --conf spark.sql.catalog.<uc-catalog-name>.type=rest \
  --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.<uc-catalog-name>.token='<PAT>' \
  --conf spark.sql.catalog.<uc-catalog-name>.warehouse=<uc-catalog-name> \
  --conf spark.sql.iceberg.vectorization.enabled=false

Accédez à votre jeu de données à partir de Spark SQL.

spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

Migrer à partir du mode de compatibilité

Si vous partagez actuellement un jeu de données à l’aide du mode de compatibilité, vous pouvez migrer vers l’utilisation de l’accès aux données externes.

Activez cette fonctionnalité en suivant les étapes décrites dans Comment activer l’accès pour un jeu de données.
Désactivez le mode de compatibilité. Voir Désactiver le mode de compatibilité

Limitations

Voici les limitations connues avec l’accès aux données externes pour les tables de streaming et les vues matérialisées.

Écritures externes : Les écritures externes dans les jeux de données de pipeline ne sont pas prises en charge.
Accès par chemin : Les lecteurs externes qui nécessitent un accès par chemin (lecture directe depuis un emplacement de stockage au lieu de l’interface de l’API UC) ne sont pas pris en charge. Pour prendre en charge l’accès basé sur le chemin, vous pouvez utiliser le mode de compatibilité, qui prend en charge l’accès basé sur le chemin, mais nécessite une copie complète du jeu de données.
Fonctionnalités de sécurité : La prise en charge de la sécurité au niveau des lignes ou du masquage au niveau des colonnes à partir de lectures externes n’est pas prise en charge.
Voyage dans le temps :Le voyage dans le temps via cette fonctionnalité n’est pas pris en charge.
Validations de catalogue (bêta) :les validations de catalogue ne sont pas compatibles avec l’accès aux données externes. Pour utiliser un accès externe aux données sur une table de streaming ou une vue matérialisée, vous devez d’abord désactiver les commits de catalogue.
Fabric: La lecture depuis Microsoft Fabric n’est pas prise en charge.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-08-18