テーブル ユーティリティ コマンドTable utility commands

デルタテーブルでは、多くのユーティリティコマンドがサポートしています。Delta tables support a number of utility commands.

デルタテーブルによって参照されなくなったファイルを削除する Remove files no longer referenced by a Delta table

テーブルでコマンドを実行すると、デルタテーブルによって参照されなくなったファイルを削除し、保有期間のしきい値よりも古いファイルを削除することができ vacuum ます。You can remove files no longer referenced by a Delta table and are older than the retention threshold by running the vacuum command on the table. vacuum 自動的にはトリガーされません。vacuum is not triggered automatically. ファイルの既定の保有期間のしきい値は7日です。The default retention threshold for the files is 7 days.

重要

  • vacuum ログファイルではなく、データファイルのみを削除します。vacuum deletes only data files, not log files. チェックポイント操作の後、ログファイルは自動的に削除され、非同期的に削除されます。Log files are deleted automatically and asynchronously after checkpoint operations. ログファイルの既定の保有期間は30日間で、 delta.logRetentionDuration SQL メソッドで設定したプロパティを使用して構成でき ALTER TABLE SET TBLPROPERTIES ます。The default retention period of log files is 30 days, configurable through the delta.logRetentionDuration property which you set with the ALTER TABLE SET TBLPROPERTIES SQL method. テーブルのプロパティ」を参照してください。See Table properties.
  • 保有期間よりも古いバージョンに 時間を移動 する機能は、実行後に失われ vacuum ます。The ability to time travel back to a version older than the retention period is lost after running vacuum.

SQLSQL

VACUUM eventsTable   -- vacuum files not required by versions older than the default retention period

VACUUM '/data/events' -- vacuum files in path-based table

VACUUM delta.`/data/events/`

VACUUM delta.`/data/events/` RETAIN 100 HOURS  -- vacuum files not required by versions more than 100 hours old

VACUUM eventsTable DRY RUN    -- do dry run to get the list of files to be deleted

構文の詳細については、「」をご覧ください。For syntax details, see

  • Databricks Runtime 2.x 以降: 真空Databricks Runtime 7.x and above: VACUUM
  • Databricks Runtime 5.5 LTS と 6.x: 真空Databricks Runtime 5.5 LTS and 6.x: Vacuum

PythonPython

注意

Python API は Databricks Runtime 6.1 以降で使用できます。The Python API is available in Databricks Runtime 6.1 and above.

from delta.tables import *

deltaTable = DeltaTable.forPath(spark, pathToTable)  # path-based tables, or
deltaTable = DeltaTable.forName(spark, tableName)    # Hive metastore-based tables

deltaTable.vacuum()        # vacuum files not required by versions older than the default retention period

deltaTable.vacuum(100)     # vacuum files not required by versions more than 100 hours old

ScalaScala

注意

スケール a API は Databricks Runtime 6.0 以降で使用できます。The Scala API is available in Databricks Runtime 6.0 and above.

import io.delta.tables._

val deltaTable = DeltaTable.forPath(spark, pathToTable)

deltaTable.vacuum()        // vacuum files not required by versions older than the default retention period

deltaTable.vacuum(100)     // vacuum files not required by versions more than 100 hours old

JavaJava

注意

Java API は Databricks Runtime 6.0 以降で使用できます。The Java API is available in Databricks Runtime 6.0 and above.

import io.delta.tables.*;
import org.apache.spark.sql.functions;

DeltaTable deltaTable = DeltaTable.forPath(spark, pathToTable);

deltaTable.vacuum();        // vacuum files not required by versions older than the default retention period

deltaTable.vacuum(100);     // vacuum files not required by versions more than 100 hours old

スケール a、Java、Python の構文の詳細については、「 デルタ LAKE API リファレンス 」を参照してください。See the Delta Lake API reference for Scala, Java, and Python syntax details.

警告

古いスナップショットやコミットされていないファイルは、テーブルに対する同時実行リーダーまたはライターによって使用されている可能性があるため、保有期間を7日よりも短く設定することはお勧めしません。We do not recommend that you set a retention interval shorter than 7 days, because old snapshots and uncommitted files can still be in use by concurrent readers or writers to the table. vacuum アクティブなファイルをクリーンアップすると、同時実行リーダーが失敗するか、または、 vacuum まだコミットされていないファイルを削除したときにテーブルが破損する可能性があります。If vacuum cleans up active files, concurrent readers can fail or, worse, tables can be corrupted when vacuum deletes files that have not yet been committed.

危険なコマンドを実行できないようにするために、Delta Lake には安全性チェックがあり vacuum ます。Delta Lake has a safety check to prevent you from running a dangerous vacuum command. このテーブルに対して、指定した保有期間よりも長くかかる操作がないことがわかっている場合は、[Apache Spark の構成] プロパティをに設定して、この安全性チェックをオフにすることができ spark.databricks.delta.retentionDurationCheck.enabled false ます。If you are certain that there are no operations being performed on this table that take longer than the retention interval you plan to specify, you can turn off this safety check by setting the Apache Spark configuration property spark.databricks.delta.retentionDurationCheck.enabled to false. 実行時間が最長の同時実行トランザクションより長く、任意のストリームがテーブルの最新の更新の背後で遅延する最長期間を選択する必要があります。You must choose an interval that is longer than the longest running concurrent transaction and the longest period that any stream can lag behind the most recent update to the table.

