Mode de compatibilité

En mode de compatibilité, vous pouvez lire les tables managées du catalogue Unity, les vues matérialisées et les tables de streaming à partir de systèmes externes tout en conservant des performances optimales sur Azure Databricks. Cette fonctionnalité génère automatiquement des versions en lecture seule de vos tables accessibles par n’importe quel client Delta Lake ou Iceberg.

Aperçu

Lorsqu’il est activé sur une table gérée, une table de diffusion en continu 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, fournissant les fonctionnalités suivantes :

• Interopérabilité avec n’importe quel client Delta Lake : lisez vos tables managées, y compris les tables de streaming ou les vues matérialisées, à partir de clients tels qu’Amazon Athena, Microsoft Fabric, Snowflake et Amazon Redshift directement à partir du stockage ou via l’API REST Unity
• Interopérabilité avec n’importe quel client Iceberg : lisez vos tables managées, y compris les tables de streaming ou les vues matérialisées, à partir de clients Iceberg tels qu’Apache Spark, Apache Trino et Snowflake via le catalogue REST Iceberg
• Automatisation sans intervention : Automatiser les rafraîchissements de données et de métadonnées pour les versions de compatibilité, avec la possibilité de configurer les intervalles de rafraîchissement en quasi temps réel

Prerequisites

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

En outre, vérifiez que vous disposez d’un emplacement externe inscrit dans le catalogue Unity avec des paramètres et des 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 inscrit en tant qu’emplacement externe dans le catalogue Unity.
• Vous devez posséder le privilège CREATE EXTERNAL TABLE pour l’emplacement externe.
• L’emplacement cible et tous les dossiers parents ou enfants ne doivent pas avoir été utilisés comme emplacement du 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 diffusion en continu, les vues matérialisées et les clones peu profonds gérés, définissez les propriétés de tableau suivantes au moment de la création de la table :

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 le catalogue Unity uniquement, vous pouvez également activer le mode de compatibilité lorsque vous modifiez une table existante :

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

La génération d’une version de compatibilité pour la première fois prend jusqu’à une heure. Vous pouvez actualiser manuellement la table immédiatement pour confirmer qu’elle fonctionne.

Vérifier 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 delta.universalFormat.enabledFormats = 'compatibility' table existe. Vous pouvez afficher cette propriété dans l’interface utilisateur de l’Explorateur de catalogues sous l’onglet Détails de votre tableau.

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

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

Recherchez ces propriétés dans la sortie :

• delta.universalFormat.enabledFormats: "compatibility" : indique que le mode de compatibilité est activé
• delta.universalFormat.compatibility.location : affiche l’emplacement de la version du mode de compatibilité

Configurer les intervalles d’actualisation

Pour les tables gérées par le catalogue Unity, vous pouvez configurer la fréquence à laquelle la version du mode de compatibilité est actualisée en définissant l’intervalle d’actualisation :

-- 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 d’actualisation par défaut est 1 HOUR. La définition de l’intervalle d’actualisation inférieur à 1 heure n’est pas recommandée et ne rend pas les actualisations plus fréquentes. L’exception est lorsque vous définissez l’intervalle d’actualisation sur 0 MINUTES. Dans ce cas, Azure Databricks vérifie les modifications après chaque validation et déclenche une actualisation si nécessaire.

Pour les tables de diffusion en continu et les vues matérialisées, un intervalle d’actualisation n’est pas nécessaire. 0 MINUTES est la valeur par défaut.

Actualisation manuelle

Pour déclencher manuellement une actualisation de la version de compatibilité :

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

L’actualisation manuelle est utile pour tester que le mode de compatibilité fonctionne correctement ou pour garantir que votre version de compatibilité est up-to-date avant une lecture ultérieure. Toutefois, l’attente des actualisations 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 des données et des métadonnées automatiquement et de manière asynchrone. Pour les tables gérées par le catalogue Unity, la génération se produit toutes les heures par défaut ou en fonction de votre intervalle d’actualisation configuré. Pour les tables de streaming et les vues matérialisées, la génération se produit après les mises à jour des tables lorsque de nouvelles validations sont effectuées.

Pour vérifier si les données et les métadonnées ont été correctement générées :

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

   DESC HISTORY my_catalog.my_schema.my_table
   

   

   Cette commande retourne l’historique des actualisations en mode de compatibilité, y compris la version delta Lake et l’horodatage. La ligne supérieure contient la dernière version et l’horodatage.

