表实用程序命令

删除Delta表不再引用的文件

您可以通过在表上运行vacuum命令来删除Delta表不再引用且早于保留阈值的文件。vacuum 不会自动触发。文件的默认保留阈值为7天。

检索Delta表历史记录

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

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

%pyspark
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

%spark
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

有关Spark SQL语法的详细信息，请参见

• Databricks Runtime 7.0及更高版本：DESCRIBE HISTORY (Delta Lake on Databricks)

• Databricks Runtime 6.x及更低版本：Describe History (Delta Lake on Databricks)

有关Scala，Java和Python语法的详细信息，请参见API参考。

历史架构

该history操作的输出包含以下列。

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

操作指标键

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

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

• 需要Databricks Runtime 7.3或更高版本。

• 需要Databricks Runtime 7.4或更高版本。

检索Delta表详细信息

可以使用“描述详细信息”检索有关增量表的详细信息（例如，文件数、数据大小）。

SQL

%sql
DESCRIBE DETAIL '/data/events/'

DESCRIBE DETAIL eventsTable

详细架构

此操作的输出只有一行具有以下架构。

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

生成清单文件

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

SQL

%sql
GENERATE symlink_format_manifest FOR TABLE delta.`/mnt/events`

GENERATE symlink_format_manifest FOR TABLE eventsTable

Python

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

Scala

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

将Parquet表转换为Delta表

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

SQL

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

Python

%pyspark
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

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

有关语法的详细信息，请参见

• Databricks运行时7.0及更高版本：转换为DELTA（Databricks上的Delta Lake）

• Databricks Runtime 6.x及更低版本：转换为Delta（Databricks上的Delta Lake）

将Delta表转换为Parquet表

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

1. 如果执行了可以更改数据文件的Delta Lake操作（例如delete或merge），请运行vacuum并将保留期限设为0小时，从而删除表的最新版本中未包含的所有数据文件。

2. 删除目录中的_delta_log目录。

将Delta表还原到较早的状态

您可以使用以下RESTORE命令将Delta表还原到其早期状态。Delta表在内部维护该表的历史版本，以使其能够还原到较早的状态。RESTORE命令支持与早期状态相对应的版本或创建早期状态的时间戳。

SQL

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

Python

%pyspark
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

%spark
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

有关语法的详细信息，请参见RESTORE（Databricks上的Delta Lake）。

表访问控制

您必须MODIFY对要还原的表具有权限

克隆 Delta 表

您可以使用以下clone命令以特定版本创建现有Delta表的副本。克隆可以是深层或浅层。

• 深层克隆是指除了现有表的元数据外，还会将源表数据复制到克隆目标的克隆。 此外，它还会克隆流元数据，使写入 Delta 表的流可在源表上停止，并在克隆的目标位置（即停止位置）继续进行克隆。

• 浅表克隆不会将数据文件复制到克隆目标。 表元数据等效于源。 创建这些克隆的成本较低。

对深层克隆或浅层克隆所做的任何更改都只会影响克隆本身，而不会影响源表。

克隆的元数据包括：架构，分区信息，不变量，可为Null性。对于深层克隆，还将克隆流和COPY INTO（Databricks上的Delta Lake）元数据。未克隆的元数据是表描述和用户定义的提交元数据。

SQL

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

Python

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

Scala

%spark
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

有关语法的详细信息，请参见CLONE（Databricks上的Delta Lake）

权限

您必须CLONEDatabricks表访问控制和您的云提供的所需的权限。

表访问控制

深层和浅层克隆都需要具有以下权限：

• 源表上的SELECT权限

• 如果要CLONE用于创建新表，请对创建表的数据库具有CREATE权限。

• 如果要CLONE用来替换表，则必须具有该表的MODIFY权限。

云权限

如果创建了深度克隆，则任何读取该深度克隆的用户都必须具有对该克隆目录的读取权限。要更改克隆，用户必须具有对克隆目录的写入权限。

如果创建了浅表克隆，则读取浅表克隆的任何用户都需要权限才能读取原始表中的文件，因为数据文件保留在源表中，并且包含浅表克隆以及该表的目录。若要更改克隆，用户需要对克隆目录具有写入权限。

克隆用例

• 数据存档：数据保存的时间可能会比按时间查看或灾难恢复的时间更长。在这些情况下，您可以创建一个深层克隆，保留表的某个时间点的状态以供存档。还可以通过增量存档保留源表的持续更新状态，以进行灾难恢复。

  SQL

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

• 机器学习流重现：在进行机器学习时，你可能希望将已训练 ML 模型的表的特定版本进行存档。可以使用此存档数据集测试将来的模型。

  SQL

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

• 在生产表上进行短期实验：为了在不损坏表的情况下测试生产表中的工作流，可以轻松创建浅表克隆。这样，就可在包含所有生产数据的克隆表上运行任意工作流，而不会影响任何生产工作负载。

  SQL

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

• 数据共享：单个组织内的其他业务部门可能希望访问上述的数据，但可能不需要最新更新。可以为不同的业务部门提供具有不同权限的克隆，而不是直接授予对源表的访问权限。克隆的性能比简单视图的性能更高。

  SQL

  %sql
  -- 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`;