デルタテーブルの履歴の取得 Retrieve Delta table history

コマンドを実行すると、デルタテーブルへの書き込みごとに、操作、ユーザー、タイムスタンプなどの情報を取得でき history ます。You can retrieve information on the operations, user, timestamp, and so on for each write to a Delta table by running the history command. 操作は、時系列の逆の順序で返されます。The operations are returned in reverse chronological order. 既定では、テーブル履歴は30日間保持されます。By default table history is retained for 30 days.

SQLSQL

DESCRIBE HISTORY '/data/events/'          -- get the full history of the table

DESCRIBE HISTORY delta.`/data/events/`

DESCRIBE HISTORY '/data/events/' LIMIT 1  -- get the last operation only

DESCRIBE HISTORY eventsTable

Spark SQL 構文の詳細については、「」を参照してください。For Spark SQL syntax details, see

PythonPython

注意

Python API は Databricks Runtime 6.1 以降で使用できます。The Python API is available in Databricks Runtime 6.1 and above.

from delta.tables import *

deltaTable = DeltaTable.forPath(spark, pathToTable)

fullHistoryDF = deltaTable.history()    # get the full history of the table

lastOperationDF = deltaTable.history(1) # get the last operation

ScalaScala

注意

スケール a API は Databricks Runtime 6.0 以降で使用できます。The Scala API is available in Databricks Runtime 6.0 and above.

import io.delta.tables._

val deltaTable = DeltaTable.forPath(spark, pathToTable)

val fullHistoryDF = deltaTable.history()    // get the full history of the table

val lastOperationDF = deltaTable.history(1) // get the last operation

JavaJava

注意

Java API は Databricks Runtime 6.0 以降で使用できます。The Java API is available in Databricks Runtime 6.0 and above.

import io.delta.tables.*;

DeltaTable deltaTable = DeltaTable.forPath(spark, pathToTable);

DataFrame fullHistoryDF = deltaTable.history();       // get the full history of the table

DataFrame lastOperationDF = deltaTable.history(1);    // fetch the last operation on the DeltaTable

スケール a/Java/Python 構文の詳細については、「 デルタ LAKE API リファレンス 」を参照してください。See the Delta Lake API reference for Scala/Java/Python syntax details.

履歴スキーマHistory schema

操作の出力 history には、次の列があります。The output of the history operation has the following columns.

ColumnColumn 種類Type 説明Description
versionversion longlong 操作によって生成されるテーブルのバージョン。Table version generated by the operation.
timestamptimestamp timestamptimestamp このバージョンがコミットされたとき。When this version was committed.
userIduserId stringstring 操作を実行したユーザーの ID。ID of the user that ran the operation.
userNameuserName stringstring 操作を実行したユーザーの名前。Name of the user that ran the operation.
operationoperation stringstring 操作の名前。Name of the operation.
operationParametersoperationParameters mapmap 操作のパラメーター (たとえば、述語)Parameters of the operation (for example, predicates.)
ジョブ (job)job structstruct 操作を実行したジョブの詳細。Details of the job that ran the operation.
ノートブックnotebook structstruct 操作が実行されたノートブックの詳細。Details of notebook from which the operation was run.
clusterIdclusterId stringstring 操作が実行されたクラスターの ID。ID of the cluster on which the operation ran.
readVersionreadVersion longlong 書き込み操作を実行するために読み取られたテーブルのバージョン。Version of the table that was read to perform the write operation.
isolationLevelisolationLevel stringstring この操作に使用される分離レベルです。Isolation level used for this operation.
isBlindAppendisBlindAppend booleanboolean この操作によってデータが追加されたかどうか。Whether this operation appended data.
operationMetricsoperationMetrics mapmap 操作のメトリック (変更された行数やファイルの数など)。Metrics of the operation (for example, number of rows and files modified.)
userMetadatauserMetadata stringstring ユーザー定義コミットメタデータ (指定されている場合)User-defined commit metadata if it was specified
+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+
|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...|
+-------+-------------------+------+--------+---------+--------------------+----+--------+---------+-----------+-----------------+-------------+--------------------+

注意

  • 操作メトリックを使用できるのは、履歴コマンド 履歴の操作が Databricks Runtime 6.5 以上を使用して実行された場合のみです。Operation metrics are available only when the history command and the operation in the history were run using Databricks Runtime 6.5 or above.
  • 次の方法を使用してデルタテーブルに書き込む場合、他のいくつかの列は使用できません。A few of the other columns are not available if you write into a Delta table using the following methods:
  • 将来追加される列は、常に最後の列の後に追加されます。Columns added in the future will always be added after the last column.

操作メトリックのキーOperation metrics keys

操作は、 history 列マップ内の操作メトリックのコレクションを返し operationMetrics ます。The history operation returns a collection of operations metrics in the operationMetrics column map.

次の表は、マップのキー定義を操作別に示しています。The following tables list the map key definitions by operation.

