通过 OSS 元数据文件接入（Direct OSS） - 云原生数据库 PolarDB

Direct OSS 根据 SERVER 中配置的 Bucket、warehouse 目录前缀和外表的数据集路径，定位 OSS 上的 Lance 数据集。该方式适合已知数据集位置、且无需 Namespace 服务的接入场景。本文按创建 SERVER、创建外表、验证并查询数据三个步骤，介绍如何在 PolarDB 中读取该数据集。

适用范围

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

已确认符合使用前提与功能限制。
已准备 Lance 数据集所在的 OSS 访问域名（Endpoint）、Bucket、数据集路径，以及下列任一种读取凭据：
- 长期 AccessKey：包含 AccessKey ID 与 AccessKey Secret。
- STS 临时凭据：包含临时 AccessKey ID、AccessKey Secret 与 SecurityToken。STS 凭据不会自动续期，需在到期前手动更新。
已使用读写节点（RW）主地址连接集群，并选择目标数据库。

步骤一：创建 SERVER

将 example_* 与 YOUR_* 替换为实际值，执行以下语句创建 SERVER。参数说明如下表所示。

重要

Direct OSS 不会自动续期 STS 凭据。使用 STS 临时凭据时，需在到期前通过 ALTER SERVER 更新同一组临时 AccessKey ID、AccessKey Secret 和 SecurityToken，并保留其余 SERVER 配置。

CREATE SERVER example_oss
FOREIGN DATA WRAPPER lance
OPTIONS (EXTRA_SERVER_INFO '{
  "lance_direct_oss_endpoint":"YOUR_OSS_ENDPOINT",
  "lance_direct_oss_bucket":"YOUR_OSS_BUCKET",
  "lance_direct_oss_warehouse_prefix":"example_warehouse",
  "lance_direct_oss_access_key_id":"YOUR_OSS_ACCESS_KEY_ID",
  "lance_direct_oss_access_key_secret":"YOUR_OSS_ACCESS_KEY_SECRET"
}');

参数	填写要求	说明
`lance_direct_oss_endpoint`	必填	OSS 访问域名或 HTTPS 地址，例如 `oss-YOUR_REGION.aliyuncs.com` 或 `https://oss-YOUR_REGION.aliyuncs.com`。默认拒绝 `http://`。
`lance_direct_oss_bucket`	必填	存放 Lance 表的 Bucket 名称，例如 `example-bucket`。
`lance_direct_oss_warehouse_prefix`	可选	Bucket 内的 warehouse 目录前缀，表路径追加在此前缀后。例如 `example_warehouse`。省略或留空时，从 Bucket 根目录解析数据集路径。
`lance_direct_oss_access_key_id`	必填	用于访问 OSS 的 AccessKey ID。使用 STS 时填写临时 AccessKey ID。
`lance_direct_oss_access_key_secret`	必填	与 AccessKey ID 配套的 AccessKey Secret。使用 STS 时填写对应的临时 AccessKey Secret。
`lance_direct_oss_sts_token`	可选，使用 STS 时必填	与临时 AccessKey ID、AccessKey Secret 同组的 SecurityToken。使用长期 AccessKey 时可省略。

上述示例使用长期 AccessKey。使用 STS 临时凭据时，需在同一 OPTIONS 中追加 lance_direct_oss_sts_token 参数。语句执行成功且无报错，即表示 SERVER 创建完成。

步骤二：创建外表

外表连接地址的格式为 server://<SERVER名称>/<数据集路径>，其中数据集路径追加在 SERVER 的 lance_direct_oss_warehouse_prefix 之后。本例中，连接地址与对应的 OSS 地址如下：

连接地址	对应的 OSS 地址
`server://example_oss/example_table.lance`	`oss://YOUR_OSS_BUCKET/example_warehouse/example_table.lance`

在目标数据库中，执行以下语句创建外表。省略列定义时，PolarDB 自动读取远端表结构，生成外表定义。需要显式指定列定义时，参考创建与维护 Lance 外表映射。

CREATE FOREIGN TABLE example_table
FROM CONNECTION 'server://example_oss/example_table.lance';

语句执行成功且无报错，即表示外表创建完成。

步骤三：验证并查询数据

外表创建完成后，在目标数据库中通过 SHOW CREATE TABLE 查看表结构并执行查询，确认数据集路径与 OSS 地址配置正确。

SET SESSION use_imci_engine = OFF;

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

SHOW CREATE TABLE 回显与远端 Lance 数据集一致的表结构，且 SELECT 返回数据行，说明验证通过。

后续步骤

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