Aller au contenu principal
Dernière mise à jour le

Activer l'accès aux données externes aux tables de streaming et aux vues matérialisées

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

L'accès aux données externes fonctionne pour les datasets gérés par les Lakeflow pipelines ainsi que pour les vues matérialisées et les tables de streaming autonomes.

Fonctionnalités​

L’utilisation de l’accès aux données externes expose les mêmes données que celles disponibles dans Databricks pour les vues matérialisées et les tables de streaming gérées par pipeline ou autonomes, sans créer de doublon des données. Ceci donne les caractéristiques suivantes en matière de performance et de fonctionnalité :

  • Aucune copie de données requise : l'accès externe est activé sans dupliquer l'intégralité du dataset.
  • Accès externe via les APIs : lisez les vues matérialisées et les tables de streaming à l'aide des APIs Delta Lake ou Iceberg.
  • Cohérence lecture-après-écriture : les lecteurs externes peuvent accéder aux données à jour après une mise à jour du dataset, garantissant ainsi l'absence d'obsolescence. Les mises à jour sont disponibles immédiatement après un refresh.
  • Objet de table unique : Les datasets apparaissent en externe comme des tables gérées avec le même nom que le dataset source au sein des APIs Unity Catalog.
  • **Faible coût :** comme le dataset complet n’est pas copié, le surcoût lié à la fourniture d’un accès externe est faible.

Exigences​

Les exigences pour vos datasets sont :

  • Unity Catalog : Vos tables de streaming et vues matérialisées doivent utiliser Unity Catalog.
  • Version de Databricks Runtime : vous devez utiliser Databricks Runtime 17,3 ou une version ultérieure.
  • Mode de publication default : la lisibilité externe n'est prise en charge qu'en mode de publication default. Pour utiliser la lisibilité externe, migrez vers le mode de publication default. Les fonctionnalités qui dépendent de métadonnées externes, telles que le CDF des vues matérialisées, fonctionneront en mode de publication hérité.

Les exigences de vos clients sont :

  • Version d'API Delta : Le client doit prendre en charge les API Delta Lake 4.0.0 ou supérieures, y compris les vecteurs de suppression, et doit utiliser les API du catalogue Unity Catalog pour l'accès.
  • Version de l'API Iceberg : Le client peut également y accéder en utilisant les APIs du catalogue Iceberg qui prennent en charge la spécification Iceberg v3 .
  • Privilèges Unity Catalog : Le principal lisant les datasets en externe doit disposer du privilège EXTERNAL USE SCHEMA sur le schéma et du SELECT privilège sur la table.
remarque

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

Comment activer l'accès à un dataset​

Il y a deux étapes pour activer l'accès externe à un dataset.

  1. Activez les métadonnées externes en utilisant soit la configuration du pipeline, soit une propriété de table. Le paramètre au niveau de la table prévaut 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 gérées par le pipeline et autonomes.

    • Configuration du pipeline : définissez pipelines.externalMetadata.enabled sur true pour activer les métadonnées externes pour tous les datasets du pipeline. Les vues matérialisées et les tables de streaming autonomes créées avec Databricks SQL n’ont pas de configuration de pipeline ; utilisez plutôt une propriété de table.

In the pipeline settings, complete the following steps:

  1. Open your pipeline and click Settings.
  2. Under Configuration, add a key-value pair: Key pipelines.externalMetadata.enabled, Value true.
  3. Click Save.

  • Propriété de table : 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, consultez Définir les propriétés de table Delta.

    SQL
    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 fois.
  • Pipelines continus : Arrêtez et redémarrez le pipeline.

Pour les objets Databricks SQL autonomes, utilisez CREATE OR REPLACE MATERIALIZED VIEW ou CREATE OR REFRESH STREAMING TABLE avec la propriété de table. L'instruction create or refresh applique la propriété.

  1. Si vous prévoyez de lire le dataset 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, consultez Définir les propriétés de table Delta.

Propriété

Utilisation

'pipelines.externalMetadata.enabled' = 'true'

Activer l'accès externe pour la table. Ce paramètre au niveau de la table prévaut 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'

Activer le suivi des lignes pour les lectures Iceberg.

'delta.universalFormat.enabledFormats' = 'iceberg'