OperationOperation メトリックの名前Metric name 説明Description
書き込み、CREATE TABLE として選択、テーブルを SELECT に置き換える、コピー先WRITE, CREATE TABLE AS SELECT, REPLACE TABLE AS SELECT, COPY INTO
numFilesnumFiles 書き込まれたファイルの数。Number of files written.
numOutputBytesnumOutputBytes 書き込まれたコンテンツのサイズ (バイト単位)。Size in bytes of the written contents.
numOutputRowsnumOutputRows 書き込まれた行の数。Number of rows written.
STREAMING UPDATESTREAMING UPDATE
numAddedFilesnumAddedFiles 追加されたファイルの数。Number of files added.
numRemovedFilesnumRemovedFiles 削除されたファイルの数。Number of files removed.
numOutputRowsnumOutputRows 書き込まれた行の数。Number of rows written.
numOutputBytesnumOutputBytes 書き込みのサイズ (バイト単位)。Size of write in bytes.
DELETEDELETE
numAddedFilesnumAddedFiles 追加されたファイルの数。Number of files added. テーブルのパーティションが削除されるときには提供されません。Not provided when partitions of the table are deleted.
numRemovedFilesnumRemovedFiles 削除されたファイルの数。Number of files removed.
numDeletedRowsnumDeletedRows 削除された行数。Number of rows removed. テーブルのパーティションが削除されるときには提供されません。Not provided when partitions of the table are deleted.
numCopiedRowsnumCopiedRows ファイルの削除処理中にコピーされた行数。Number of rows copied in the process of deleting files.
TRUNCATETRUNCATE numRemovedFilesnumRemovedFiles 削除されたファイルの数。Number of files removed.
MERGEMERGE
numSourceRowsnumSourceRows ソースデータフレーム内の行の数。Number of rows in the source DataFrame.
numTargetRowsInsertednumTargetRowsInserted 対象テーブルに挿入された行の数。Number of rows inserted into the target table.
numTargetRowsUpdatednumTargetRowsUpdated ターゲットテーブルで更新された行の数。Number of rows updated in the target table.
numTargetRowsDeletednumTargetRowsDeleted ターゲットテーブルで削除された行の数。Number of rows deleted in the target table.
numTargetRowsCopiednumTargetRowsCopied コピーされたターゲット行の数。Number of target rows copied.
numOutputRowsnumOutputRows 書き込まれた行の合計数。Total number of rows written out.
numTargetFilesAddednumTargetFilesAdded シンク (ターゲット) に追加されたファイルの数。Number of files added to the sink(target).
numTargetFilesRemoved 削除されましたnumTargetFilesRemoved シンク (ターゲット) から削除されたファイルの数。Number of files removed from the sink(target).
UPDATEUPDATE
numAddedFilesnumAddedFiles 追加されたファイルの数。Number of files added.
numRemovedFilesnumRemovedFiles 削除されたファイルの数。Number of files removed.
numUpdatedRowsnumUpdatedRows 更新された行の数。Number of rows updated.
numCopiedRowsnumCopiedRows ファイルの更新処理中にコピーされた行の数。Number of rows just copied over in the process of updating files.
FSCKFSCK numRemovedFilesnumRemovedFiles 削除されたファイルの数。Number of files removed.
CONVERTCONVERT numConvertedFilesnumConvertedFiles 変換された Parquet ファイルの数。Number of Parquet files that have been converted.
OperationOperation メトリックの名前Metric name 説明Description
複製 (1)CLONE (1)
sourceTableSizesourceTableSize 複製されたバージョンのソーステーブルのサイズ (バイト単位)。Size in bytes of the source table at the version that’s cloned.
sourceNumOfFilessourceNumOfFiles 複製されたバージョンのソーステーブル内のファイルの数。Number of files in the source table at the version that’s cloned.
numRemovedFilesnumRemovedFiles 前の差分テーブルが置き換えられた場合に、ターゲットテーブルから削除されたファイルの数。Number of files removed from the target table if a previous Delta table was replaced.
removedFilesSizeremovedFilesSize 前の差分テーブルが置換された場合に、ターゲットテーブルから削除されたファイルの合計サイズ (バイト単位)。Total size in bytes of the files removed from the target table if a previous Delta table was replaced.
numCopiedFilesnumCopiedFiles 新しい場所にコピーされたファイルの数。Number of files that were copied over to the new location. 浅い複製の場合は0。0 for shallow clones.
copiedFilesSizecopiedFilesSize コピーして新しい場所にコピーされたファイルの合計サイズ (バイト単位)。Total size in bytes of the files that were copied copied over to the new location. 浅い複製の場合は0。0 for shallow clones.
復元 (2)RESTORE (2)
すべてのものを復元するtableSizeAfterRestore 復元後のテーブルサイズ (バイト単位)。Table size in bytes after restore.
numOfFilesAfterRestorenumOfFilesAfterRestore 復元後のテーブル内のファイルの数。Number of files in the table after restore.
numRemovedFilesnumRemovedFiles 復元操作によって削除されたファイルの数。Number of files removed by the restore operation.
numRestoredFilesnumRestoredFiles 復元の結果として追加されたファイルの数。Number of files that were added as a result of the restore.
removedFilesSizeremovedFilesSize 復元によって削除されたファイルのサイズ (バイト単位)。Size in bytes of files removed by the restore.
restoredFilesSizerestoredFilesSize 復元によって追加されたファイルのサイズ (バイト単位)。Size in bytes of files added by the restore.
最適化OPTIMIZE
numAddedFilesnumAddedFiles 追加されたファイルの数。Number of files added.
numRemovedFilesnumRemovedFiles 最適化されたファイルの数。Number of files optimized.
numAddedBytesnumAddedBytes テーブルが最適化された後に追加されたバイト数。Number of bytes added after the table was optimized.
numRemovedBytesnumRemovedBytes 削除されたバイト数。Number of bytes removed.
minFileSize サイズminFileSize テーブルが最適化された後の最小ファイルサイズ。Size of the smallest file after the table was optimized.
p25FileSizep25FileSize テーブルが最適化された後の25パーセンタイルファイルのサイズ。Size of the 25th percentile file after the table was optimized.
p50FileSizep50FileSize テーブルが最適化された後のファイルサイズの中央値。Median file size after the table was optimized.
p75FileSizep75FileSize テーブルが最適化された後の75パーセンタイルファイルのサイズ。Size of the 75th percentile file after the table was optimized.
maxFileSizemaxFileSize テーブルが最適化された後の最大ファイルサイズ。Size of the largest file after the table was optimized.

