ANALYZE TABLE … MÉTRIQUES DE STOCKAGE DE CALCUL

S’applique à : Databricks Runtime 18.0 et versions ultérieures

La ANALYZE TABLE … COMPUTE STORAGE METRICS commande calcule les métriques de taille de stockage totale pour les tables. Il affiche une répartition détaillée du stockage pour l’analyse et l’optimisation des coûts. Pour l’optimisation des performances des requêtes, consultez ANALYZE TABLE ... STATISTIQUES DE CALCUL.

Par défaut, la commande analyse directement les fichiers de la table. Sur les tables volumineuses, ajoutez la USING INVENTORY clause pour lire à partir d’un rapport d’inventaire de stockage cloud prégéné, ce qui réduit le temps et le coût des métriques de stockage de calcul. Consultez Utiliser un rapport d’inventaire.

Syntaxe

ANALYZE TABLE table_name COMPUTE STORAGE METRICS
  [ USING INVENTORY LOCATION inventory_path
    CONF conf_name ]

Paramètres

• table_name

  Identifie la table à analyser. Le nom ne doit pas inclure de spécification temporelle ou de spécification d’options ou de chemin d’accès. Si la table est introuvable, Azure Databricks déclenche une condition d’erreur TABLE_OR_VIEW_NOT_FOUND.

• USING INVENTORY

  Optional. Lit les métriques de stockage à partir d’un rapport d’inventaire de stockage cloud prégéné au lieu d’analyser les fichiers de la table. Consultez Utiliser un rapport d’inventaire. Prend deux sous-paramètres :

  • LOCATION inventory_path

    Littéral STRING avec le chemin d’accès de stockage cloud complet au rapport d’inventaire, y compris tout préfixe. Ce chemin doit correspondre à la destination que vous avez configurée lorsque vous configurez le rapport d’inventaire sur le compartiment source ou le conteneur, et il doit être sauvegardé par un emplacement externe auquel vous avez accès. Consultez Utiliser un rapport d’inventaire.

    Par exemple : 'abfss://your-destination-container@your-storage-account.dfs.core.windows.net/your-prefix/'.

  • CONF conf_name

    Required. Littéral STRING qui identifie la configuration du rapport d’inventaire sur le compartiment source ou le conteneur à utiliser.

    Si vous configurez la règle de stratégie d’inventaire d’objets blob à l’aide de la Azure CLI, utilisez la même valeur que celle pour namelaquelle vous avez défini . Si vous configurez à l’aide de la console Azure, utilisez plutôt la valeur que vous définissez pour le nom de la règle.

Descriptif

Calcule les métriques de taille de stockage totales pour une table spécifique. Cette commande retourne des informations de stockage complètes, notamment le nombre total d’octets, les octets actifs, les octets vides et les octets de déplacement de temps, ainsi que le nombre associé de fichiers pour chaque catégorie.

Utilisez cette commande pour identifier les tables volumineuses ou inutilisées, optimiser les coûts de stockage et comprendre pourquoi la taille totale du stockage diffère de la taille de table active. Cela est utile pour les administrateurs de plateforme qui doivent analyser les modèles de stockage sur plusieurs tables ou suivre les modifications de stockage au fil du temps.

Métriques de sortie

La commande retourne trois colonnes : metric_name, metric_valueet metric_description. Une ligne est retournée pour chacune des métriques suivantes :

Détails

• Par défaut, la commande utilise une approche de liste récursive pour calculer les informations de stockage. Le temps d’exécution est généralement en quelques minutes, mais peut prendre jusqu’à plusieurs heures pour les tables très volumineuses.
• Cette commande fonctionne à la fois pour les tables managées et externes du catalogue Unity.
• La commande calcule les métriques de stockage au moment de l’exécution. Les résultats ne sont pas stockés dans le catalogue Unity et ne sont pas reflétés dans la DESCRIBE EXTENDED sortie, ce qui affiche uniquement la taille de la table active.
• Pour suivre les modifications de stockage au fil du temps, exécutez régulièrement cette commande et stockez les résultats dans une table. Exécutez cette commande dans une boucle sur plusieurs tables pour analyser les modèles de stockage dans votre patrimoine de données. Consultez les métriques de stockage de calcul pour toutes les tables d’un catalogue.

Utiliser un rapport d’inventaire

S’applique à : Databricks Runtime 19 et versions ultérieures

Utilisez la USING INVENTORY clause sur les tables volumineuses pour réduire le temps et le coût des métriques de stockage informatique, en lisant un rapport d’inventaire de stockage cloud prédéfinis au lieu d’analyser les fichiers de la table. Databricks recommande cette clause pour les tables composées de 100 000 fichiers ou plus, ou pour les tables qui sont fortement partitionnée sur plusieurs clés. Pour les tables plus petites ou les tables sans rapport d’inventaire configuré, utilisez la commande sans cette clause.

La USING INVENTORY clause fonctionne pour les tables managées et externes du catalogue Unity. Il s’exécute uniquement sur le calcul classique. Pour plus de limitations, consultez les limitations USING INVENTORY.

