Mode de compatibilité

info

Aperçu

Cette fonctionnalité est en aperçu public.

À l'aide du Mode de compatibilité, vous pouvez lire les tables gérées par Unity Catalog, les vues matérialisées et les tables de streaming à partir de systèmes externes tout en maintenant des performances optimales sur Databricks. Cette fonctionnalité génère automatiquement des versions en lecture seule de vos tables qui peuvent être accessibles par n'importe quel client Delta Lake ou Iceberg.

Présentation

Lorsqu'il est activé sur une table gérée, une table de streaming ou une vue matérialisée, le Mode de compatibilité génère une version en lecture seule de votre table à un emplacement choisi. Cette version de compatibilité inclut les métadonnées v1 pour les formats Delta Lake et Iceberg, offrant les capacités suivantes :

• Interopérabilité avec tout client Delta Lake : Lisez vos tables gérées, y compris les tables de streaming ou les vues matérialisées, à partir de clients comme Amazon Athena, Snowflake et Amazon Redshift, directement depuis le stockage ou via l'API REST Unity
• Interopérabilité avec tout client Iceberg : Lisez vos tables gérées, y compris les tables en streaming ou les vues matérialisées, à partir de clients Iceberg comme Apache Spark, Apache Trino et Snowflake via le catalogue REST Iceberg
• Automatisation facile à configurer : Automatisez les refresh de données et de métadonnées pour les versions de compatibilité, avec la possibilité de configurer des intervalles de refresh quasi en temps réel.

Prérequis

Pour activer le mode de compatibilité sur une table, vous devez utiliser Unity Catalog. Seules les tables de streaming Unity Catalog, les vues matérialisées Unity Catalog et les tables gérées Unity Catalog sont prises en charge. Les tables externes Unity Catalog ne sont pas prises en charge.

De plus, vérifiez que vous disposez d'un emplacement externe enregistré dans Unity Catalog avec les paramètres et les autorisations appropriés :

• L'emplacement cible doit exister dans votre compte de stockage et être vide.
• L'emplacement cible ou l'un de ses dossiers parents doit être enregistré comme emplacement externe dans Unity Catalog.
• Vous devez disposer du privilège CREATE EXTERNAL TABLE pour l'emplacement externe.
• L'emplacement cible et tout dossier parent ou enfant ne doivent pas avoir été utilisés comme emplacement en Mode de compatibilité pour une autre table au cours des 7 derniers jours.

Activer le Mode de compatibilité sur les tables

Pour les tables de streaming, les vues matérialisées et les clones superficiels gérés, définissez les propriétés de table suivantes au moment de la création de la table :

SQL

CREATE [STREAMING TABLE | MATERIALIZED VIEW | TABLE] my_catalog.my_schema.my_table
TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

Pour les tables gérées par Unity Catalog uniquement, vous pouvez également activer le Mode de compatibilité lorsque vous modifiez une table existante :

SQL

-- For existing managed tables
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

Cela prend jusqu'à une heure pour générer une version de compatibilité pour la première fois. Vous pouvez refresh manuellement la table immédiatement pour confirmer que cela fonctionne.

remarque

Vous devez spécifier le nom complet de la table en trois parties (catalog.schema.table_name). Par exemple, pour users.john.my_table, usersest le catalogue et john est le schéma.

Vérifiez si le Mode de compatibilité est activé

Pour vérifier que le Mode de compatibilité est activé sur votre table, vérifiez que la propriété de table delta.universalFormat.enabledFormats = 'compatibility' existe. Vous pouvez afficher cette propriété dans l'interface utilisateur de l'Explorateur de catalogues sur la tab détails de votre table.

Vous pouvez également exécuter les commandes SQL suivantes dans un notebook :

SQL

DESC DETAIL my_catalog.my_schema.my_table
DESC EXTENDED my_catalog.my_schema.my_table

Recherchez ces propriétés dans le résultat :

• delta.universalFormat.enabledFormats: "compatibility" – Indique que le Mode de compatibilité est activé
• delta.universalFormat.compatibility.location – Indique l'emplacement de la version du Mode de Compatibilité

Configurer les intervalles de refresh

Pour les tables gérées par Unity Catalog, vous pouvez configurer la fréquence à laquelle la version du Mode de compatibilité est rafraîchie en définissant l'intervalle de refresh :

SQL

-- Evaluate whether a refresh is needed after every commit (fastest)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '0 MINUTES'
)

-- Refresh hourly (default)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '1 HOUR'
)

L'intervalle de refresh par default est de 1 HOUR. Définir l'intervalle de refresh en dessous d'une heure n'est pas recommandé, et n'entraînera pas de refreshes plus fréquentes. L'exception est lorsque vous définissez l'intervalle de refresh sur 0 MINUTES. Dans ce cas, Databricks vérifie les modifications après chaque commit et déclenche un refresh si nécessaire.

Pour les tables de streaming et les vues matérialisées, un intervalle de refresh n'est pas requis. 0 MINUTES is the default value.

remarque

