通用表

通用表是非 Iceberg 表。表可以是多种格式，包括 Delta、CSV 等。借助此框架，你可以：

• 在命名空间下创建通用表
• 加载通用表
• 删除通用表
• 列出某个命名空间下的所有通用表

❗重要提示

通用表目前处于测试阶段，请谨慎使用，如遇到问题请及时反馈。

什么是通用表？

通用表是一种定义了以下字段的实体：

• name（必填）：表在命名空间内的唯一标识符

• format（必填）：通用表的格式，例如 "delta"、"csv"

• base-location（可选）：以 URI 格式表示的表基础位置。例如：s3:///path/to/table

  • 表基础位置是指包含该表所有文件的位置
  • 如果一个表包含多个不相交的位置（即包含位于所配置基础位置之外的文件），则不符合 Polaris 当前对通用表的支持要求。
  • 如果未提供位置，则由客户端或用户负责管理该位置。

• properties（可选）：创建时传入的通用表属性。

  • 目前尚未定义任何保留的属性键。
  • 属性的定义和解释由客户端或引擎实现负责。

• doc（可选）：表的注释或描述

通用表 API 与 Iceberg 表 API 对比

Polaris 提供了一套与 Iceberg API 不同的通用表 API。下表展示了两套 API 的对比：

请注意，通用表与 Iceberg 表共享同一命名空间，表名在同一命名空间下必须唯一。

使用通用表

目前有两种方式可以使用 Polaris 通用表：

1. 使用 curl 等工具，通过 REST API 调用直接与 Polaris 通信。详见后文说明。
2. 如果你使用 Spark，可以使用所提供的 Spark 客户端。详细说明请参阅 Polaris Spark 客户端。

创建通用表

要创建通用表，你需要提供 什么是通用表 中描述的相应字段。

创建通用表的 REST API 为 POST /polaris/v1/{prefix}/namespaces/{namespace}/generic-tables，请求体如下所示：

{
  "name": "<table_name>",
  "format": "<table_format>",
  "base-location": "<table_base_location>",
  "doc": "<comment or description for table>",
  "properties": {
    "<property-key>": "<property-value>"
  }
}

下面是一个使用 curl 在目录 delta_catalog 下的命名空间 delta_ns 中，创建名为 delta_table、格式为 delta 的通用表的示例：

curl -X POST http://localhost:8181/api/catalog/polaris/v1/delta_catalog/namespaces/delta_ns/generic-tables \
  -H "Content-Type: application/json" \
  -d '{
    "name": "delta_table",
    "format": "delta",
    "base-location": "s3://<my-bucket>/path/to/table",
    "doc": "delta table example",
    "properties": {
      "key1": "value1"
    }
  }'

加载通用表

加载通用表的 REST 端点为 GET /polaris/v1/{prefix}/namespaces/{namespace}/generic-tables/{generic-table}。

以下是使用 curl 加载表 delta_table 的示例：

curl -X GET http://localhost:8181/api/catalog/polaris/v1/delta_catalog/namespaces/delta_ns/generic-tables/delta_table

而响应如下所示：

{
  "table": {
    "name": "delta_table",
    "format": "delta",
    "base-location": "s3://<my-bucket>/path/to/table",
    "doc": "delta table example",
    "properties": {
      "key1": "value1"
    }
  }
}

列出通用表

列出给定命名空间下通用表的 REST 端点为 GET /polaris/v1/{prefix}/namespaces/{namespace}/generic-tables/。

以下 curl 命令列出命名空间 delta_namespace 下的所有表：

curl -X GET http://localhost:8181/api/catalog/polaris/v1/delta_catalog/namespaces/delta_ns/generic-tables/

示例响应：

{
  "identifiers": [
    {
      "namespace": ["delta_ns"],
      "name": "delta_table"
    }
  ],
  "next-page-token": null
}

删除通用表

删除通用表的 REST 端点为 DELETE /polaris/v1/{prefix}/namespaces/{namespace}/generic-tables/{generic-table}

以下 curl 调用会删除表 delat_table：

curl -X DELETE http://localhost:8181/api/catalog/polaris/v1/delta_catalog/namespaces/delta_ns/generic-tables/{generic-table}

API 参考

有关完整且最新的 API 规范，请参阅 Catalog API Spec。

当前限制

泛型表支持存在一些已知的限制：

1. 泛型表提供的规范信息有限。例如，没有 Schema 或分区的规范。
2. Polaris 不提供提交协调。协调数据的加载和提交是引擎的职责。目录仅感知上述泛型表字段。
3. Polaris 不提供更新能力。对泛型表的任何更新都必须通过删除并重新创建来完成。
4. 泛型表 API 不支持凭证分发（credential vending）。