通过

从 Delta 客户端访问 Databricks 的数据表

本页介绍如何使用 Unity REST API 从外部 Delta 客户端创建、读取和写入 Unity 目录托管表和外部表。 有关受支持的集成的完整列表，请参阅 Unity 目录集成。

小贴士

有关如何使用 Microsoft Fabric 读取Azure Databricks数据的信息，请参阅 使用 Microsoft Fabric 读取 Unity 目录中注册的数据。

使用 Unity REST API 创建、读取和写入

重要

从 Delta 客户端创建和写入 Unity Catalog 管理的表格目前处于测试阶段。 外部客户端支持有限。

Unity REST API 提供外部客户端对注册到 Unity 目录的表的创建、读取和写入访问权限。 使用 工作区 URL 作为端点配置访问权限。 下表类型是可访问的：

表类型 阅读 写入 创建
托管增量 是的 是* 是*
外部变动 是的 是的 是的

* 支持包含 目录提交的托管 Delta 表。

要求

Azure Databricks 支持通过 Unity REST API 访问 Unity Catalog 中的表。 您必须在工作区启用 Unity Catalog 才能使用这些端点。

还必须完成以下配置步骤，以使用 Unity REST API 配置对 Delta 客户端表的访问：

局限性

  • 目前不支持通过 IcebergCompatV3 外部访问 UniForm 表。 在外部写入 UniForm 表后，必须在 Databricks 中运行 MSCK REPAIR TABLE 以生成 Iceberg 元数据。
  • 模式更改（例如ALTER TABLE）、表属性更新和表功能更改当前不支持在托管表上由外部客户端进行。
  • 外部客户端无法对托管 Delta 表执行表维护操作，例如 OPTIMIZE， VACUUM和 ANALYZE。
  • 外部客户端无法创建 浅表克隆。
  • 外部客户端无法创建包含生成的列、默认列或约束列的表。
  • 创建外部表时，Azure Databricks建议使用 Apache Spark 来确保列定义的格式与 Apache Spark 兼容。 API 不会验证列规范的正确性。 如果规范与 Apache Spark 不兼容，则 Databricks Runtime 可能无法读取表。

使用 PAT 身份验证使用 Apache Spark 访问 Delta 表

要使用 PAT 身份验证，通过 Apache Spark 读取或写入 Unity Catalog 托管的 Delta 表和外部 Delta 表，需要以下配置：

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

请替换以下变量：

  • <uc-catalog-name>：Unity Catalog 中包含你的表的目录名称。
  • <token>：用于配置集成的主体的个人访问令牌（PAT）。
  • <workspace-url>：Azure Databricks workspace URL，包括工作区 ID。 例如，adb-1234567890123456.12.azuredatabricks.net。

注释

在上次更新此页面时，上面显示的包版本是最新的。 较新版本可能可用。 验证包版本是否与 Spark 版本兼容。

有关为云对象存储配置 Apache Spark 的其他详细信息，请参阅 Unity 目录 OSS 文档。

重要

为了读取、写入或创建启用了目录提交的表，需要 Databricks Runtime 16.4 及更高版本。 若要在现有表上启用或禁用目录提交，需要 Databricks Runtime 18.0 及更高版本。

若要使用 目录提交创建托管 Delta 表，请使用以下 SQL：

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported') USING delta;

若要创建外部 Delta 表，请使用以下 SQL：

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

使用 OAuth 身份验证通过 Apache Spark 访问 Delta 表

Azure Databricks还支持 OAuth 计算机到计算机（M2M）身份验证。 OAuth 会自动处理 Unity 目录身份验证的令牌和凭据续订。

外部 Spark 客户端的 OAuth 身份验证需要：

  • Unity Catalog Spark 客户端版本 0.4.1 或更高版本（io.unitycatalog:unitycatalog-spark）
  • Apache Spark 4.0 或更高版本
  • Delta Spark 4.2.0 或更高版本
  • 具有适当权限的 OAuth M2M 服务主体。 请参阅 使用 OAuth 授权服务主体访问 Azure Databricks。

若要使用 OAuth 身份验证通过 Apache Spark 创建、读取或写入 Unity 目录托管表和外部 Delta 表，需要以下配置：

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.auth.type": "oauth",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.uri": "<oauth-token-endpoint>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientId": "<oauth-client-id>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientSecret": "<oauth-client-secret>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

请替换以下变量：

  • <workspace-url>：Azure Databricks workspace URL，包括工作区 ID。 例如，adb-1234567890123456.12.azuredatabricks.net。

注释

在上次更新此页面时，上面显示的包版本是最新的。 较新版本可能可用。 验证包版本是否与 Spark 版本兼容。

使用 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 Catalog 中的名称
  • <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>")

注释

为外部客户端创建表 API 具有以下限制：

  • 仅支持外部 Delta 表（"table_type": "EXTERNAL" 和 "data_source_format": "DELTA"）。
  • 仅允许以下字段：
    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties
  • 不支持列掩码。
  • Last updated on