Les modifications qui ont un impact significatif sur les temps de refresh (tels que le renommage de colonnes ou l'activation de l'élargissement de type) sont effectuées toutes les heures, quel que soit l'intervalle de refresh cible.

refresh manuel

Pour Trigger manuellement un refresh de la version de compatibilité :

SQL

REFRESH [TABLE | STREAMING TABLE | MATERIALIZED VIEW] my_catalog.my_schema.my_table SYNC UNIFORM

Le refresh manuel est utile pour vérifier que le Mode de compatibilité fonctionne correctement, ou pour garantir que votre version de compatibilité est à jour avant une lecture ultérieure. Cependant, attendre les refresh automatiques peut être plus rentable.

Surveiller l'état de génération des données et des métadonnées

Le Mode de compatibilité génère automatiquement et de manière asynchrone des données et des métadonnées. Pour les tables gérées par Unity Catalog, la génération a lieu toutes les heures par default, ou en fonction de votre intervalle de refresh configuré. Pour les tables de streaming et les vues matérialisées, la génération a lieu après les mises à jour de table lorsqu'il y a de nouveaux commits.

Pour vérifier si les données et les métadonnées ont été générées avec succès :

1. Utilisez DESCRIBE HISTORY pour trouver la dernière version de votre table source :

   SQL

   DESC HISTORY my_catalog.my_schema.my_table

   

   Cette commande renvoie l'historique des refresh vers le Mode de compatibilité, y compris la version et le timestamp de Delta Lake. La première ligne contient la dernière version et le timestamp.

2. Utilisez DESCRIBE EXTENDED pour trouver la version correspondante du Mode de compatibilité :

   SQL

   DESC EXTENDED my_catalog.my_schema.my_table

   

   Recherchez les champs sous UniForm Compatibility Information :

   • Dernière version actualisée : la version Delta Lake qui a été mise à jour pour la dernière fois avec le Mode de compatibilité.
   • **Dernière refresh** : Le Timestamp de la dernière refresh

   Le Mode de compatibilité est à jour si la version de la table correspond à la version trouvée à l'étape 1.

