Utiliser 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 interroger une table à un point précis dans le temps en utilisant le voyage dans le temps.

Note

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 des opérations de voyage dans le temps, sauf si vous avez défini des configurations de conservation des données et des journaux sur une valeur supérieure.

Récupérer l’historique des tables

Exécutez la DESCRIBE HISTORY commande pour récupérer des informations, notamment les opérations, l’utilisateur et l’horodatage pour chaque écriture dans une table. Les opérations sont retourné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 de 30 jours par défaut.

Note

Le voyage dans le temps et l’historique des tables sont contrôlés par des seuils de rétention distincts. Voir voyage dans le temps.

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

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

Pour plus d’informations sur la syntaxe Spark SQL, consultez DESCRIBE HISTORY.

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

L’Explorateur de catalogue affiche visuellement l’historique des tables sous l’onglet Historique .

Schéma de l’historique

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

Column	Type	Description
version	`long`	Version de table générée par l’opération.
timestamp	`timestamp`	Moment de validation de cette version.
identifiant utilisateur	`string`	ID de l’utilisateur qui a exécuté l’opération.
userName	`string`	Nom de l’utilisateur qui a exécuté l’opération.
fonctionnement	`string`	Nom de l’opération.
paramètres d'opération	`map`	Paramètres de l’opération (par exemple, prédicats.) Pour `OPTIMIZE` les opérations, ces paramètres identifient le type d’opération. Consultez Identifier le type d’opération`OPTIMIZE`.
tâche	`struct`	Détails du travail Lakeflow qui a effectué l’opération. Remplit uniquement les validations écrites à partir d’un travail Lakeflow. Sinon, `null`.
notebook	`struct`	Détails du notebook Databricks depuis lequel l’opération a été exécutée. Remplit uniquement les validations écrites à partir d’un notebook Databricks. Sinon, `null`.
clusterId	`string`	ID du cluster sur lequel l’opération s’est exécutée.
readVersion	`long`	Version de la table qui a été lue pour effectuer l’opération d’écriture.
isolationLevel	`string`	Niveau d’isolation utilisé pour cette opération.
isBlindAppend	`boolean`	Indique si cette opération a ajouté des données.
operationMetrics	`map`	Métriques de l’opération (par exemple, 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.

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

Note

Si vous écrivez dans une table à l’aide des méthodes suivantes, certaines colonnes ne sont pas disponibles :
Les colonnes ajoutées à l’avenir seront toujours ajoutées après la dernière colonne.

Présentation des `partitionBy` paramètres d’opération

Le partitionBy champ de l’historique des tables n’est significatif 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 à des tables existantes (APPEND, INSERT, DELETE UPDATE, MERGE), ce champ peut afficher un tableau [] ou des colonnes de partition vides en fonction de la méthode d’écriture utilisée (.save() vs .saveAsTable()).

Cette incohérence est attendue et n’affecte pas la façon dont les données sont écrites dans des partitions. Vous ne devez pas l’utiliser pour valider les opérations d’ajout.

Example

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

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

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

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

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

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

L’opération APPEND affiche :

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

La valeur vide partitionBy est attendue. Les données sont toujours écrites dans les partitions correctes en fonction du schéma de partition existant de la table. Notez que la référence .save() à un chemin d’accès peut 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 d’opération

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

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