表实用命令

Delta 表支持许多实用程序命令。

对于许多 Delta Lake 操作，您可以通过在创建新的 SparkSession 时设置配置来启用与 Apache Spark DataSourceV2 和 Catalog API（从 3.0 开始）的集成。请参阅配置 SparkSession。

移除 Delta 表不再引用的文件

您可以通过对表运行 vacuum 命令来移除 Delta 表不再引用且早于保留阈值的文件。vacuum 不会自动触发。文件的默认保留阈值为 7 天。要更改此行为，请参阅数据保留。

重要

• vacuum 会从 Delta Lake 未管理的目录中删除所有文件，并忽略以下划线 _ 开头的目录。如果您在 Delta 表目录中存储额外的元数据（例如结构化流检查点），请使用 _checkpoints 等目录名称。
• vacuum 仅删除数据文件，不删除日志文件。日志文件在检查点操作后会自动异步删除。日志文件的默认保留期为 30 天，可通过 delta.logRetentionDuration 属性进行配置，您可以使用 ALTER TABLE SET TBLPROPERTIES SQL 方法设置此属性。请参阅表属性。
• 运行 vacuum 后，时间旅行回溯到早于保留期的版本的功能将丢失。

SQL

VACUUM eventsTable   -- This runs VACUUM in ‘FULL’ mode and deletes data files outside of the retention duration and all files in the table directory not referenced by the table.

VACUUM eventsTable LITE   -- This VACUUM in ‘LITE’ mode runs faster.
                          -- Instead of finding all files in the table directory, `VACUUM LITE` uses the Delta transaction log to identify and remove files no longer referenced by any table versions within the retention duration.
                          -- If `VACUUM LITE` cannot be completed because the Delta log has been pruned a `DELTA_CANNOT_VACUUM_LITE` exception is raised.
                          -- This mode is available only in Delta 3.3 and above.

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

VACUUM eventsTable USING INVENTORY inventoryTable  —- vacuum files based on a provided reservoir of files as a delta table

VACUUM eventsTable USING INVENTORY (select * from inventoryTable)  —- vacuum files based on a provided reservoir of files as spark SQL query

Python

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

Scala

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

Java

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

注意

使用 VACUUM 时，若要配置 Spark 以并行删除文件（基于 shuffle 分区的数量），请将会话配置 "spark.databricks.delta.vacuum.parallelDelete.enabled" 设置为 "true"。

请参阅 Delta Lake API 以获取 Scala、Java 和 Python 语法详细信息。

注意

建议您将保留间隔设置为至少 7 天，因为旧快照和未提交的文件仍可能被表的并发读取器或写入器使用。如果 VACUUM 清理活动文件，并发读取器可能会失败，或者更糟糕的是，当 VACUUM 删除尚未提交的文件时，表可能会损坏。您必须选择一个间隔，该间隔要长于最长的并发事务运行时间以及任何流落后于表最新更新的最长时间。

Delta Lake 具有一项安全检查，可防止您运行危险的 VACUUM 命令。如果您确定此表上没有执行任何耗时超过您计划指定的保留间隔的操作，则可以通过将 Spark 配置属性 spark.databricks.delta.retentionDurationCheck.enabled 设置为 false 来关闭此安全检查。

清单表

清单表包含文件路径列表及其大小、类型（是否为目录）和上次修改时间。当提供 INVENTORY 选项时，VACUUM 将考虑其中列出的文件，而不是对表目录进行完整列表，这对于非常大的表可能非常耗时。清单表可以指定为 delta 表或 spark SQL 查询，提供预期的表架构。架构应如下所示：

列名	类型	描述
路径	字符串	完全限定 URI
长度	整数	大小（字节）
isDir	boolean	布尔值，指示是否为目录
modificationTime	整数	文件更新时间（毫秒）

检索 Delta 表历史记录

您可以通过运行 history 命令检索 Delta 表每次写入操作的信息，例如操作、用户、时间戳等。操作按时间倒序返回。默认情况下，表历史记录保留 30 天。

请参阅配置 SparkSession，了解如何在 Apache Spark 中启用 SQL 命令支持的步骤。

SQL

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

Python

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

Scala

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

Java

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

请参阅 Delta Lake API，了解 Scala/Java/Python 语法详细信息。

history 操作的输出具有以下列。

