创建与维护 Lance 外表映射 - 云原生数据库 PolarDB

使用PolarDB查询远端 Lance 数据集前，需要为其创建外表映射。映射不复制整表数据，也不修改远端数据。本文介绍如何创建、查看、维护和删除外表映射。

适用范围

操作前，确保满足以下条件：

已满足使用前提与功能限制中的要求。
已为远端数据源创建 SERVER。
已使用读写节点（RW）主地址连接集群，并选择目标数据库。
操作账号具备相应的建表、删除表权限。

创建和查看外表映射

以下示例使用的 example_* 均为占位名称，本地外表名可与远端表名不同。创建方式有两种，按需选择：

需要映射全部列、直接按远端表结构生成本地列时，使用方式一：自动发现列，即省略列定义的默认方式。
只需映射部分列、调整列顺序或指定本地类型时，使用方式二：显式指定列。

方式一：自动发现列

省略列定义时，PolarDB 自动读取远端表结构并创建本地列。

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

方式二：显式指定列

可只映射需要的列并调整列顺序。列名须与远端列名精确匹配，类型须无损兼容，可空性须一致。

CREATE FOREIGN TABLE example_table (
  example_id BIGINT NOT NULL,
  example_text TEXT NOT NULL
) ENGINE=LANCE CONNECTION='server://example_server/example_table.lance';

示例中的 example_id 和 example_text 在远端均为 NOT NULL，因此两列均声明为 NOT NULL。

查看映射

映射创建完成后，执行以下语句查看外表定义，确认生成的列名与类型：

SHOW CREATE TABLE example_table;

类型与读取规则

下表列出 Lance 顶层字段的类型映射和读取要求。自动映射为省略列定义时生成的本地类型，显式声明仅支持表中列出的本地类型，不符合映射要求时建表报错。表中 p、s 分别指 decimal 源类型的 precision 和 scale，p' 指目标类型的 precision。

