テーブル履歴のスキーマとオペレーションメトリクス

DESCRIBE HISTORY コマンドは、Apache Iceberg テーブルおよび Delta Lake テーブルに対して、テーブル操作の履歴を記述する14列を返します。各列を解釈するには、このリファレンスを使用してください。

テーブル履歴の取得、以前のテーブルバージョンのクエリ、およびテーブルの復元に関するガイダンスについては、テーブル履歴の操作を参照してください。

履歴スキーマ

historyオペレーションの出力には、次の列があります。

列	Type	説明
version	`long`	オペレーションによって生成されたテーブルのバージョン。
timestamp	`timestamp`	このバージョンがコミットされたとき。
userId	`string`	操作を実行したユーザーのID。
userName	`string`	オペレーションを実行したユーザーの名前。
operation	`string`	オペレーションの名前。
operationParameters	`map`	オペレーションのパラメーター（述語など）。`OPTIMIZE` オペレーションの場合、これらのパラメーターはオペレーションのタイプを識別します。「`OPTIMIZE` オペレーションのタイプを識別する」を参照してください。
ジョブ	`struct`	オペレーションを実行したLakeflow Jobの詳細。Lakeflow Jobから書き込まれたcommitに対してのみ入力されます。それ以外の場合は、`null`。
notebook	`struct`	オペレーションが実行されたDatabricksノートブックの詳細。Databricksノートブックから書き込まれたcommitに対してのみ入力されます。それ以外の場合は、`null`。
clusterId	`string`	オペレーションが実行されたクラスターの ID。
readVersion	`long`	書き込みオペレーションを行うために読み込まれたテーブルのバージョン。
isolationLevel	`string`	このオペレーションに使用される隔離レベル。
isBlindAppend	`boolean`	このオペレーションでデータが追加されたかどうか。
operationMetrics	`map`	オペレーションのメトリクス（たとえば、行数や変更されたファイル数など）。
userMetadata	`string`	指定されている場合のユーザー定義のcommitメタデータ。

列	Type	説明
version	`long`	オペレーションによって生成されたテーブルのバージョン。
timestamp	`timestamp`	このバージョンがコミットされたとき。
userId	`string`	操作を実行したユーザーのID。
userName	`string`	オペレーションを実行したユーザーの名前。
operation	`string`	オペレーションの名前。
operationParameters	`map`	オペレーションのパラメーター（述語など）。`OPTIMIZE` オペレーションの場合、これらのパラメーターはオペレーションのタイプを識別します。「`OPTIMIZE` オペレーションのタイプを識別する」を参照してください。
ジョブ	`struct`	オペレーションを実行したLakeflow Jobの詳細。Lakeflow Jobから書き込まれたcommitに対してのみ入力されます。それ以外の場合は、`null`。
notebook	`struct`	オペレーションが実行されたDatabricksノートブックの詳細。Databricksノートブックから書き込まれたcommitに対してのみ入力されます。それ以外の場合は、`null`。
clusterId	`string`	オペレーションが実行されたクラスターの ID。
readVersion	`long`	書き込みオペレーションを行うために読み込まれたテーブルのバージョン。
isolationLevel	`string`	このオペレーションに使用される隔離レベル。
isBlindAppend	`boolean`	このオペレーションでデータが追加されたかどうか。
operationMetrics	`map`	オペレーションのメトリクス（たとえば、行数や変更されたファイル数など）。
userMetadata	`string`	指定されている場合のユーザー定義のcommitメタデータ。

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

注記

次の方法を使用してテーブルに書き込む場合、一部の列は使用できません：
今後追加される列は、常に最後の列の後に追加されます。

オペレーションパラメーターにおける`partitionBy`の理解

テーブル履歴の partitionBy フィールドは、テーブルのパーティションスキーマを定義または変更するCREATEおよびOVERWRITEオペレーションに対してのみ意味を持ちます。

既存のテーブルへの追加オペレーション（APPEND、INSERT、UPDATE、DELETE、MERGE）の場合、使用される書き込みメソッド（.save()対.saveAsTable()）に応じて、このフィールドには空の配列[]またはパーティション列が表示されることがあります。

この不整合は予期された動作であり、パーティションへのデータの書き込み方法には影響しません。追加オペレーションの検証には使用しないでください。

例

date 列でパーティション分割されたテーブルを検討します。テーブルを作成すると、partitionBy にデータが投入されます：

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

履歴内のCREATEオペレーションは以下を示します：

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

このテーブルにデータを追加すると、partitionBy は空の配列を表示します：

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

APPENDオペレーションは以下を表示します：

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

空の partitionBy 値が予期されています。データは、テーブルの既存のパーティションスキーマに基づいて、引き続き正しいパーティションに書き込まれます。パスへの .save() ではこのフィールドにパーティション列が表示される場合がありますが、この違いは実装の詳細であり、書き込み動作には影響しません。

運用メトリクス

history オペレーションは、operationMetrics 列マップ内のオペレーションメトリクスのコレクションを返します。

以下のテーブルは、オペレーション別のマップキー定義の一覧です。

`WRITE`、`CREATE TABLE AS SELECT`、`REPLACE TABLE AS SELECT`、 `COPY INTO`