Activer les lectures Iceberg.

'delta.enableIcebergCompatV3' = 'true'

Utilisez Iceberg V3 pour les lectures Iceberg.

Propriété

Utilisation

'pipelines.externalMetadata.enabled' = 'true'

Activer l'accès externe pour la table. Ce paramètre au niveau de la table prévaut 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'

Activer le suivi des lignes pour les lectures Iceberg.

'delta.universalFormat.enabledFormats' = 'iceberg'

Activer les lectures Iceberg.

'delta.enableIcebergCompatV3' = 'true'

Utilisez Iceberg V3 pour les lectures Iceberg.

SQL
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 USING ICEBERG équivalente à la place.

SQL
CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

Pour les datasets gérés par pipeline, utilisez les instructions de mise à jour du pipeline ci-dessus pour appliquer les propriétés Iceberg. Pour les objets Databricks SQL autonomes, réexécutez 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 streaming. Pour voir les propriétés de votre dataset, utilisez les instructions SQL DESCRIBE DETAIL ou DESCRIBE EXTENDED.

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

Si vous pensez que les métadonnées externes sont obsolètes, un principal disposant du privilège MODIFY sur la table peut manuellement Trigger la mise à jour des métadonnées sur le compute de cluster partagé en utilisant Databricks Runtime 17.3 ou version ultérieure :

SQL
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 Catalog Explorer sur la page des détails de la table. Alternativement, exécutez les commandes suivantes dans l'éditeur SQL ou un Notebook Databricks :

SQL
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 de versions pour les vues matérialisées n'est pas encore disponible.

Lecture des données à partir de clients externes​

Les sections suivantes fournissent des exemples sur la façon de lire votre dataset à partir de différents clients et environnements.

Pour plus de détails sur la configuration, consultez l'accès client Delta et l'accès client Iceberg.

Utiliser l'API REST d'Unity avec le lecteur Spark Delta​

Utilisez Apache Spark™ version 4.0 ou ultérieure. Vous pouvez download sur https://spark.apache.org/downloads.html.

  1. Selon votre fournisseur cloud, exécutez la commande suivante pour start un Shell Spark SQL avec Delta 4.0 et Unity Catalog.
Shell
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>

  1. À partir du Shell SQL, vous pouvez désormais accéder à votre dataset avec Spark SQL. Par exemple :

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

Utilisez le lecteur Snowflake Iceberg​

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

  1. Configurez le catalogue Iceberg REST dans Snowflake.

    SQL
    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>';

  2. Accédez à votre dataset depuis Snowflake SQL.

    SQL
    ALTER ICEBERG TABLE my_table REFRESH;
    SELECT * FROM my_table;

Utilisez le catalogue Iceberg REST avec le lecteur Spark Iceberg​

Utilisez Apache Spark™ version 4.0 ou ultérieure. Vous pouvez download sur https://spark.apache.org/downloads.html.

  1. Dans AWS, exécutez la commande suivante pour start un Shell Spark SQL avec Iceberg v3.

    Shell
    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

  2. Accédez à votre dataset depuis Spark SQL.

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

Migration depuis le mode de compatibilité​

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

  1. Activez cette fonctionnalité en suivant les étapes décrites dans Comment activer l'accès pour un dataset.
  2. Désactiver le mode de compatibilité. Consulter Désactiver le Mode de compatibilité

Limitations​

Les limitations connues suivantes concernent l'accès aux données externes pour les tables de streaming et les vues matérialisées.

  • Écritures externes : les écritures externes vers les dataset de pipeline ne sont pas prises en charge.
  • Accès basé sur le chemin d’accès : Les lecteurs externes qui nécessitent un accès basé sur le chemin d’accès (lecture directe via un emplacement de stockage au lieu de l’interface 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 dataset.
  • 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.
  • Time travel : le time travel via cette fonctionnalité n'est pas pris en charge.
  • Commits de catalogue (bêta) : Les commits de catalogue ne sont pas compatibles avec l’accès aux données externes. Pour utiliser l’accès aux données externes sur une table de streaming ou une vue matérialisée, vous devez d’abord désactiver les commits de catalogue.
  • Fabric : La lecture à partir de Microsoft Fabric n'est pas prise en charge.
Sur cette page