Pour plus d’informations sur les métriques retournées par la commande, consultez Métriques de sortie.

Prerequisites

La USING INVENTORY clause présente les conditions préalables suivantes :

• Privilèges à configurer pour la première fois : les administrateurs de metastore ont les privilèges de Azure Databricks requis par défaut. Si vous n’êtes pas administrateur, pour configurer des rapports d’inventaire et inscrire leur destination en tant qu’emplacement externe, vous devez disposer des autorisations suivantes :
  • Autorisations du fournisseur de cloud pour configurer des rapports d’inventaire sur le compartiment source ou le conteneur.
  • L’un des privilèges suivants Azure Databricks pour inscrire la destination d’inventaire en tant qu’emplacement externe :
    • Privilège CREATE EXTERNAL LOCATION sur le metastore et les informations d’identification de stockage qu’il référence.
    • Le privilège MANAGE sur l’emplacement externe.

• Rapport d’inventaire configuré : configurez un rapport d’inventaire d’objets blob stockage Azure sur chaque conteneur source qui contient les tables que vous souhaitez analyser. Utilisez ces paramètres :
  • Type d’objet : Blob
  • Types d’objets blob : objets blob de blocs et objets blob d’ajout
  • Sous-types : n’activez pas les instantanés Include ou include les objets blob supprimés
  • Fréquence : Quotidienne
  • Format d’exportation : Apache Parquet
  • Champs d’inventaire d’objets blob : Nom, Dernière modification, Longueur du contenu, Instantané, Suppression et état du dossier HDI (CLI schemaFields: Name, , Last-Modified, Content-LengthSnapshot, Deleted, ). hdi_isfolder Sans eux, la commande ne peut pas calculer la sortie correcte.

• Emplacement externe du rapport d'inventaire : vous devez disposer d'un accès en lecture dans Azure Databricks au chemin de destination du rapport d'inventaire.

  • Si le chemin d’accès n’est pas dans un emplacement externe existant, inscrivez-le en tant qu’emplacement externe en premier. Consultez Se connecter à un emplacement externe Azure Data Lake Storage Gen2 (ADLS Gen2).

• Privilèges d’exécution de la commande : vous devez disposer du READ FILES privilège sur l’emplacement externe dans Azure Databricks qui sauvegarde la destination du rapport d’inventaire, en plus de vos privilèges existants sur la table que vous analysez.

Pour rechercher le compartiment source ou le conteneur d’une table, exécutez EXTENDED et vérifiez DESCRIBE TABLE le Location champ dans la sortie. Pour les vues matérialisées et les tables de diffusion en continu, vous devez utiliser DESCRIBE EXTENDED pour rechercher l’emplacement de stockage réel. Vous devez vérifier que votre rapport d’inventaire est configuré sur ce compartiment source ou conteneur.

Erreurs de rapport d’inventaire obsolètes

La commande recherche le rapport d’inventaire complet le plus récent généré au cours des 14 derniers jours. S’il ne trouve aucun rapport dans cette fenêtre, la commande ne calcule pas les métriques et retourne une ANALYZE_TABLE_COMPUTE_STORAGE_METRICS_INVENTORY_CONTENTS_NOT_VALID erreur avec un message similaire à ce qui suit :

No inventory reports found in the last 14 days (window: 2026-07-08 to 2026-07-22).
1 report directory(s) exist but fall outside the lookback window.
Ensure a recent inventory report has been generated.

Pour résoudre cette erreur, vérifiez que le compartiment source ou le conteneur génère des rapports d’inventaire selon la planification que vous avez configurée, puis réexécutez la commande une fois qu’un nouveau rapport est généré. Voir Conditions préalables.

Considérations relatives au type de tableau

Pour les vues matérialisées et les tables de diffusion en continu, total_bytes inclut la taille de la table et les métadonnées associées. La active_bytes métrique exclut la table vacuumable_bytes et time_travel_bytes.

Pour les clones peu profonds, total_bytes inclut uniquement les propres métadonnées du clone et les fichiers journaux Delta, à l’exclusion des fichiers de table source. active_bytes est égal à zéro, car le clone fait référence aux fichiers de données de la table source.

Exemples

Métriques de stockage de calcul

Pour calculer les métriques de stockage, exécutez la commande suivante :

ANALYZE TABLE main.my_schema.my_table COMPUTE STORAGE METRICS;

La commande retourne la sortie, par exemple :

metric_name              metric_value  metric_description
-----------------------  ------------  --------------------------------------------------
total_bytes                5368709120  Total bytes on disk
num_total_files                  1250  Total files on disk
active_bytes               4294967296  Bytes in current snapshot
num_active_files                 1000  Files in current snapshot
vacuumable_bytes            805306368  Bytes eligible for vacuum
num_vacuumable_files              150  Files eligible for vacuum
time_travel_bytes           268435456  Bytes reachable by time travel (excluding active)
num_time_travel_files             100  Files reachable by time travel (excluding active)