これらのオペレーションでは、以下のメトリクスを利用できます：

メトリクス名	説明
`numFiles`	書き込まれたファイルの数。
`numOutputBytes`	書き込まれた内容のサイズ（バイト単位）。
`numOutputRows`	書き込まれた行数。

`STREAMING UPDATE`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`numAddedFiles`	追加されたファイルの数。
`numRemovedFiles`	削除されたファイルの数。
`numOutputRows`	書き込まれた行数。
`numOutputBytes`	書き込みサイズ（バイト単位）。

メトリクス名	説明
`numAddedFiles`	追加されたファイルの数。
`numRemovedFiles`	削除されたファイルの数。
`numOutputRows`	書き込まれた行数。
`numOutputBytes`	書き込みサイズ（バイト単位）。

`DELETE`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`numAddedFiles`	追加されたファイルの数。テーブルのパーティションが削除された場合は提供されません。
`numRemovedFiles`	削除されたファイルの数。
`numDeletedRows`	削除された行の数。テーブルのパーティションが削除された場合は提供されません。
`numCopiedRows`	ファイルの削除処理中にコピーされた行数。
`executionTimeMs`	オペレーション全体の実行にかかった時間。
`scanTimeMs`	ファイルの一致をスキャンするのにかかった時間。
`rewriteTimeMs`	一致したファイルの書き換えにかかった時間。

メトリクス名	説明
`numAddedFiles`	追加されたファイルの数。テーブルのパーティションが削除された場合は提供されません。
`numRemovedFiles`	削除されたファイルの数。
`numDeletedRows`	削除された行の数。テーブルのパーティションが削除された場合は提供されません。
`numCopiedRows`	ファイルの削除処理中にコピーされた行数。
`executionTimeMs`	オペレーション全体の実行にかかった時間。
`scanTimeMs`	ファイルの一致をスキャンするのにかかった時間。
`rewriteTimeMs`	一致したファイルの書き換えにかかった時間。

`TRUNCATE`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`numRemovedFiles`	削除されたファイルの数。
`executionTimeMs`	オペレーション全体の実行にかかった時間。

`MERGE`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`numSourceRows`	ソースDataFrameの行数。
`numTargetRowsInserted`	ターゲットテーブルに挿入された行数。
`numTargetRowsUpdated`	ターゲットテーブルで更新された行数。
`numTargetRowsDeleted`	ターゲットテーブルで削除された行数。
`numTargetRowsCopied`	コピーされたターゲット行の数。
`numOutputRows`	書き出された行の合計数。
`numTargetFilesAdded`	シンク（ターゲット）に追加されたファイルの数。
`numTargetFilesRemoved`	シンク（ターゲット）から削除されたファイルの数。
`executionTimeMs`	オペレーション全体の実行にかかった時間。
`scanTimeMs`	ファイルの一致をスキャンするのにかかった時間。
`rewriteTimeMs`	一致したファイルの書き換えにかかった時間。

メトリクス名	説明
`numSourceRows`	ソースDataFrameの行数。
`numTargetRowsInserted`	ターゲットテーブルに挿入された行数。
`numTargetRowsUpdated`	ターゲットテーブルで更新された行数。
`numTargetRowsDeleted`	ターゲットテーブルで削除された行数。
`numTargetRowsCopied`	コピーされたターゲット行の数。
`numOutputRows`	書き出された行の合計数。
`numTargetFilesAdded`	シンク（ターゲット）に追加されたファイルの数。
`numTargetFilesRemoved`	シンク（ターゲット）から削除されたファイルの数。
`executionTimeMs`	オペレーション全体の実行にかかった時間。
`scanTimeMs`	ファイルの一致をスキャンするのにかかった時間。
`rewriteTimeMs`	一致したファイルの書き換えにかかった時間。

`UPDATE`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`numAddedFiles`	追加されたファイルの数。
`numRemovedFiles`	削除されたファイルの数。
`numUpdatedRows`	更新された行数。
`numCopiedRows`	ファイルの更新プロセスでコピーされた行数。
`executionTimeMs`	オペレーション全体の実行にかかった時間。
`scanTimeMs`	ファイルの一致をスキャンするのにかかった時間。
`rewriteTimeMs`	一致したファイルの書き換えにかかった時間。

メトリクス名	説明
`numAddedFiles`	追加されたファイルの数。
`numRemovedFiles`	削除されたファイルの数。
`numUpdatedRows`	更新された行数。
`numCopiedRows`	ファイルの更新プロセスでコピーされた行数。
`executionTimeMs`	オペレーション全体の実行にかかった時間。
`scanTimeMs`	ファイルの一致をスキャンするのにかかった時間。
`rewriteTimeMs`	一致したファイルの書き換えにかかった時間。

`FSCK`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`numRemovedFiles`	削除されたファイルの数。

`CONVERT`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`numConvertedFiles`	変換された Parquet ファイルの数。