(1) DATABRICKS RUNTIME 7.3 LTS 以上である必要があります。(1) Requires Databricks Runtime 7.3 LTS or above.

(2) には7.4 以上の Databricks Runtime が必要です。(2) Requires Databricks Runtime 7.4 or above.

デルタテーブルの詳細 の取得 Retrieve Delta table details

を使用して、デルタテーブル (ファイル数、データサイズなど) に関する詳細情報を取得でき DESCRIBE DETAIL ます。You can retrieve detailed information about a Delta table (for example, number of files, data size) using DESCRIBE DETAIL.

DESCRIBE DETAIL '/data/events/'

DESCRIBE DETAIL eventsTable

Spark SQL 構文の詳細については、「」を参照してください。For Spark SQL syntax details, see

詳細スキーマDetail schema

この操作の出力には、次のスキーマを持つ行が1つだけあります。The output of this operation has only one row with the following schema.

ColumnColumn 種類Type [説明]Description
formatformat stringstring テーブルの形式 ("デルタ")。Format of the table, that is, “delta”.
idid stringstring テーブルの一意の ID。Unique ID of the table.
namename stringstring Metastore で定義されているテーブルの名前。Name of the table as defined in the metastore.
descriptiondescription stringstring テーブルの説明。Description of the table.
locationlocation stringstring テーブルの場所。Location of the table.
createdAtcreatedAt タイムスタンプtimestamp テーブルが作成された日時。When the table was created.
lastModifiedlastModified タイムスタンプtimestamp テーブルが最後に変更された日時。When the table was last modified.
partitionColumnspartitionColumns 文字列の配列array of strings テーブルがパーティション分割されている場合は、パーティション列の名前。Names of the partition columns if the table is partitioned.
numFilesnumFiles longlong テーブルの最新バージョンのファイル数。Number of the files in the latest version of the table.
propertiesproperties 文字列マップstring-string map このテーブルに設定されているすべてのプロパティ。All the properties set for this table.
minReaderVersionminReaderVersion INTint テーブルを読み取ることができるリーダーの最小バージョン (ログプロトコルによる)。Minimum version of readers (according to the log protocol) that can read the table.
minWriterVersionminWriterVersion INTint テーブルに書き込むことができるライターの最小バージョン (ログプロトコルによる)。Minimum version of writers (according to the log protocol) that can write to the table.
+------+--------------------+------------------+-----------+--------------------+--------------------+-------------------+----------------+--------+-----------+----------+----------------+----------------+
|format|                  id|              name|description|            location|           createdAt|       lastModified|partitionColumns|numFiles|sizeInBytes|properties|minReaderVersion|minWriterVersion|
+------+--------------------+------------------+-----------+--------------------+--------------------+-------------------+----------------+--------+-----------+----------+----------------+----------------+
| delta|d31f82d2-a69f-42e...|default.deltatable|       null|file:/Users/tdas/...|2020-06-05 12:20:...|2020-06-05 12:20:20|              []|      10|      12345|        []|               1|               2|
+------+--------------------+------------------+-----------+--------------------+--------------------+-------------------+----------------+--------+-----------+----------+----------------+----------------+

Parquet テーブルからデルタテーブルへ の変換 Convert a Parquet table to a Delta table

Parquet テーブルをその場でデルタテーブルに変換します。Convert a Parquet table to a Delta table in-place. このコマンドは、ディレクトリ内のすべてのファイルを一覧表示し、これらのファイルを追跡するデルタ Lake transaction ログを作成し、すべての Parquet ファイルのフッターを読み取ってデータスキーマを自動的に推測します。This command lists all the files in the directory, creates a Delta Lake transaction log that tracks these files, and automatically infers the data schema by reading the footers of all Parquet files. データがパーティション分割されている場合は、パーティション列のスキーマを DDL 形式の文字列 (つまり、) として指定する必要があり <column-name1> <type>, <column-name2> <type>, ... ます。If your data is partitioned, you must specify the schema of the partition columns as a DDL-formatted string (that is, <column-name1> <type>, <column-name2> <type>, ...).