列	类型	描述
版本	long	操作生成的表版本。
时间戳	时间戳	此版本提交的时间。
userId	字符串	运行该操作的用户 ID。
userName	字符串	运行该操作的用户姓名。
操作	字符串	操作名称。
operationParameters	地图	操作参数（例如，谓词）。
作业	结构体	运行该操作的作业详细信息。
笔记本	结构体	运行该操作的笔记本详细信息。
clusterId	字符串	运行该操作的集群 ID。
readVersion	long	执行写入操作时读取的表版本。
isolationLevel	字符串	此操作使用的隔离级别。
isBlindAppend	boolean	此操作是否附加数据。
operationMetrics	地图	操作指标（例如，修改的行数和文件数）。
userMetadata	字符串	如果指定，用户定义的提交元数据

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

注意

某些列可能为 null，因为您的环境中可能不提供相应信息。- 将来添加的列将始终在最后一列之后添加。

history 操作在 operationMetrics 列映射中返回操作指标的集合。

下表列出了按操作分类的映射键定义。

Operation	指标名称	描述
写入、创建表 AS SELECT、替换表 AS SELECT、复制到
	numFiles	写入的文件数。
	numOutputBytes	写入内容的字节大小。
	numOutputRows	写入的行数。
流式更新
	numAddedFiles	添加的文件数。
	numRemovedFiles	移除的文件数。
	numOutputRows	写入的行数。
	numOutputBytes	写入大小（字节）。
删除
	numAddedFiles	添加的文件数。删除表分区时不提供。
	numRemovedFiles	移除的文件数。
	numDeletedRows	删除的行数。删除表分区时不提供。
	numCopiedRows	删除文件过程中复制的行数。
	executionTimeMs	执行整个操作所花费的时间。
	scanTimeMs	扫描文件以查找匹配项所花费的时间。
	rewriteTimeMs	重写匹配文件所花费的时间。
截断
	numRemovedFiles	移除的文件数。
	executionTimeMs	执行整个操作所花费的时间。
合并
	numSourceRows	源 DataFrame 中的行数。
	numTargetRowsInserted	插入到目标表中的行数。
	numTargetRowsUpdated	目标表中更新的行数。
	numTargetRowsDeleted	目标表中删除的行数。
	numTargetRowsCopied	复制的目标行数。
	numOutputRows	写入的总行数。
	numTargetFilesAdded	添加到接收器（目标）的文件数。
	numTargetFilesRemoved	从接收器（目标）移除的文件数。
	executionTimeMs	执行整个操作所花费的时间。
	scanTimeMs	扫描文件以查找匹配项所花费的时间。
	rewriteTimeMs	重写匹配文件所花费的时间。
更新
	numAddedFiles	添加的文件数。
	numRemovedFiles	移除的文件数。
	numUpdatedRows	更新的行数。
	numCopiedRows	更新文件过程中仅复制的行数。
	executionTimeMs	执行整个操作所花费的时间。
	scanTimeMs	扫描文件以查找匹配项所花费的时间。
	rewriteTimeMs	重写匹配文件所花费的时间。
FSCK	numRemovedFiles	移除的文件数。
转换	numConvertedFiles	已转换的 Parquet 文件数。
优化
	numAddedFiles	添加的文件数。
	numRemovedFiles	优化的文件数。
	numAddedBytes	表优化后添加的字节数。
	numRemovedBytes	删除的字节数。
	minFileSize	表优化后最小文件的大小。
	p25FileSize	表优化后第 25 百分位数文件的大小。
	p50FileSize	表优化后中位数文件大小。
	p75FileSize	表优化后第 75 百分位数文件的大小。
	maxFileSize	表优化后最大文件的大小。
VACUUM
	numDeletedFiles	已删除的文件数。
	numVacuumedDirectories	已清理的目录数。
	numFilesToDelete	要删除的文件数。
恢复
	tableSizeAfterRestore	恢复后表的大小（字节）。
	numOfFilesAfterRestore	恢复后表中的文件数。
	numRemovedFiles	恢复操作删除的文件数。
	numRestoredFiles	由于恢复而添加的文件数。
	removedFilesSize	恢复删除的文件大小（字节）。
	restoredFilesSize	恢复添加的文件大小（字节）。

检索 Delta 表详细信息

您可以使用 DESCRIBE DETAIL 检索 Delta 表的详细信息（例如，文件数量、数据大小）。

