Gérer l'historique des tables

Pour les tables Apache Iceberg et Delta Lake, chaque opération qui modifie une table crée une nouvelle version de table. Utilisez les informations d'historique pour auditer les opérations, restaurer une table ou query une table à un point précis dans le temps en utilisant le time travel.

remarque

Databricks ne recommande pas d'utiliser l'historique des tables comme solution de sauvegarde à long terme pour l'archivage des données. Utilisez uniquement les 7 derniers jours pour les opérations de time travel, sauf si vous avez défini les configurations de conservation des données et des logs à une valeur plus élevée.

Récupérer l'historique de la table

Exécutez la commande DESCRIBE HISTORY pour récupérer des informations, notamment les opérations, l’utilisateur et le Timestamp de chaque écriture dans une table. Les opérations sont renvoyées dans l'ordre chronologique inverse.

La rétention de l'historique des tables est déterminée par le paramètre de table logRetentionDuration, qui est 30 jours by default.

remarque

Le time travel et l'historique des tables sont régis par différents seuils de rétention. See time travel.

SQL
DESCRIBE HISTORY table_name       -- get the full history of the table

DESCRIBE HISTORY table_name LIMIT 1  -- get the last operation only

Pour plus de détails sur la syntaxe Spark SQL, consultez DESCRIBE HISTORY.

Pour plus de détails sur la syntaxe Scala, Java et Python, consultez la documentation de l’API Delta Lake.

Catalog Explorer shows table history visually on the History tab.

Schéma d'historique

La sortie de l'opération history comporte les colonnes suivantes.

Colonne	Type	Description
Version	`long`	La version de table générée par l'opération.
Horodatage	`timestamp`	Lorsque cette version a été validée.
ID utilisateur	`string`	L'ID de l'utilisateur qui a exécuté l'opération.
Nom d'utilisateur	`string`	Le nom de l’utilisateur qui a exécuté l’Opération.
Opérations	`string`	Le nom de l'opération.
Paramètres d'opération	`map`	Les paramètres de l'opération (par exemple, les prédicats). Pour les opérations `OPTIMIZE`, ces paramètres identifient le type d'opération. Consultez Identifier le type d'opération de `OPTIMIZE`.
Job	`struct`	Les détails du LakeFlow Job qui a exécuté l'opération. Est renseigné uniquement pour les commits écrits à partir d'un LakeFlow Job. Sinon, `null`.
Notebook	`struct`	Les détails du Notebook Databricks à partir duquel l'opération a été exécutée. Renseigné uniquement pour les commits écrits à partir d'un Notebook Databricks. Sinon, `null`.
ID de cluster	`string`	L'ID du cluster sur lequel l'opération a été exécutée.
readVersion	`long`	La version de la table qui a été lue pour effectuer l'opération d'écriture.
isolationLevel	`string`	Le niveau d'isolation utilisé pour cette opération.
isBlindAppend	`boolean`	Si cette opération a ajouté des données.
operationMetrics	`map`	Les métriques de l'opération (par exemple, le nombre de lignes et de fichiers modifiés).
userMetadata	`string`	Les métadonnées de commit définies par l'utilisateur si elles ont été spécifiées.

Colonne	Type	Description
Version	`long`	La version de table générée par l'opération.
Horodatage	`timestamp`	Lorsque cette version a été validée.
ID utilisateur	`string`	L'ID de l'utilisateur qui a exécuté l'opération.
Nom d'utilisateur	`string`	Le nom de l’utilisateur qui a exécuté l’Opération.
Opérations	`string`	Le nom de l'opération.
Paramètres d'opération	`map`	Les paramètres de l'opération (par exemple, les prédicats). Pour les opérations `OPTIMIZE`, ces paramètres identifient le type d'opération. Consultez Identifier le type d'opération de `OPTIMIZE`.
Job	`struct`	Les détails du LakeFlow Job qui a exécuté l'opération. Est renseigné uniquement pour les commits écrits à partir d'un LakeFlow Job. Sinon, `null`.
Notebook	`struct`	Les détails du Notebook Databricks à partir duquel l'opération a été exécutée. Renseigné uniquement pour les commits écrits à partir d'un Notebook Databricks. Sinon, `null`.
ID de cluster	`string`	L'ID du cluster sur lequel l'opération a été exécutée.
readVersion	`long`	La version de la table qui a été lue pour effectuer l'opération d'écriture.
isolationLevel	`string`	Le niveau d'isolation utilisé pour cette opération.
isBlindAppend	`boolean`	Si cette opération a ajouté des données.
operationMetrics	`map`	Les métriques de l'opération (par exemple, le nombre de lignes et de fichiers modifiés).
userMetadata	`string`	Les métadonnées de commit définies par l'utilisateur si elles ont été spécifiées.

