从外部客户端创建外部 Delta 表

本页介绍如何从外部客户端和系统创建由 Delta Lake 支持的 Unity 目录外部表。

要求

• 为元存储启用外部数据访问。 请参阅在元存储上启用外部数据访问。

• 授予主体配置集成的权限

  • EXTERNAL USE SCHEMA 对包含对象的架构的特权。
  • EXTERNAL USE LOCATION 对包含路径的外部位置的特权。 请参阅 授予主体 Unity 目录特权。
  • CREATE TABLE 对表、 CREATE EXTERNAL TABLE 外部位置、 USE CATALOG 父目录及其 USE SCHEMA 父架构的权限。

  请参阅 授予主体 Unity 目录特权。

可以使用 Apache Spark、Unity 目录 API 或其他外部客户端创建外部表。

使用 Apache Spark 创建 Delta 表

下面是配置 Apache Spark 以创建 Unity 目录外部 Delta 表的设置示例：

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.hadoop.fs.s3.impl": "org.apache.hadoop.fs.s3a.S3AFileSystem",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",

替换以下变量：

• <uc-catalog-name>：Unity Catalog 中包含你的表的目录名称。
• <workspace-url>：Azure Databricks 工作区的 URL。
• <token>：用于配置集成的主体的 OAuth 令牌。

若要使 Apache Spark 和 Delta Lake 与 Unity 目录协同工作，至少需要 Apache Spark 3.5.3 和 Delta Lake 3.2.1。

启动 Apache Spark 时包括以下依赖项：

--packages "org.apache.hadoop:hadoop-aws:3.3.4,\
io.delta:delta-spark_2.12:3.2.1,\
io.unitycatalog:unitycatalog-spark_2.12:0.2.0"

现在可以使用 SQL 创建外部表：

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
USING delta
LOCATION <path>;

使用 API 创建 Delta 表

若要使用 Unity 目录 REST API 创建外部 Delta 表，请执行以下步骤：

步骤 1：向创建表 API 发出 POST 请求

使用以下 API 请求在 Unity 目录中注册表元数据：

curl --location --request POST 'https://<workspace-url>/api/2.0/unity-catalog/tables/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "<table-name>",
  "catalog_name": "<uc-catalog-name>",
  "schema_name": "<schema-name>",
  "table_type": "EXTERNAL",
  "data_source_format": "DELTA",
  "storage_location": "<path>",
  "columns": [
    {
      "name": "id",
      "type_name": "LONG",
      "type_text": "bigint",
      "type_json": "\"long\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 0,
      "nullable": true
    },
    {
      "name": "name",
      "type_name": "STRING",
      "type_text": "string",
      "type_json": "\"string\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 1,
      "nullable": true
    }
  ]
}'

替换以下变量：

• <workspace-url>：Azure Databricks 工作区的 URL
• <token>：进行 API 调用的主体的令牌
• <uc-catalog-name>：Unity 目录中将包含外部表的目录的名称
• <schema-name>：将在其中创建表的目录中的架构的名称
• <table-name>：外部表的名称
• <path>：表数据的完全限定路径

步骤 2：初始化 Delta 表位置

上述 API 调用在 ：[UC] 中注册表，但它不会在存储位置创建 Delta 文件。 若要初始化表位置，请使用 Spark 编写空的 Delta 表：

此步骤中使用的架构必须与 API 请求中提供的列定义完全匹配。

from pyspark.sql.types import StructType, StructField, StringType, LongType

# Define schema matching your API call
schema = StructType([
    StructField("id", LongType(), True),
    StructField("name", StringType(), True)
])

# Create an empty DataFrame and initialize the Delta table
empty_df = spark.createDataFrame([], schema)
empty_df.write \
    .format("delta") \
    .mode("overwrite") \
    .save("<path>")