2. Permet DESCRIBE EXTENDED de rechercher la version correspondante du mode de compatibilité :

   DESC EXTENDED my_catalog.my_schema.my_table
   

   

   Recherchez les champs sous Informations de compatibilité uniforme :

   • Dernière version actualisée : version Delta Lake qui a été mise à jour pour la dernière fois avec le mode de compatibilité
   • Dernière actualisation : horodatage de la dernière actualisation

   Le mode de compatibilité est up-to-date si la version de la table correspond à la version trouvée à l’étape 1.

3. Utilisez DESC HISTORY sur la version de compatibilité.

   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 up-to-date si la version Delta Lake correspond à la version trouvée à l’étape 3.

   

Superviser les coûts

L’optimisation prédictive gère le cluster de calcul qui effectue des actualisations automatiques pour le mode de compatibilité. Pour afficher les coûts associés, interrogez les tables de facturation système :

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 requête signale l’utilisation des actualisations automatiques uniquement. Les coûts des actualisations manuelles sont associés à votre calcul et il n’existe pas de moyen direct de suivre séparément ces coûts. En règle générale, le coût d’un déclencheur 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:

VACUUM delta.'<compatibility_mode_location_path>';

Pour rechercher le chemin d’emplacement du mode de compatibilité, utilisez la commande vérifier si le DESCRIBE EXTENDEDmode de compatibilité est activé. Dans la sortie, la valeur de delta.universalFormat.compatibility.location est l’emplacement.

Lire les versions de compatibilité à partir de clients externes

Vous pouvez utiliser n’importe quel client Delta Lake ou Iceberg pour lire des données à partir de versions de compatibilité. Consultez ci-dessous pour obtenir des exemples pour AmazonThéna, Snowflake (lecteur Delta) et Fabric.

AmazonThéna

1. Dans l’Éditeur de requête Athéna, créez une table externe avec l’emplacement spécifié :

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

2. Lisez le tableau :

   SELECT * FROM <table_name>
   

Lecteur de Snowflake pour Delta Lake

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

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

   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. Actualisez la table (l’actualisation automatique n’est pas prise en charge pour le format Delta Lake dans Snowflake) :

   ALTER EXTERNAL TABLE <table_name> REFRESH;
   

4. Lisez le tableau :

   SELECT * FROM <table_name>;
   

Microsoft Fabric

1. Créez une capacité Fabric, un espace de travail et un notebook Synapse.

2. Créez un lakehouse avec des données dans l’emplacement de compatibilité.

3. Lisez les fichiers sous la forme d’une table Delta Lake :

   spark.read.format("delta").load("Files/<path_to_data>")
   

Lecture des versions de compatibilité à partir de l’API REST Unity

Les tables avec mode de compatibilité activé peuvent être lues par nom via l’API REST Unity avec des paramètres spéciaux. Pour les tables de diffusion en continu, définissez le paramètre 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 avec mode de compatibilité activé peuvent être lues à partir de n’importe quel client Iceberg à l’aide du catalogue REST Iceberg. Le mode de compatibilité fonctionne automatiquement pour les formats de table Delta Lake et Iceberg.

Conditions d’installation requises

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

Configuration de Apache Spark

bin/spark-sql --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.8.0,org.apache.iceberg:iceberg-azure-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 des tables Iceberg avec Apache Spark.

Configuration de 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-st/mv-name>';

Désactiver le mode de compatibilité

Pour désactiver le mode de compatibilité, désactivez la propriété de table correspondante.

-- 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' = '')

Limites

• Accès en lecture seule : la version de compatibilité est en lecture seule. Vous ne pouvez pas écrire dans la version de compatibilité.
• Aucune prise en charge RLS/CLS : vous ne pouvez pas activer le mode de compatibilité sur les tables avec sécurité au niveau des lignes (RLS) ou sécurité au niveau des colonnes (CLS).
• Aucun changement de nom de colonne de partition : le changement de nom de colonne de partition n’est pas pris en charge sur les tables avec le mode de compatibilité activé. Le changement de nom de colonne de données est pris en charge.
• Fonctionnalités de tableau limitées : les fonctionnalités suivantes ne sont pas disponibles dans la version de compatibilité :
  • Colonnes de classement
  • Clés primaires
  • Voyage dans le temps
  • Modifier le flux de données
  • Noms de colonnes avec des caractères spéciaux (seront renommés)