Text
+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+
|version|          timestamp|userId|userName|operation| operationParameters| job|notebook|clusterId|readVersion|   isolationLevel|isBlindAppend|    operationMetrics|
+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+
|      5|2019-07-29 14:07:47|   ###|     ###|   DELETE|[predicate -> ["(...|null|     ###|      ###|          4|WriteSerializable|        false|[numTotalRows -> ...|
|      4|2019-07-29 14:07:41|   ###|     ###|   UPDATE|[predicate -> (id...|null|     ###|      ###|          3|WriteSerializable|        false|[numTotalRows -> ...|
|      3|2019-07-29 14:07:29|   ###|     ###|   DELETE|[predicate -> ["(...|null|     ###|      ###|          2|WriteSerializable|        false|[numTotalRows -> ...|
|      2|2019-07-29 14:06:56|   ###|     ###|   UPDATE|[predicate -> (id...|null|     ###|      ###|          1|WriteSerializable|        false|[numTotalRows -> ...|
|      1|2019-07-29 14:04:31|   ###|     ###|   DELETE|[predicate -> ["(...|null|     ###|      ###|          0|WriteSerializable|        false|[numTotalRows -> ...|
|      0|2019-07-29 14:01:40|   ###|     ###|    WRITE|[mode -> ErrorIfE...|null|     ###|      ###|       null|WriteSerializable|         true|[numFiles -> 2, n...|
+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+

remarque

Si vous écrivez dans une table en utilisant les méthodes suivantes, certaines colonnes ne sont pas disponibles :
Les colonnes ajoutées ultérieurement seront toujours ajoutées après la dernière colonne.

Comprendre `partitionBy` dans les paramètres d'Opérations

Le champ partitionBy dans l'historique de la table n'est pertinent que pour les opérations CREATE et OVERWRITE qui définissent ou modifient le schéma de partition d'une table.

Pour les opérations d'ajout aux tables existantes (APPEND, INSERT, UPDATE, DELETE, MERGE), ce champ peut afficher un tableau vide [] ou des colonnes de partition selon la méthode d'écriture utilisée (.save() vs .saveAsTable()).

Cette incohérence est un comportement attendu et n'affecte pas la façon dont les données sont écrites dans les partitions. Vous ne devriez pas l'utiliser pour valider les opérations d'ajout.

Exemple

Considérez une table partitionnée par la colonne date. Lorsque vous créez la table, partitionBy est rempli :

Python
df.write.format("delta") \
  .partitionBy("date") \
  .saveAsTable("sales_data")

L'opération CREATE dans l'historique affiche :

Text
operationParameters: {
  "mode": "ErrorIfExists",
  "partitionBy": "[\"date\"]"
}

Lorsque vous ajoutez des données à cette table, partitionBy affiche un tableau vide :

Python
new_df.write.format("delta") \
  .mode("append") \
  .saveAsTable("sales_data")

L'opération APPEND affiche :

Text
operationParameters: {
  "mode": "Append",
  "partitionBy": "[]"
}

La valeur vide de partitionBy est attendue. Les données sont toujours écrites dans les partitions correctes, basées sur le schéma de partition existant de la table. Notez que .save() vers un chemin d'accès pourrait afficher des colonnes de partition dans ce champ, mais cette différence est un détail d'implémentation et n'affecte pas le comportement d'écriture.

Métriques des opérations

L’opération history renvoie une collection de métriques d’opérations dans le mappage de colonnes operationMetrics.

Les tableaux suivants répertorient les définitions des clés de mappage par opération.