注意

Parquet テーブルが構造化ストリーミングによって作成された場合、ファイルの一覧を回避するには、 _spark_metadata SQL 構成をに設定するテーブルに含まれているファイルのソースとしてサブディレクトリを使用し spark.databricks.delta.convert.useMetadataLog true ます。If a Parquet table was created by Structured Streaming, the listing of files can be avoided by using the _spark_metadata sub-directory as the source of truth for files contained in the table setting the SQL configuration spark.databricks.delta.convert.useMetadataLog to true.

SQLSQL

-- Convert unpartitioned parquet table at path '<path-to-table>'
CONVERT TO DELTA parquet.`<path-to-table>`

-- Convert partitioned Parquet table at path '<path-to-table>' and partitioned by integer columns named 'part' and 'part2'
CONVERT TO DELTA parquet.`<path-to-table>` PARTITIONED BY (part int, part2 int)

構文の詳細については、「」をご覧ください。For syntax details, see

PythonPython

注意

Python API は Databricks Runtime 6.1 以降で使用できます。The Python API is available in Databricks Runtime 6.1 and above.

from delta.tables import *

# Convert unpartitioned parquet table at path '<path-to-table>'
deltaTable = DeltaTable.convertToDelta(spark, "parquet.`<path-to-table>`")

# Convert partitioned parquet table at path '<path-to-table>' and partitioned by integer column named 'part'
partitionedDeltaTable = DeltaTable.convertToDelta(spark, "parquet.`<path-to-table>`", "part int")

ScalaScala

注意

スケール a API は Databricks Runtime 6.0 以降で使用できます。The Scala API is available in Databricks Runtime 6.0 and above.

import io.delta.tables._

// Convert unpartitioned Parquet table at path '<path-to-table>'
val deltaTable = DeltaTable.convertToDelta(spark, "parquet.`<path-to-table>`")

// Convert partitioned Parquet table at path '<path-to-table>' and partitioned by integer columns named 'part' and 'part2'
val partitionedDeltaTable = DeltaTable.convertToDelta(spark, "parquet.`<path-to-table>`", "part int, part2 int")

JavaJava

注意

スケール a API は Databricks Runtime 6.0 以降で使用できます。The Scala API is available in Databricks Runtime 6.0 and above.

import io.delta.tables.*;

// Convert unpartitioned parquet table at path '<path-to-table>'
DeltaTable deltaTable = DeltaTable.convertToDelta(spark, "parquet.`<path-to-table>`");

// Convert partitioned Parquet table at path '<path-to-table>' and partitioned by integer columns named 'part' and 'part2'
DeltaTable deltaTable = DeltaTable.convertToDelta(spark, "parquet.`<path-to-table>`", "part int, part2 int");

注意

Delta Lake によって追跡されていないファイルは表示されず、を実行すると削除でき vacuum ます。Any file not tracked by Delta Lake is invisible and can be deleted when you run vacuum. 変換処理中は、データファイルの更新または追加を避ける必要があります。You should avoid updating or appending data files during the conversion process. テーブルが変換されたら、すべての書き込みがデルタレイクを経由するようにします。After the table is converted, make sure all writes go through Delta Lake.

Delta テーブルを Parquet テーブルに変換するConvert a Delta table to a Parquet table

次の手順を使用して、デルタテーブルを Parquet テーブルに簡単に変換できます。You can easily convert a Delta table back to a Parquet table using the following steps:

  1. データファイルを変更できるデルタレイク操作 (やなど) を実行した場合は、 delete merge リテンション期間0時間で vacuum を実行し、最新バージョンのテーブルに属していないすべてのデータファイルを削除します。If you have performed Delta Lake operations that can change the data files (for example, delete or merge), run vacuum with retention of 0 hours to delete all data files that do not belong to the latest version of the table.
  2. _delta_logテーブルディレクトリ内のディレクトリを削除します。Delete the _delta_log directory in the table directory.

以前の状態にデルタテーブルを復元する Restore a Delta table to an earlier state

重要

この機能はパブリック プレビュー段階にあります。This feature is in Public Preview.

注意

Databricks Runtime 7.4 以降で使用できます。Available in Databricks Runtime 7.4 and above.

コマンドを使用して、デルタテーブルを以前の状態に復元でき RESTORE ます。You can restore a Delta table to its earlier state by using the RESTORE command. デルタテーブルは、以前の状態に復元できるようにするために、テーブルの履歴バージョンを内部的に保持します。A Delta table internally maintains historic versions of the table that enable it to be restored to an earlier state. 以前の状態に対応するバージョンまたは以前の状態が作成されたときのタイムスタンプは、コマンドによってオプションとしてサポートされ RESTORE ます。A version corresponding to the earlier state or a timestamp of when the earlier state was created are supported as options by the RESTORE command.