La sortie indique :

• Stockage total : 5,37 Go sur 1 250 fichiers
• Données actives : 4,29 Go dans 1 000 fichiers (version actuelle de la table)
• Données vides : 805 Mo dans 150 fichiers (VACUUM peut récupérer cette taille de stockage)
• Données de voyage dans le temps : 268 Mo dans 100 fichiers (pour les requêtes historiques)

Calcul des métriques de stockage à l’aide d’un rapport d’inventaire

L’exemple suivant calcule les mêmes métriques à partir d’un rapport d’inventaire au lieu d’analyser les fichiers de la table :

ANALYZE TABLE main.my_schema.my_table COMPUTE STORAGE METRICS
USING INVENTORY LOCATION 'abfss://your-destination-container@your-storage-account.dfs.core.windows.net/your-prefix/'
CONF 'databricks-inventory-list-config';

Étant donné que les rapports d’inventaire reflètent l’état de la table au moment où le rapport a été généré (jusqu’à 24 heures plus tôt), la sortie peut différer d’une analyse directe. Par exemple:

metric_name              metric_value  metric_description
-----------------------  ------------  --------------------------------------------------
total_bytes                5100273664  Total bytes on disk
num_total_files                  1232  Total files on disk
active_bytes               4076863488  Bytes in current snapshot
num_active_files                  984  Files in current snapshot
vacuumable_bytes            771751936  Bytes eligible for vacuum
num_vacuumable_files              148  Files eligible for vacuum
time_travel_bytes           251658240  Bytes reachable by time travel (excluding active)
num_time_travel_files             100  Files reachable by time travel (excluding active)

Consultez Utiliser un rapport d’inventaire.

Calcul des métriques de stockage pour toutes les tables d’un catalogue

Pour calculer les métriques de stockage pour chaque table d’un catalogue, toutes utilisant des rapports d’inventaire à la même destination, utilisez une boucle. L’exemple suivant répertorie les tables à l’aide d’un schéma d’informations, que chaque catalogue inclut automatiquement :

%python
tables = spark.sql("""
  SELECT table_catalog, table_schema, table_name
  FROM main.information_schema.tables
  WHERE table_type IN (
    'MANAGED', 'EXTERNAL',
    'STREAMING_TABLE', 'MATERIALIZED_VIEW',
    'MANAGED_SHALLOW_CLONE', 'EXTERNAL_SHALLOW_CLONE'
  )
""").collect()

for t in tables:
    full_name = f"{t.table_catalog}.{t.table_schema}.{t.table_name}"
    result = spark.sql(f"""
      ANALYZE TABLE {full_name} COMPUTE STORAGE METRICS
      USING INVENTORY LOCATION 'abfss://your-destination-container@your-storage-account.dfs.core.windows.net/your-prefix/'
      CONF 'databricks-inventory-list-config'
    """)
    result.show()

UTILISATION DES LIMITATIONS D’INVENTAIRE

La USING INVENTORY clause présente les limitations suivantes :

• Cette clause s’exécute uniquement sur le calcul classique. Elle n’est pas prise en charge sur les entrepôts SQL serverless ou Databricks.
• Cette clause prend uniquement en charge les tables de catalogue, y compris les tables gérées et externes. Elle ne prend pas en charge les tables Delta Lake basées sur le chemin, ce qui génère une erreur : ANALYZE_TABLE_COMPUTE_STORAGE_METRICS_NOT_SUPPORTED condition d’erreur.
• Si le contrôle de version d’objet est activé sur le compartiment source ou le conteneur, les résultats ne sont pas garantis pour être corrects.
• Si l’emplacement de stockage d’une table change, reconfigurez le rapport d’inventaire sur le nouveau compartiment source ou conteneur. L’emplacement d’origine ne génère plus de rapports pour la table. Par exemple, la conversion d’une table externe en table managée modifie l’emplacement de stockage de la table. Consultez Convertir des tables Delta Lake externes ou étrangères en tables gérées par le catalogue Unity.

Azure ne prend pas en charge la configuration de l'inventaire entre les comptes de stockage. Si vos tables s’étendent sur plusieurs comptes de stockage, chaque compte de stockage a besoin de sa propre configuration d’inventaire.

Notebook : Métriques de stockage de calcul pour plusieurs tables

Le notebook suivant s’exécute ANALYZE TABLE ... COMPUTE STORAGE METRICS ... USING INVENTORY sur un ensemble de tables de catalogue Unity et stocke les résultats dans une table Delta Lake. Utilisez-la pour analyser le stockage sur de nombreuses tables à la fois.

Calcul des métriques de stockage pour plusieurs tables notebook

Obtenir un ordinateur portable

Déclarations connexes

• ANALYZE TABLE … STATISTIQUES DE CALCUL
• VACUUM
• Optimisation prédictive pour les tables managées du catalogue Unity
• Utiliser l’historique des tables
• Convertir des tables Delta Lake externes ou étrangères en tables gérées par le catalogue Unity
• Emplacements externes