请参阅配置 SparkSession，了解如何在 Apache Spark 中启用 SQL 命令支持的步骤。

SQL

DESCRIBE DETAIL '/data/events/'

DESCRIBE DETAIL eventsTable

Python

from delta.tables import *

deltaTable = DeltaTable.forPath(spark, pathToTable)

detailDF = deltaTable.detail()

Scala

import io.delta.tables._

val deltaTable = DeltaTable.forPath(spark, pathToTable)

val detailDF = deltaTable.detail()

Java

import io.delta.tables.*;

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

DataFrame detailDF = deltaTable.detail();

请参阅 Delta Lake API，了解 Scala/Java/Python 语法详细信息。

此操作的输出只有一行，其架构如下。

列	类型	描述
格式	字符串	表的格式，即 delta。
ID	字符串	表的唯一 ID。
名称	字符串	在元存储中定义的表名称。
描述	字符串	表的描述。
location	字符串	表的存储位置。
createdAt	时间戳	表创建时间。
lastModified	时间戳	表上次修改时间。
partitionColumns	字符串数组	如果表已分区，则为分区列的名称。
numFiles	long	表中最新版本的文件数量。
sizeInBytes	int	表最新快照的大小（字节）。
properties	字符串到字符串的映射	为此表设置的所有属性。
minReaderVersion	int	可以读取表的读取器（根据日志协议）的最小版本。
minWriterVersion	int	可以写入表的写入器（根据日志协议）的最小版本。

+------+--------------------+------------------+-----------+--------------------+--------------------+-------------------+----------------+--------+-----------+----------+----------------+----------------+
|format|                  id|              name|description|            location|           createdAt|       lastModified|partitionColumns|numFiles|sizeInBytes|properties|minReaderVersion|minWriterVersion|
+------+--------------------+------------------+-----------+--------------------+--------------------+-------------------+----------------+--------+-----------+----------+----------------+----------------+
| delta|d31f82d2-a69f-42e...|default.deltatable|       null|file:/Users/tuor/...|2020-06-05 12:20:...|2020-06-05 12:20:20|              []|      10|      12345|        []|               1|               2|
+------+--------------------+------------------+-----------+--------------------+--------------------+-------------------+----------------+--------+-----------+----------+----------------+----------------+

生成清单文件

您可以为 Delta 表生成清单文件，其他处理引擎（即 Apache Spark 以外的引擎）可以使用该文件读取 Delta 表。例如，要生成可供 Presto 和 Athena 读取 Delta 表的清单文件，您可以运行以下命令：

SQL

GENERATE symlink_format_manifest FOR TABLE delta.`<path-to-delta-table>`

Python

deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Scala

val deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Java

DeltaTable deltaTable = DeltaTable.forPath(<path-to-delta-table>);
deltaTable.generate("symlink_format_manifest");

请参阅配置 SparkSession，了解如何在 Apache Spark 中启用 SQL 命令支持的步骤。

将 Parquet 表转换为 Delta 表

将 Parquet 表原地转换为 Delta 表。此命令列出目录中的所有文件，创建一个跟踪这些文件的 Delta Lake 事务日志，并通过读取所有 Parquet 文件的页脚自动推断数据模式。如果您的数据已分区，则必须将分区列的模式指定为 DDL 格式的字符串（即 <column-name1> <type>, <column-name2> <type>, ...）。

默认情况下，此命令将收集每个文件的统计信息（例如，每列的最小值和最大值）。这些统计信息将在查询时用于提供更快的查询。您可以使用 NO STATISTICS 在 SQL API 中禁用此统计信息收集。

注意

如果 Parquet 表是由结构化流式处理创建的，则可以通过将 _spark_metadata 子目录用作表中包含文件的真实来源，并将 SQL 配置 spark.databricks.delta.convert.useMetadataLog 设置为 true 来避免文件列表。

SQL

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

-- Convert unpartitioned Parquet table and disable statistics collection
CONVERT TO DELTA parquet.`<path-to-table>` NO STATISTICS

-- 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)

-- Convert partitioned Parquet table and disable statistics collection
CONVERT TO DELTA parquet.`<path-to-table>` NO STATISTICS PARTITIONED BY (part int, part2 int)

Python

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")

Scala

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")