重要

  • 既に復元されたテーブルと 複製 されたテーブルを復元できます。You can restore an already restored table and cloned tables.
  • データファイルが手動またはによって削除された古いバージョンにテーブルを復元すると、 vacuum が失敗します。Restoring a table to an older version where the data files were deleted manually or by vacuum will fail. がに設定されている場合、このバージョンの部分的な復元は引き続き可能です spark.sql.files.ignoreMissingFiles trueRestoring to this version partially is still possible if spark.sql.files.ignoreMissingFiles is set to true.
  • 以前の状態に復元するためのタイムスタンプ形式は yyyy-MM-dd HH:mm:ss です。The timestamp format for restoring to an earlier state is yyyy-MM-dd HH:mm:ss. 日付 () 文字列のみを指定する yyyy-MM-dd こともできます。Providing only a date(yyyy-MM-dd) string is also supported.

SQLSQL

RESTORE TABLE db.target_table TO VERSION AS OF <version>
RESTORE TABLE delta.`/data/target/` TO TIMESTAMP AS OF <timestamp>

PythonPython

from delta.tables import *

deltaTable = DeltaTable.forPath(spark, <path-to-table>)  # path-based tables, or
deltaTable = DeltaTable.forName(spark, <table-name>)    # Hive metastore-based tables

deltaTable.restoreToVersion(0) # restore table to oldest version

deltaTable.restoreToTimestamp('2019-02-14') # restore to a specific timestamp

ScalaScala

import io.delta.tables._

val deltaTable = DeltaTable.forPath(spark, <path-to-table>)
val deltaTable = DeltaTable.forName(spark, <table-name>)

deltaTable.restoreToVersion(0) // restore table to oldest version

deltaTable.restoreToTimestamp("2019-02-14") // restore to a specific timestamp

JavaJava

import io.delta.tables.*;

DeltaTable deltaTable = DeltaTable.forPath(spark, <path-to-table>);
DeltaTable deltaTable = DeltaTable.forName(spark, <table-name>);

deltaTable.restoreToVersion(0) // restore table to oldest version

deltaTable.restoreToTimestamp("2019-02-14") // restore to a specific timestamp

構文の詳細については、「 RESTORE (Delta Lake on Azure Databricks)」を参照してください。For syntax details, see RESTORE (Delta Lake on Azure Databricks).

テーブルのアクセス制御Table access control

MODIFY復元するテーブルに対する権限が必要です。You must have MODIFY permission on the table being restored.

デルタテーブルの複製 Clone a Delta table

注意

Databricks Runtime 7.2 以降で使用できます。Available in Databricks Runtime 7.2 and above.

コマンドを使用して、特定のバージョンの既存のデルタテーブルのコピーを作成でき clone ます。You can create a copy of an existing Delta table at a specific version using the clone command. 複製は、ディープでも浅いでもかまいません。Clones can be either deep or shallow.

このセクションの内容:In this section:

複製の種類Clone types

  • ディープクローン は、既存のテーブルのメタデータに加えて、ソーステーブルのデータを複製ターゲットにコピーする複製です。A deep clone is a clone that copies the source table data to the clone target in addition to the metadata of the existing table. さらに、ストリームメタデータも複製されるため、デルタテーブルに書き込むストリームをソーステーブルで停止し、中断した場所から複製のターゲットで続行することができます。Additionally, stream metadata is also cloned such that a stream that writes to the Delta table can be stopped on a source table and continued on the target of a clone from where it left off.
  • シャロークローン は、データファイルが複製ターゲットにコピーされない複製です。A shallow clone is a clone that does not copy the data files to the clone target. テーブルのメタデータは、ソースに相当します。The table metadata is equivalent to the source. これらの複製は、作成するとコストが安くなります。These clones are cheaper to create.

ディープクローンまたは浅い複製に加えられたすべての変更は、ソーステーブルではなくクローン自体にのみ影響します。Any changes made to either deep or shallow clones affect only the clones themselves and not the source table.

複製されるメタデータには、スキーマ、パーティション分割情報、インバリアント、null 値の許容属性が含まれます。The metadata that is cloned includes: schema, partitioning information, invariants, nullability. ディープクローンの場合のみ、ストリームと コピー INTO (デルタ Lake on Azure Databricks) のメタデータも複製されます。For deep clones only, stream and COPY INTO (Delta Lake on Azure Databricks) metadata are also cloned. 複製されないメタデータは、テーブルの説明と ユーザー定義のコミットメタデータです。Metadata not cloned are the table description and user-defined commit metadata.

