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

当 OSS 数据集已按 Lance Directory Namespace 规范组织时，可通过 Directory Namespace 接入 PolarDB。Directory Namespace 基于该规范，在指定的 OSS 根目录下根据表标识解析 Lance 数据集位置，将其挂载为外表并直接查询。整个接入过程分为三步：创建 SERVER、创建外表、查询数据并验证映射。

适用范围

开始操作前，确认满足以下条件：

已满足使用前提与功能限制中的要求。
Lance 数据集已按照 Lance Directory Namespace 规范组织。
已准备 OSS 访问域名、Bucket 路径与读取凭据。
已使用读写节点（RW）主地址连接集群，并选择目标数据库。

步骤一：创建 SERVER

执行以下语句创建 SERVER，通过 EXTRA_SERVER_INFO 配置 OSS 根目录与读取凭据。lance_dir_ns_oss_endpoint 填写 OSS 访问域名或 HTTPS 地址，默认拒绝 http://。

CREATE SERVER example_directory
FOREIGN DATA WRAPPER lance
OPTIONS (EXTRA_SERVER_INFO '{
  "lance_dir_ns_root":"oss://YOUR_OSS_BUCKET/example_warehouse",
  "lance_dir_ns_oss_endpoint":"YOUR_OSS_ENDPOINT",
  "lance_dir_ns_oss_access_key_id":"YOUR_OSS_ACCESS_KEY_ID",
  "lance_dir_ns_oss_access_key_secret":"YOUR_OSS_ACCESS_KEY_SECRET"
}');

参数说明如下：

参数	填写要求	说明
`lance_dir_ns_root`	必填。	Directory Namespace 的根目录，填写规范化的 `oss://<bucket-name>/<warehouse-path>` URI，如 `oss://YOUR_OSS_BUCKET/example_warehouse`。
`lance_dir_ns_oss_endpoint`	必填。	OSS 访问域名或 HTTPS 地址，例如 `oss-YOUR_REGION.aliyuncs.com` 或 `https://oss-YOUR_REGION.aliyuncs.com`。默认拒绝 `http://`。
`lance_dir_ns_oss_access_key_id`	必填。	用于读取 OSS 数据的 AccessKey ID。使用 STS 时填写临时 AccessKey ID。
`lance_dir_ns_oss_access_key_secret`	必填。	与 AccessKey ID 配套的 AccessKey Secret。使用 STS 时填写对应的临时 AccessKey Secret。
`lance_dir_ns_oss_sts_token`	可选，使用 STS 时必填。	与临时 AccessKey ID、AccessKey Secret 同组的 SecurityToken。使用长期 AccessKey 时可省略。

读取凭据支持两种方式：使用长期 AccessKey 时，填写 AccessKey ID 与 AccessKey Secret。使用 STS 临时凭据时，还需通过 lance_dir_ns_oss_sts_token 填写同组的 SecurityToken。

步骤二：创建外表

在目标数据库中，执行以下语句创建外表。连接地址格式为 server://<SERVER名称>/<表名>，本例使用 server://example_directory/example_table，其中 example_directory 为步骤一创建的 SERVER。

本地外表名与 Namespace 中的远端表标识分别填写：

本地外表名位于 CREATE FOREIGN TABLE 之后，本例统一使用 example_table。
远端表标识位于连接地址中，本例同样取 example_table。
表名暂不支持 Namespace 嵌套表示。
省略列定义时，PolarDB 自动读取远端表结构，并确定表定义。需要显式指定列定义时，参考创建与维护 Lance 外表映射。

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

步骤三：查询数据并验证映射

外表创建完成后，执行以下语句查询数据，确认外表映射正确：先通过 SHOW CREATE TABLE 查看表结构，再通过 SELECT 查询数据，返回数据即表示外表映射正确。

SET SESSION use_imci_engine = OFF;

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

后续步骤

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