Java

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 时可能会被删除。您应该避免在转换过程中更新或追加数据文件。表转换后，请确保所有写入都通过 Delta Lake 进行。

将 Iceberg 表转换为 Delta 表

注意

它在 Delta Lake 2.3 及更高版本中可用。

如果 Iceberg 表的基础文件格式是 Parquet，您可以将 Iceberg 表原地转换为 Delta 表。与从 Parquet 表转换类似，此转换是原地的，不会有任何数据复制或数据重写。原始 Iceberg 表和转换后的 Delta 表具有独立的历史记录，因此只要不触及或删除源数据 Parquet 文件，修改 Delta 表就不会影响 Iceberg 表。

以下命令根据 Iceberg 表的本机文件清单、模式和分区信息创建 Delta Lake 事务日志。转换器还在转换期间收集列统计信息，除非指定了 NO STATISTICS。

SQL

-- Convert the Iceberg table in the path <path-to-table>.
CONVERT TO DELTA iceberg.\`<path-to-table>\`

-- Convert the Iceberg table in the path <path-to-table> without collecting statistics.
CONVERT TO DELTA iceberg.\`<path-to-table>\` NO STATISTICS

重要

需要一个额外的 jar delta-iceberg 才能使用转换器。例如，bin/spark-sql --packages io.delta:delta-spark_2.12:3.0.0,io.delta:delta-iceberg_2.12:3.0.0:...。

delta-iceberg 目前不适用于 Delta Lake 2.4.0 版本，因为 iceberg-spark-runtime 尚不支持 Spark 3.4。它适用于 Delta Lake 2.3.0。

注意

不支持转换 Iceberg 元存储表。 - 不支持转换已发生分区演变的 Iceberg 表。 - 不支持转换已发生更新、删除或合并的 Iceberg merge-on-read 表。

将 Delta 表转换为 Parquet 表

您可以使用以下步骤轻松地将 Delta 表转换回 Parquet 表

1. 如果您执行了可能更改数据文件的 Delta Lake 操作（例如 delete 或 merge），请运行 vacuum （保留期为 0 小时）以删除所有不属于表最新版本的数据文件。
2. 删除表目录中的 _delta_log 目录。

将 Delta 表恢复到较早状态

您可以使用 RESTORE 命令将 Delta 表恢复到其较早的状态。Delta 表内部维护表的历史版本，使其能够恢复到较早的状态。RESTORE 命令支持与较早状态对应的版本或创建较早状态时的时间戳作为选项。

重要

• 您可以恢复已恢复的表。
• 恢复到数据文件被手动删除或被 vacuum 删除的旧版本将失败。如果 spark.sql.files.ignoreMissingFiles 设置为 true，则仍然可以部分恢复到此版本。
• 恢复到早期状态的时间戳格式为 yyyy-MM-dd HH:mm:ss。也支持仅提供日期 (yyyy-MM-dd) 字符串。

SQL

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

Python

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

Scala

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

Java

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 日志条目包含 dataChange 设置为 true。如果存在下游应用程序（例如处理 Delta Lake 表更新的 结构化流作业），则由恢复操作添加的数据更改日志条目将被视为新的数据更新，处理它们可能导致重复数据。

例如

表版本	Operation	Delta 日志更新	数据更改日志更新中的记录
0	插入	AddFile(/path/to/file-1, dataChange = true)	(name = Viktor, age = 29), (name = George, age = 55)
1	插入	AddFile(/path/to/file-2, dataChange = true)	(name = George, age = 39)
2	优化	AddFile(/path/to/file-3, dataChange = false), RemoveFile(/path/to/file-1), RemoveFile(/path/to/file-2)	（无记录，因为优化压缩不会更改表中的数据）
3	RESTORE(version=1)	RemoveFile(/path/to/file-3), AddFile(/path/to/file-1, dataChange = true), AddFile(/path/to/file-2, dataChange = true)	(name = Viktor, age = 29), (name = George, age = 55), (name = George, age = 39)

在前面的示例中，RESTORE 命令导致已在读取 Delta 表版本 0 和 1 时看到的更新。如果流式查询正在读取此表，则这些文件将被视为新添加的数据并再次处理。

RESTORE 在操作完成后将以下指标报告为单行 DataFrame

• table_size_after_restore: 恢复后表的大小。
• num_of_files_after_restore: 恢复后表中的文件数。
• num_removed_files: 从表中删除（逻辑删除）的文件数。
• num_restored_files: 由于回滚而恢复的文件数。
• removed_files_size: 从表中删除的文件总大小（字节）。
• restored_files_size: 恢复的文件总大小（字节）。

浅克隆 Delta 表

注意

它在 Delta Lake 2.3 及更高版本中可用。

您可以使用 shallow clone 命令以特定版本创建现有 Delta 表的浅层副本。

对浅层副本所做的任何更改只影响副本本身，而不影响源表，只要它们不触及源数据 Parquet 文件。

克隆的元数据包括：模式、分区信息、不变性、可为空性。对于浅层克隆，流元数据不克隆。未克隆的元数据是表描述和用户定义的提交元数据。

重要

• 浅克隆引用源目录中的数据文件。如果您在源表上运行 vacuum，客户端将无法再读取引用的数据文件，并且将抛出 FileNotFoundException。在这种情况下，使用 replace 对浅克隆运行克隆将修复该克隆。
• 如果目标路径已存在非 Delta 表，则使用 replace 克隆到该目标将创建 Delta 日志。然后，您可以通过运行 vacuum 清理任何现有数据。
• 如果目标路径中存在 Delta 表，则会创建一个新提交，其中包含来自源表的新元数据和新数据。在 replace 的情况下，需要首先清空目标表以避免数据重复。
• 克隆表与 Create Table As Select 或 CTAS 不同。浅克隆获取源表的元数据。克隆还具有更简单的语法：您无需指定分区、格式、不变性、可为空性等，因为它们取自源表。
• 克隆表与源表具有独立的历程。在克隆表上进行时间旅行查询时，输入与在源表上进行时间旅行查询时不同。例如，如果源表版本为 100，我们通过克隆它来创建一个新表，则新表的版本将为 0，因此我们无法在新表上运行时间旅行查询，例如 SELECT * FROM tbl AS OF VERSION 99。

SQL

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

CREATE OR REPLACE TABLE db.target_table SHALLOW CLONE db.source_table -- Replace the target. target needs to be emptied

CREATE TABLE IF NOT EXISTS delta.`/data/target/` SHALLOW 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)

CLONE 在操作完成后将以下指标作为单行 DataFrame 报告

• source_table_size: 正在克隆的源表大小（以字节为单位）。
• source_num_of_files: 源表中的文件数量。

云提供商权限

如果您已创建浅层克隆，则任何读取浅层克隆的用户都需要权限才能读取原始表中的文件，因为数据文件保留在克隆源表的目录中。要更改克隆，用户需要对克隆目录具有写入权限。

克隆用例

机器学习流程复现

在进行机器学习时，您可能希望存档训练 ML 模型的某个版本的表。未来的模型可以使用此存档数据集进行测试。

SQL

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

对生产表进行短期实验

为了在生产表上测试工作流而不损坏表，您可以轻松创建一个浅层克隆。这允许您在包含所有生产数据的克隆表上运行任意工作流，而不会影响任何生产工作负载。

SQL

-- 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;

表属性覆盖

表属性覆盖对于以下情况特别有用

• 与不同的业务部门共享数据时，使用所有者或用户信息对表进行注释。
• 归档 Delta 表并需要时间旅行。您可以为归档表独立指定日志保留期。例如

SQL

CREATE OR REPLACE TABLE archive.my_table SHALLOW CLONE prod.my_table
TBLPROPERTIES (
  delta.logRetentionDuration = '3650 days',
  delta.deletedFileRetentionDuration = '3650 days'
)
LOCATION 'xx://archive/my_table'

将 Parquet 或 Iceberg 表克隆到 Delta

注意

它在 Delta Lake 2.3 及更高版本中可用。

Parquet 和 Iceberg 的浅层克隆结合了用于克隆 Delta 表和将表转换为 Delta Lake 的功能，您可以使用克隆功能将数据从 Parquet 或 Iceberg 数据源转换为托管或外部 Delta 表，并使用相同的基本语法。

replace 具有与 Delta 浅层克隆相同的限制，即目标表在应用 replace 之前必须清空。

SQL

CREATE OR REPLACE TABLE <target_table_name> SHALLOW CLONE parquet.`/path/to/data`;

CREATE OR REPLACE TABLE <target_table_name> SHALLOW CLONE iceberg.`/path/to/data`;