`OPTIMIZE`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`numAddedFiles`	追加されたファイルの数。
`numRemovedFiles`	最適化されたファイルの数。
`numAddedBytes`	テーブルが最適化された後に追加されたバイト数。
`numRemovedBytes`	削除されたバイト数。
`minFileSize`	テーブルが最適化された後の最小ファイルのサイズ。
`p25FileSize`	テーブルが最適化された後の25パーセンタイルファイルのサイズ。
`p50FileSize`	テーブルが最適化された後のファイルサイズの中央値。
`p75FileSize`	テーブルが最適化された後の75パーセンタイルファイルのサイズ。
`maxFileSize`	テーブルが最適化された後の最大ファイルのサイズ。

メトリクス名	説明
`numAddedFiles`	追加されたファイルの数。
`numRemovedFiles`	最適化されたファイルの数。
`numAddedBytes`	テーブルが最適化された後に追加されたバイト数。
`numRemovedBytes`	削除されたバイト数。
`minFileSize`	テーブルが最適化された後の最小ファイルのサイズ。
`p25FileSize`	テーブルが最適化された後の25パーセンタイルファイルのサイズ。
`p50FileSize`	テーブルが最適化された後のファイルサイズの中央値。
`p75FileSize`	テーブルが最適化された後の75パーセンタイルファイルのサイズ。
`maxFileSize`	テーブルが最適化された後の最大ファイルのサイズ。

`CLONE`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`sourceTableSize`	クローン作成されたバージョンでのソーステーブルのサイズ（バイト単位）。
`sourceNumOfFiles`	クローン作成されたバージョンでのソーステーブル内のファイル数。
`numRemovedFiles`	以前のテーブルが置き換えられた場合にターゲットテーブルから削除されたファイルの数。
`removedFilesSize`	以前のテーブルが置き換えられた場合にターゲットテーブルから削除されたファイルの合計サイズ（バイト単位）。
`numCopiedFiles`	新しい場所にコピーされたファイルの数。シャロークローンの場合は0。
`copiedFilesSize`	新しい場所にコピーされたファイルの合計サイズ（バイト単位）。シャロークローンの場合は0。

メトリクス名	説明
`sourceTableSize`	クローン作成されたバージョンでのソーステーブルのサイズ（バイト単位）。
`sourceNumOfFiles`	クローン作成されたバージョンでのソーステーブル内のファイル数。
`numRemovedFiles`	以前のテーブルが置き換えられた場合にターゲットテーブルから削除されたファイルの数。
`removedFilesSize`	以前のテーブルが置き換えられた場合にターゲットテーブルから削除されたファイルの合計サイズ（バイト単位）。
`numCopiedFiles`	新しい場所にコピーされたファイルの数。シャロークローンの場合は0。
`copiedFilesSize`	新しい場所にコピーされたファイルの合計サイズ（バイト単位）。シャロークローンの場合は0。

`RESTORE`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`tableSizeAfterRestore`	復元後のテーブルサイズ（バイト単位）。
`numOfFilesAfterRestore`	復元後のテーブル内のファイルの数。
`numRemovedFiles`	復元オペレーションによって削除されたファイルの数。
`numRestoredFiles`	復元の結果として追加されたファイルの数。
`removedFilesSize`	リストアによって削除されたファイルのサイズ（バイト単位）。
`restoredFilesSize`	リストアによって追加されたファイルのサイズ（バイト単位）。

メトリクス名	説明
`tableSizeAfterRestore`	復元後のテーブルサイズ（バイト単位）。
`numOfFilesAfterRestore`	復元後のテーブル内のファイルの数。
`numRemovedFiles`	復元オペレーションによって削除されたファイルの数。
`numRestoredFiles`	復元の結果として追加されたファイルの数。
`removedFilesSize`	リストアによって削除されたファイルのサイズ（バイト単位）。
`restoredFilesSize`	リストアによって追加されたファイルのサイズ（バイト単位）。

`VACUUM`

このオペレーションでは、次のメトリクスを利用できます：

メトリクス名	説明
`numDeletedFiles`	削除されたファイルの数。
`numVacuumedDirectories`	vacuum処理されたディレクトリの数。
`numFilesToDelete`	削除するファイルの数。

メトリクス名	説明
`numDeletedFiles`	削除されたファイルの数。
`numVacuumedDirectories`	vacuum処理されたディレクトリの数。
`numFilesToDelete`	削除するファイルの数。

履歴スキーマ​

オペレーションパラメーターにおけるpartitionByの理解​

例​

運用メトリクス​

WRITE、CREATE TABLE AS SELECT、REPLACE TABLE AS SELECT、 COPY INTO​

STREAMING UPDATE​

DELETE​

TRUNCATE​

MERGE​

UPDATE​

FSCK​

CONVERT​

OPTIMIZE​

CLONE​

RESTORE​

VACUUM​

履歴スキーマ

オペレーションパラメーターにおける`partitionBy`の理解

例

運用メトリクス

`WRITE`、`CREATE TABLE AS SELECT`、`REPLACE TABLE AS SELECT`、 `COPY INTO`

`STREAMING UPDATE`

`DELETE`

`TRUNCATE`

`MERGE`

`UPDATE`

`FSCK`

`CONVERT`

`OPTIMIZE`

`CLONE`

`RESTORE`

`VACUUM`