重要

  • シャロークローンは、ソースディレクトリ内のデータファイルを参照します。Shallow clones reference data files in the source directory. vacuumソーステーブルでを実行すると、クライアントは参照されるデータファイルを読み取ることができなくなり、がスローされ FileNotFoundException ます。If you run vacuum on the source table clients will no longer be able to read the referenced data files and a FileNotFoundException will be thrown. この場合、シャロークローンで [置換] を実行すると、複製が修復されます。In this case, running clone with replace over the shallow clone will repair the clone. これが頻繁に発生する場合は、代わりに、ソーステーブルに依存しないディープクローンの使用を検討してください。If this occurs often, consider using a deep clone instead which does not depend on the source table.
  • ディープクローンは、複製元のソースに依存しませんが、ディープクローンによってデータとメタデータがコピーされるため、作成にコストがかかります。Deep clones do not depend on the source from which they were cloned, but are expensive to create because a deep clone copies the data as well as the metadata.
  • replaceそのパスにテーブルが既に存在するターゲットにを使用して複製すると、そのパスにデルタログが存在しない場合は差分ログが作成されます。Cloning with replace to a target that already has a table at that path creates a Delta log if one does not exist at that path. を実行することで、既存のデータをクリーンアップでき vacuum ます。You can clean up any existing data by running vacuum. 既存のテーブルがデルタテーブルの場合は、新しいメタデータとソーステーブルの新しいデータを含む既存のデルタテーブルに新しいコミットが作成されます。If the existing table is a Delta table, a new commit is created on the existing Delta table that includes the new metadata and new data from the source table.
  • テーブルの複製はまたはと同じではありません Create Table As Select CTASCloning a table is not the same as Create Table As Select or CTAS. 複製によって、データに加えてソーステーブルのメタデータもコピーされます。A clone copies the metadata of the source table in addition to the data. 複製には、単純な構文があります。パーティション分割、フォーマット、インバリアント、null 値の許容属性などをソーステーブルから取得するときに指定する必要はありません。Cloning also has simpler syntax: you don’t need to specify partitioning, format, invariants, nullability and so on as they are taken from the source table.
  • 複製されたテーブルには、ソーステーブルとは独立した履歴があります。A cloned table has an independent history from its source table. 複製されたテーブルに対するタイムトラベルクエリは、ソーステーブルでの動作と同じ入力では機能しません。Time travel queries on a cloned table will not work with the same inputs as they work on its source table.

SQLSQL

 CREATE TABLE delta.`/data/target/` CLONE delta.`/data/source/` -- Create a deep clone of /data/source at /data/target

 CREATE OR REPLACE TABLE db.target_table CLONE db.source_table -- Replace the target

 CREATE TABLE IF NOT EXISTS TABLE delta.`/data/target/` CLONE db.source_table -- No-op if the target table exists

 CREATE TABLE db.target_table SHALLOW CLONE delta.`/data/source`

 CREATE TABLE db.target_table SHALLOW CLONE delta.`/data/source` VERSION AS OF version

 CREATE TABLE db.target_table SHALLOW CLONE delta.`/data/source` TIMESTAMP AS OF timestamp_expression -- timestamp can be like “2019-01-01” or like date_sub(current_date(), 1)

PythonPython

 from delta.tables import *

 deltaTable = DeltaTable.forPath(spark, pathToTable)  # path-based tables, or
 deltaTable = DeltaTable.forName(spark, tableName)    # Hive metastore-based tables

 deltaTable.clone(target, isShallow, replace) # clone the source at latest version

 deltaTable.cloneAtVersion(version, target, isShallow, replace) # clone the source at a specific version

# clone the source at a specific timestamp such as timestamp=“2019-01-01”
 deltaTable.cloneAtTimestamp(timestamp, target, isShallow, replace)

ScalaScala

 import io.delta.tables._

 val deltaTable = DeltaTable.forPath(spark, pathToTable)
 val deltaTable = DeltaTable.forName(spark, tableName)

 deltaTable.clone(target, isShallow, replace) // clone the source at latest version

 deltaTable.cloneAtVersion(version, target, isShallow, replace) // clone the source at a specific version

 deltaTable.cloneAtTimestamp(timestamp, target, isShallow, replace) // clone the source at a specific timestamp

JavaJava

 import io.delta.tables.*;

 DeltaTable deltaTable = DeltaTable.forPath(spark, pathToTable);
 DeltaTable deltaTable = DeltaTable.forName(spark, tableName);

 deltaTable.clone(target, isShallow, replace) // clone the source at latest version

 deltaTable.cloneAtVersion(version, target, isShallow, replace) // clone the source at a specific version

 deltaTable.cloneAtTimestamp(timestamp, target, isShallow, replace) // clone the source at a specific timestamp

構文の詳細については、「 CLONE (Delta Lake on Azure Databricks)」を参照してください。For syntax details, see CLONE (Delta Lake on Azure Databricks).

アクセス許可Permissions

Azure Databricks テーブルアクセス制御とクラウドプロバイダーのアクセス許可を構成する必要があります。You must configure permissions for Azure Databricks table access control and your cloud provider.

テーブルのアクセス制御Table access control

ディープ複製と浅い複製には、次のアクセス許可が必要です。The following permissions are required for both deep and shallow clones:

  • SELECT ソーステーブルに対する権限。SELECT permission on the source table.
  • を使用して CLONE 新しいテーブルを作成する場合は、 CREATE テーブルを作成するデータベースに対する権限です。If you are using CLONE to create a new table, CREATE permission on the database in which you are creating the table.
  • を使用してテーブルを置換する場合は、 CLONE MODIFY テーブルに対する権限が必要です。If you are using CLONE to replace a table, you must have MODIFY permission on the table.

クラウドプロバイダーのアクセス許可Cloud provider permissions

ディープクローンを作成した場合は、ディープクローンを読み取るすべてのユーザーに、複製のディレクトリへの読み取りアクセス権が必要です。If you have created a deep clone, any user that reads the deep clone must have read access to the clone’s directory. 複製を変更するには、ユーザーが複製のディレクトリに対する書き込みアクセス権を持っている必要があります。To make changes to the clone, users must have write access to the clone’s directory.