Lance 类型	自动映射	显式声明允许的本地类型	读取规则与限制
bool	TINYINT(1)	TINYINT、SMALLINT、INT、BIGINT；均可带 UNSIGNED	false 读取为 0，true 读取为 1。
int8	TINYINT	TINYINT、SMALLINT、INT、BIGINT	覆盖完整值域的无损映射。
int16	SMALLINT	SMALLINT、INT、BIGINT	覆盖完整值域的无损映射。
int32	INT	INT、BIGINT	覆盖完整值域的无损映射。
int64	BIGINT	BIGINT	覆盖完整值域的无损映射。
uint8	TINYINT UNSIGNED	TINYINT UNSIGNED、SMALLINT UNSIGNED、INT UNSIGNED、BIGINT UNSIGNED；或 SMALLINT、INT、BIGINT	覆盖完整值域的无损映射。
uint16	SMALLINT UNSIGNED	SMALLINT UNSIGNED、INT UNSIGNED、BIGINT UNSIGNED；或 INT、BIGINT	覆盖完整值域的无损映射。
uint32	INT UNSIGNED	INT UNSIGNED、BIGINT UNSIGNED；或 BIGINT	覆盖完整值域的无损映射。
uint64	BIGINT UNSIGNED	BIGINT UNSIGNED	覆盖完整值域的无损映射。
halffloat（16 位）	FLOAT	FLOAT、DOUBLE	16 位半精度浮点可无损扩宽。目标类型不能带 UNSIGNED 或固定小数位声明。
float（32 位）	FLOAT	FLOAT、DOUBLE	32 位单精度浮点可无损扩宽为 DOUBLE。目标类型不能带 UNSIGNED 或固定小数位声明。
double（64 位）	DOUBLE	DOUBLE	目标类型不能带 UNSIGNED 或固定小数位声明。
decimal:128:p:s	DECIMAL(p,s)	DECIMAL(p',s)；p'≥p 且 p'≤65	目标类型的 scale s 必须与源类型一致，只允许增加 precision。
string	LONGTEXT	CHAR(n)、VARCHAR(n)、TINYTEXT、TEXT、MEDIUMTEXT、LONGTEXT	UTF-8 文本。支持并默认使用 `utf8mb4` 字符集和 `utf8mb4_0900_bin` 排序规则，可省略显式声明。
large_string	LONGTEXT	CHAR(n)、VARCHAR(n)、TINYTEXT、TEXT、MEDIUMTEXT、LONGTEXT	UTF-8 文本。支持并默认使用 `utf8mb4` 字符集和 `utf8mb4_0900_bin` 排序规则，可省略显式声明。
binary	LONGBLOB	BINARY(n)、VARBINARY(n)、TINYBLOB、BLOB、MEDIUMBLOB、LONGBLOB	原始字节。支持并默认使用 `binary` 字符集和 `binary` 排序规则。
large_binary	LONGBLOB	BINARY(n)、VARBINARY(n)、TINYBLOB、BLOB、MEDIUMBLOB、LONGBLOB	原始字节。支持并默认使用 `binary` 字符集和 `binary` 排序规则。
fixed_size_binary:N	LONGBLOB	BINARY(n)、VARBINARY(n)、TINYBLOB、BLOB、MEDIUMBLOB、LONGBLOB	原始字节。支持并默认使用 `binary` 字符集和 `binary` 排序规则。
date32:day	DATE	DATE	日期须在 1000-01-01～9999-12-31 范围内，越界报错。
timestamp:s:tz	DATETIME(6)	DATETIME(6)	秒精度，微秒部分补 0。时区仅允许无时区或 UTC。日期年份须在 1000～9999 范围内。
timestamp:ms:tz	DATETIME(6)	DATETIME(6)	毫秒精度，毫秒部分精确换算为微秒。时区仅允许无时区或 UTC。日期年份须在 1000～9999 范围内。
timestamp:us:tz	DATETIME(6)	DATETIME(6)	微秒精度，保留源微秒部分。时区仅允许无时区或 UTC。日期年份须在 1000～9999 范围内。
timestamp:ns:tz	DATETIME(6)	DATETIME(6)	纳秒原始值必须能被 1000 整除，才能精确换算为微秒，否则读取报错。时区仅允许无时区或 UTC。日期年份须在 1000～9999 范围内。
list	JSON	JSON	JSON 数组。
list.struct	JSON	JSON	JSON 对象数组。
large_list	JSON	JSON	JSON 数组。
large_list.struct	JSON	JSON	JSON 对象数组。
map	JSON	JSON	STRING 键输出 JSON 对象，其他受支持键输出 `{"key":...,"value":...}` 对象组成的数组。
struct	JSON	JSON	JSON 对象。
fixed_size_list:float:N	VECTOR(N)	VECTOR(N)；维度必须完全一致	1≤N≤16383。元素必须为 float（32 位），不能含 NULL、NaN 或无穷值。其他元素类型的 fixed_size_list 不支持，也不能映射为 JSON 或 BLOB。

补充读取规则

建表阶段报错：显式声明的本地类型不符合上表映射要求；二进制列指定 binary 字符集和 binary 排序规则之外的字符集或排序规则。
读取阶段报错：建表成功后，读取仍会检查实际值，越界、NaN 或无穷值、精度损失、容量超限或转换截断时，查询报错。字符串列读取时按目标类型校验容量，超出限制时报错。启用兼容读取后，现有映射列与远端结构不兼容时查询报错（详见远端表结构变化后维护映射）。
字符集自动调整：字符串列指定其他合法的非二进制字符集或排序规则时，建表会自动调整为 utf8mb4 / utf8mb4_0900_bin 并给出警告，可通过 SHOW WARNINGS 和 SHOW CREATE TABLE 查看。
时间戳：读取结果不受会话 time_zone 影响。
复杂类型：嵌套字段须递归满足 JSON 类型支持要求，不支持嵌套 fixed_size_list；嵌套 timestamp 仅支持无时区。二进制底层字段转换为大写十六进制字符串，日期和时间戳字段转换为 JSON 字符串。

删除外表映射

停止依赖该映射的业务访问后，执行以下语句删除外表映射。该操作不会删除远端数据集、快照或文件。

DROP FOREIGN TABLE IF EXISTS example_table;

远端数据更新

远端仅追加数据且表结构未变化时，后续查询可以读取新版本，无需重建外表映射。正在执行的 SQL 继续读取开始时确定的数据版本。

远端表结构变化后维护映射

本地列定义不会随远端表结构自动变化。按变化类型选择处理方式：

远端表路径变化：数据集迁移或路径更名后，需重新创建外表映射，并将连接路径更新为当前的数据集路径。
远端表结构变化：默认会校验完整的远端结构，未映射列的变化也会触发检查失败，通常需要按以下两种方式之一处理：
- 兼容读取：将 lance_allow_compatible_schema_evolution 设置为 ON 可启用兼容读取。若现有映射列的名称、类型和可空性与远端兼容，查询成功，反之查询报错。兼容读取会产生警告，且不会自动增加本地列或更新结构绑定，适用于暂不需要新增列和更新结构绑定的场景。
- 重建映射：需要使用新增列或更新结构绑定时，删除并重新创建映射，按远端当前结构重新生成完整列映射。

重建映射前，注意以下约束：

重要

当前不支持通过 ALTER TABLE 更新结构绑定。从删除旧映射到新映射创建成功期间，该表名不可用于查询，请先停止依赖该映射的业务访问，并保存原表定义。

核对下游 SQL、权限和新结构后，执行以下语句删除并重建映射。示例按远端当前结构重新生成完整列映射，连接路径请填写远端当前的命名空间和表名：

DROP FOREIGN TABLE IF EXISTS example_table;

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

SHOW CREATE TABLE example_table;

重建成功后，可通过相同表名访问新映射。可通过 SHOW CREATE TABLE 查看重建后的表定义，若列结构变化影响原有 SQL，需同步调整。