通过 REST Namespace 接入 - 云原生数据库 PolarDB

REST Namespace 是用于解析 Lance 数据集位置的 REST 服务，适合借助 Catalog 统一管理 Lance 表的接入场景。Lance 数据集存储于对象存储 OSS，接入流程为：创建指向 REST Namespace 服务的 SERVER，基于该 SERVER 创建映射远端 Lance 表的外表，最后执行查询验证接入结果。

适用范围

已满足使用前提与功能限制中的要求。
REST Namespace 服务能被查询节点访问，并能返回查询节点可访问的对象存储 OSS 数据位置和读取配置。
已准备 REST Namespace 服务地址、Namespace 和认证信息。
已使用读写节点（RW）主地址连接集群，并选择目标数据库。

步骤一：创建 SERVER

以下示例以 Bearer Token 认证为例，将 example_*、YOUR_* 替换为实际值后，执行以下语句创建 SERVER。参数说明见下方各表，认证字段按所选认证方式填写：

若 REST Namespace 服务要求 API Key 认证，将 lance_rest_ns_auth_type 填写为 api_key，并以 lance_rest_ns_api_key 字段替换示例中的 lance_rest_ns_token 字段。
若服务无需认证，将 lance_rest_ns_auth_type 填写为 none，并省略 lance_rest_ns_token 字段。

CREATE SERVER example_rest
FOREIGN DATA WRAPPER lance
OPTIONS (EXTRA_SERVER_INFO '{
  "lance_rest_ns_auth_type":"token",
  "lance_rest_ns_uri":"https://YOUR_REST_HOST",
  "lance_rest_ns_namespace":"example_catalog$example_schema",
  "lance_rest_ns_token":"YOUR_BEARER_TOKEN"
}');

基本连接参数

参数	填写要求	说明
`lance_rest_ns_uri`	必填	REST Namespace 服务的基础地址，须包含协议，默认要求 HTTPS。示例为 `https://YOUR_REST_HOST`。
`lance_rest_ns_namespace`	必填	默认 Namespace，不得为空。远端表标识仅填写表名时使用。多级 Namespace 按 `lance_rest_ns_delimiter` 分隔。
`lance_rest_ns_auth_type`	必填	认证方式，按所选方式填写对应的认证参数。取值范围： `none`（无需认证） `token`（Bearer Token） `api_key`（API Key）。
`lance_rest_ns_delimiter`	可选	Namespace 层级与表名的分隔符，默认为 `$`。显式填写时不得为空。
`lance_rest_ns_headers_json`	可选	额外请求头，填写字符串形式的 JSON 对象，键和值均为字符串。省略时不添加额外请求头。`Authorization`、`x-api-key`、`Host`、`Content-Length` 为保留请求头（不区分大小写），不允许自定义。请求头名称不得为空或包含空格、控制字符、冒号，值不得包含 NUL、回车、换行或制表符。

认证参数

参数	填写要求	说明
`lance_rest_ns_token`	`lance_rest_ns_auth_type=token` 时必填，其他方式省略	非空 Bearer Token，发送为 `Authorization: Bearer <token>`。
`lance_rest_ns_api_key`	`lance_rest_ns_auth_type=api_key` 时必填，其他方式省略	非空 API Key，作为 `x-api-key` 请求头的值发送。

步骤二：创建外表

在目标数据库执行建表语句。连接地址格式为 server://<SERVER名称>/<远端表标识>，分隔符由 SERVER 参数 lance_rest_ns_delimiter 指定，以下示例假定分隔符为 $。远端表标识支持以下两种写法，任选其一。切换写法时，请先删除已创建的本地外表示例，再执行另一条建表语句。

使用默认 Namespace

当 <远端表标识> 不包含分隔符时，整个标识作为表名，Namespace 使用 SERVER 中 lance_rest_ns_namespace 的值，并按同一分隔符拆分为 Namespace 层级。本例中，默认 Namespace 为 example_catalog$example_schema，远端表名为 example_table，本地外表名为 example_table。

CREATE FOREIGN TABLE example_table
FROM CONNECTION 'server://example_rest/example_table';

显式指定 Namespace

当 <远端表标识> 包含分隔符时，最后一个分隔符之后的部分作为表名，之前的部分作为完整 Namespace，并按同一分隔符拆分层级，不再使用 lance_rest_ns_namespace 指定的默认 Namespace。以下示例显式指定 Namespace 为 example_catalog$example_schema，远端表名为 example_table。

CREATE FOREIGN TABLE example_table
FROM CONNECTION 'server://example_rest/example_catalog$example_schema$example_table';

以上两种写法均可省略列定义，此时 PolarDB 自动读取远端表结构，并确定本地外表的列定义。需要显式指定列定义时，参考创建与维护 Lance 外表映射。

步骤三：查询数据

外表创建完成后，通过 SHOW CREATE TABLE 查看表结构，并执行查询，确认连接配置与表标识正确。

SET SESSION use_imci_engine = OFF;

SHOW CREATE TABLE example_table;
SELECT * FROM example_table LIMIT 10;

后续步骤

上游数据更新导致表结构变化时，按创建与维护 Lance 外表映射中的外表映射维护章节处理。