浅い複製を作成した場合、シャロークローンを読み取るすべてのユーザーは、元のテーブル内のファイルを読み取るためのアクセス許可が必要です。これは、データファイルが浅い複製を含むソーステーブルに残り、複製のディレクトリであるためです。If you have created a shallow clone, any user that reads the shallow clone needs permission to read the files in the original table, since the data files remain in the source table with shallow clones, as well as the clone’s directory. 複製を変更するには、ユーザーに複製のディレクトリへの書き込みアクセス権が必要です。To make changes to the clone, users will need write access to the clone’s directory.

ユースケースの複製Clone use cases

このセクションの内容:In this section:

データのアーカイブData archiving

データは、時間の経過と共に、またはディザスターリカバリーに対応できる限り長く保持する必要がある場合があります。Data may need to be kept for longer than is feasible with time travel or for disaster recovery. このような場合は、詳細な複製を作成して、特定の時点におけるテーブルの状態を保存することができます。In these cases, you can create a deep clone to preserve the state of a table at a certain point in time for archival. 増分アーカイブでは、ディザスターリカバリーのためにソーステーブルの状態を継続的に更新することもできます。Incremental archiving is also possible to keep a continually updating state of a source table for disaster recovery.

-- Every month run
CREATE OR REPLACE TABLE delta.`/some/archive/path` CLONE my_prod_table

Machine learning のフローの再現Machine learning flow reproduction

機械学習を行う場合、ML モデルをトレーニングした特定のバージョンのテーブルをアーカイブすることができます。When doing machine learning, you may want to archive a certain version of a table on which you trained an ML model. 将来のモデルは、このアーカイブされたデータセットを使用してテストできます。Future models can be tested using this archived data set.

-- Trained model on version 15 of Delta table
CREATE TABLE delta.`/model/dataset` CLONE entire_dataset VERSION AS OF 15

実稼働テーブルでの短期実験Short-term experiments on a production table

テーブルを破損させずに、実稼働テーブルでワークフローをテストするには、簡易複製を簡単に作成できます。To test a workflow on a production table without corrupting the table, you can easily create a shallow clone. これにより、複製されたテーブルに対して、すべての実稼働データを含む任意のワークフローを実行できますが、運用環境のワークロードには影響しません。This allows you to run arbitrary workflows on the cloned table that contains all the production data but does not affect any production workloads.

-- Perform shallow clone
CREATE OR REPLACE TABLE my_test SHALLOW CLONE my_prod_table;

UPDATE my_test WHERE user_id is null SET invalid=true;
-- Run a bunch of validations. Once happy:

-- This should leverage the update information in the clone to prune to only
-- changed files in the clone if possible
MERGE INTO my_prod_table
USING my_test
ON my_test.user_id <=> my_prod_table.user_id
WHEN MATCHED AND my_test.user_id is null THEN UPDATE *;

DROP TABLE my_test;

データ共有Data sharing

1つの組織内の他の部署は同じデータにアクセスできますが、最新の更新プログラムを必要としない場合があります。Other business units within a single organization may want to access the same data but may not require the latest updates. ソーステーブルへのアクセス権を直接付与する代わりに、さまざまな事業単位に対して異なるアクセス許可を持つ複製を提供できます。Instead of giving access to the source table directly, you can provide clones with different permissions for different business units. 複製のパフォーマンスは、単純なビューを超える場合があります。The performance of the clone can exceed that of a simple view.

  -- Perform deep clone
  CREATE OR REPLACE TABLE shared_table CLONE my_prod_table;

  -- Grant other users access to the shared table
  GRANT SELECT ON shared_table TO `<user-name>@<user-domain>.com`;

テーブルプロパティのオーバーライドTable property overrides

テーブルプロパティのオーバーライドは、次の場合に特に便利です。Table property overrides are particularly useful for:

  • 異なる事業単位でデータを共有するときに、所有者またはユーザー情報を含むテーブルに注釈を付ける。Annotating tables with owner or user information when sharing data with different business units.

  • デルタテーブルとタイムトラベルのアーカイブが必要です。Archiving Delta tables and time travel is required. アーカイブテーブルに対して個別にログの保有期間を指定できます。You can specify the log retention period independently for the archive table. 次に例を示します。For example:

    SQLSQL
    CREATE OR REPLACE archive.my_table CLONE prod.my_table
    LOCATION 'xx://archive/my_table'
    TBLPROPERTIES (
      delta.logRetentionDuration = '3650 days',
      delta.deletedFileRetentionDuration = '3650 days'
    )
    
    PythonPython
    dt = DeltaTable.forName(spark, "prod.my_table")
    tblProps = {
      "delta.logRetentionDuration": "3650 days",
      "delta.deletedFileRetentionDuration": "3650 days"
    }
    dt.clone('xx://archive/my_table', isShallow=False, replace=True, tblProps)
    
    ScalaScala
    val dt = DeltaTable.forName(spark, "prod.my_table")
    val tblProps = Map(
      "delta.logRetentionDuration" -> "3650 days",
      "delta.deletedFileRetentionDuration" -> "3650 days"
    )
    dt.clone("xx://archive/my_table", isShallow = false, replace = true, properties = tblProps)