3. Utilisez DESC HISTORY sur la version de compatibilité elle-même :

   SQL

   DESC HISTORY delta.\`<compatibility_location>\`

   

4. Dans l'Explorateur de catalogues, affichez les champs de métadonnées pour la version de compatibilité. Le Mode de compatibilité est à jour si la version de Delta Lake correspond à la version trouvée à l'étape 3.

   

Surveillance des coûts

L'Optimisation prédictive gère le cluster de compute qui effectue les actualisations automatiques pour le Mode de compatibilité. Pour afficher les coûts associés, query les tables de facturation du système :

SQL

SELECT
  DATE_TRUNC('DAY', start_time) AS day,
  SUM(usage_quantity) AS dbus
FROM
  system.storage.predictive_optimization_operations_history
WHERE
  operation_type = "COMPATIBILITY_MODE_REFRESH"
GROUP BY 1
ORDER BY 1 DESC;

Cette query signale l'utilisation uniquement pour les refresh automatiques. Les coûts des refresh manuels sont associés à votre compute, et il n'existe pas de moyen direct de suivre ces coûts séparément. Généralement, le coût d'un Trigger manuel est proportionnel au coût de l'Opération d'écriture initiale dans la table d'origine.

Supprimer les fichiers de données inutilisés

Pour supprimer les fichiers de données inutilisés sur la version de compatibilité de votre table, utilisez VACUUM:

SQL

VACUUM delta.'<compatibility_mode_location_path>';

Pour trouver le chemin d'emplacement du Mode de compatibilité, utilisez la commande DESCRIBE EXTENDED dans Vérifier si le Mode de compatibilité est activé. Dans la sortie, la valeur de delta.universalFormat.compatibility.location est l'emplacement.

Lire les versions de compatibilité des clients externes

Vous pouvez utiliser n'importe quel client Delta Lake ou Iceberg pour lire les données des versions de compatibilité. Voir ci-dessous pour des exemples pour Amazon Athena et Snowflake (lecteur Delta).

Amazon Athena

1. Dans l'éditeur de query Athena, créez une table externe à l'emplacement spécifié :

   SQL

   CREATE EXTERNAL TABLE <table_name>
   LOCATION '<compatibility_location>'
   TBLPROPERTIES ('table_type' = 'DELTA')

2. Lire la table :

   SQL

   SELECT * FROM <table_name>

Lecteur Snowflake Delta Lake

1. Créez une intégration de stockage pour accéder à l'emplacement de stockage (voir la documentation Snowflake).

2. Créer une table externe au format Delta Lake :

   SQL

   CREATE OR REPLACE EXTERNAL TABLE <table_name>
   WITH LOCATION = @<my_location>
   FILE_FORMAT = (TYPE = PARQUET)
   TABLE_FORMAT = DELTA
   AUTO_REFRESH = false
   REFRESH_ON_CREATE = false;

3. Refresh the table (auto refresh n'est pas pris en charge pour le format Delta Lake dans Snowflake) :

   SQL

   ALTER EXTERNAL TABLE <table_name> REFRESH;

4. Lire la table :

   SQL

   SELECT * FROM <table_name>;

Lecture des versions de compatibilité de l'API REST Unity

Les tables avec le Mode de compatibilité activé peuvent être lues par leur nom via l’API REST Unity avec des parameter spéciaux. Pour les tables de streaming, définissez le parameter d’API suivant :

GET /api/2.1/unity-catalog/tables/{full_name}?read_streaming_table_as_managed=true

Pour les vues matérialisées, définissez le paramètre d'API suivant :

GET /api/2.1/unity-catalog/tables/{full_name}?read_materialized_view_as_managed=true

Lecture des versions de compatibilité à partir du catalogue REST Iceberg

Les tables pour lesquelles le mode de compatibilité est activé peuvent être lues à partir de n'importe quel client Iceberg à l'aide du catalogue Iceberg REST. Le mode de compatibilité fonctionne automatiquement pour les formats de table Delta Lake et Iceberg.

Exigences de configuration

1. Activez l'accès aux données externes sur le metastore.
2. Accordez le privilège EXTERNAL USE SCHEMA sur le schéma.
3. Créez un jeton d'accès personnel Databricks (PAT).

Configuration Apache Spark

Bash

bin/spark-sql --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.8.0,org.apache.iceberg:iceberg-aws-bundle:1.8.0 \
  --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \
  --conf spark.sql.catalog.catalog_name=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.catalog_name.type=rest \
  --conf spark.sql.catalog.catalog_name.uri=<workspace-url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.catalog_name.token=<PAT> \
  --conf spark.sql.catalog.catalog_name.warehouse=<uc-catalog-name>

Pour plus d’informations, consultez Utiliser les tables Iceberg avec Apache Spark.

Configuration Snowflake

Snowflake offre deux options pour accéder aux tables en Mode de compatibilité via le catalogue REST Iceberg : via les bases de données liées au catalogue de Snowflake, ou via des tables externes.

Pour les deux options, commencez par configurer une intégration de catalogue Snowflake :

SQL

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  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',
    WAREHOUSE = '<uc-catalog-name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

Remplacez les variables suivantes :

• <catalog-integration-name>: Le nom que vous souhaitez attribuer au catalogue enregistré dans Snowflake.
• <uc-schema-name>: Le nom du schéma dans Unity Catalog auquel vous devez accéder.
• <uc-catalog-name>: Le nom du catalogue dans Unity Catalog auquel vous devez accéder.
• <workspace-url>: L'URL du Workspace Databricks.
• <token>: jeton PAT pour le principal qui configure l'intégration.

Bases de données liées au catalogue

Les bases de données liées au catalogue de Snowflake se synchronisent automatiquement avec Unity Catalog pour détecter les schémas et les tables Iceberg. Ceci élimine le besoin de refresh manuel des métadonnées.

Après avoir configuré une intégration de catalogue Snowflake, référez-vous à la documentation Snowflake pour créer une base de données liée au catalogue afin d’accéder à vos tables.

remarque

Les tables accessibles via le Mode de compatibilité sont en lecture seule. Les bases de données liées au catalogue étant une fonctionnalité de Snowflake, Databricks recommande de se référer à la documentation de Snowflake pour les Opérations prises en charge sur les tables de streaming Databricks, les vues matérialisées ou les tables gérées avec le Mode de compatibilité activé.

Tables externes

Vous pouvez également créer des tables externes après avoir créé une intégration de catalogue Snowflake. Cette approche nécessite d’actualiser manuellement les métadonnées pour voir les mises à jour.

SQL

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

Désactiver le Mode compatibilité

Pour désactiver le Mode de compatibilité, désactivez la propriété de table correspondante :

SQL

-- For UC managed tables
ALTER TABLE my_table UNSET TBLPROPERTIES('delta.universalFormat.enabledFormats')

-- For streaming tables and materialized views
CREATE OR REPLACE [STREAMING TABLE | MATERIALIZED VIEW] my_table
TBLPROPERTIES('delta.universalFormat.enabledFormats' = '')

attention

La désactivation du Mode de compatibilité arrête immédiatement la génération des données et des métadonnées. Après 7 jours, les données et métadonnées associées seront supprimées. Pendant cette période de 7 jours, vous pouvez restaurer les données et les métadonnées en réactivant le Mode de compatibilité sur la même table.

Limitations

• Lecture seule : La version de compatibilité est en lecture seule. Vous ne pouvez pas écrire dans la version de compatibilité.
• Pas de prise en charge RLS/CLS : vous ne pouvez pas activer le Mode de compatibilité sur les tables avec la sécurité au niveau des lignes (RLS) ou la sécurité au niveau des colonnes (CLS).
• **Aucun renommage de colonne de partition** : Le renommage de colonne de partition n’est pas pris en charge sur les tables avec le Mode de compatibilité activé. Le renommage de colonne de données est pris en charge.
• Fonctionnalités de table limitées : les fonctionnalités suivantes ne sont pas disponibles dans la version de compatibilité :
  • Colonnes de classement
  • Clés primaires
  • time travel
  • Flux de données de modification
  • Noms de colonne avec des caractères spéciaux (seront renommés)