使用前提与功能限制 - 云原生数据库 PolarDB

PolarDB 湖库一体支持通过 Lance 外表只读访问 Lance 格式数据集。使用前，请先确认集群版本、功能开通、账号权限与网络环境满足使用范围，并了解功能限制中的支持范围。

说明

本功能目前处于灰度阶段，若您有相关需求，请提交工单申请开通。

适用范围

适用版本与功能开通

集群为MySQL 8.0.2，内核小版本为8.0.2.2.39及以上，且非多主集群（Limitless）集群。

功能参数配置

开启 loose_polar_enable_lance 后可新建 Lance 外表。下表所列参数为内核默认值，实际配置以集群为准。表中带 loose_ 前缀的参数名用于配置，SQL 语句中需使用去掉该前缀的参数名。对于同时支持 GLOBAL 和 SESSION 级别的参数，修改 GLOBAL 值不会改变已有连接的 SESSION 值，新建连接将继承修改后的值。

功能开关

参数	级别	默认值	说明
`loose_polar_enable_lance`	GLOBAL	OFF	控制新建 Lance 外表，关闭后已有 Lance 外表仍可读取。

功能配置

参数	级别	默认值	说明
`loose_lance_allow_reads_on_rw`	GLOBAL	ON	是否允许读写节点（RW）读取 Lance 外表。
`loose_lance_allow_compatible_schema_evolution`	GLOBAL、SESSION	OFF	远端结构变化后，是否允许在现有本地列可映射时继续读取。

账号权限要求

权限要求

管理 SERVER 需要具有 SERVERS_ADMIN 权限。高权限账号默认具有该权限，并且可以向普通账号授予该权限。
创建和查询外表还需要具备目标数据库的建表和查询权限。

权限不足的处理

缺少权限时，系统提示以下错误：

Access denied; you need (at least one of) the SERVERS_ADMIN OR SUPER privilege(s) for this operation

按以下流程确认权限并处理：

请先执行以下命令，查看当前用户是否具有 SERVERS_ADMIN 权限，执行前将 用户名 替换为实际的账号名。
```
SHOW GRANTS FOR 用户名;
```
如果您当前没有SERVERS_ADMIN权限，请提交工单联系我们。

网络与对象存储要求

查询节点需能访问 OSS Endpoint，并具备 OSS 文件的读取权限。
使用 REST Namespace 时，查询节点需能访问 Namespace Endpoint，并具备相应权限。

功能限制

支持的表与文件格式

支持 Lance 数据文件格式 legacy (0.1)、2.0、2.1 和 2.2。支持的 Lance 类型要求以外表映射文档中的类型与读取规则为准。远端数据、索引和历史版本由上游按查询需求维护。

支持的 SQL 操作范围

Lance 外表为只读表，以下操作均不会修改或删除远端数据。

操作	用途
`SELECT`	过滤、检索、投影、聚合、排序、窗口函数及关联查询。具体执行方式参见查询数据与分析加速文档；各类检索在不同执行模式下的支持情况见查询能力执行限制。
`CREATE FOREIGN TABLE`、`DROP FOREIGN TABLE`	创建、删除本地外表映射，不修改远端数据。
`CREATE/ALTER/DROP SERVER`	管理数据源连接（SERVER）。
`LOCK TABLES ... READ`	在行式执行时可使用，添加的是本地读锁，不锁定远端数据版本。

查询能力执行限制

查询能力	行式执行	单节点 IMCI	MPP 并行执行
查询与分析加速	支持	支持	支持
向量检索	支持精确 KNN 检索	支持精确 KNN 检索。向量索引可用时支持加速检索	支持精确 KNN 检索
全文检索	单列自然语言模式；全文索引可用时，支持加速检索	单列自然语言模式。全文索引可用时，支持加速检索	不支持
向量与全文混合检索	不支持	向量索引可用时，支持向量相似度与全文相关性的加权融合排序	不支持

三类检索的具体写法及限制，分别参见对应的向量检索、全文检索和向量与全文混合检索文档。

数据一致性与结构限制

每条 SQL 首次访问外表时重新打开数据集的最新版本，不会将外表绑定到建表时的数据版本。
同一条 SQL 对同一 Lance 外表的多次引用使用固定的数据集地址、版本和表结构。不提供多语句事务级或跨外表的统一快照。
远端表结构变化后，默认拒绝继续读取，需删除并重建本地映射，相关操作参见远端表结构变化后维护映射。在 SQL 语句中开启 lance_allow_compatible_schema_evolution 后，仅允许现有本地列仍可映射的变化，不自动增加本地列，也不更新原有绑定。
查询期间，上游需保留该查询使用的 manifest、数据文件和索引。上游清理所需历史文件、原地替换数据集，或 MPP 节点解析到不同位置，都可能导致查询失败。