From c424d2be367bc0d4f0424fa9e9c48bd9a244f2e1 Mon Sep 17 00:00:00 2001 From: shaoyue Date: Fri, 18 Sep 2026 22:45:22 +0800 Subject: [PATCH] Use English documentation by default and preserve Chinese translations --- ROADMAP-cn.md | 219 +++++++++++++++++++++ ROADMAP.md | 286 ++++++++++++++-------------- Readme.md | 2 +- docs/milvus-2.6-api-inventory-cn.md | 84 ++++++++ docs/milvus-2.6-api-inventory.md | 134 ++++++------- 5 files changed, 516 insertions(+), 209 deletions(-) create mode 100644 ROADMAP-cn.md create mode 100644 docs/milvus-2.6-api-inventory-cn.md diff --git a/ROADMAP-cn.md b/ROADMAP-cn.md new file mode 100644 index 0000000..cca7d66 --- /dev/null +++ b/ROADMAP-cn.md @@ -0,0 +1,219 @@ +# Milvus 2.6 全功能支持 Roadmap + +[English](ROADMAP.md) + +更新日期：2026-09-18。当前实现基线：`077de63`（PR #2）。 + +目标：通过 MySQL 和 PostgreSQL 两种协议，完整提供 **Milvus 2.6.23 已实现、面向用户的数据与管理能力**。两个协议使用同一个能力模型、执行计划和权限语义；`mysql`、`postgres`、`both` 三种启动模式持续通过 E2E。 + +这是实现计划，文中的新增 SQL、过程名及阶段均为**待实现草案**，不能作为当前支持说明。当前可用语法以 [Readme.md](Readme.md) 为准。 + +## 1. 版本与范围 + +- **完整支持目标固定为 2.6.23**；这是本次核对的官方 2.6 发布基线。后续 2.6 补丁通过独立兼容性 PR 更新目标，不能悄悄扩大支持声明。[发布说明](https://milvus.io/docs/v2.6.x/release_notes.md) +- **2.6.2 保留已有功能回归**，不承诺它拥有后续补丁新增的能力。每项功能记录最低已验证 server/SDK 版本、部署条件和测试证据。 +- 覆盖数据模型、DDL、DML、查询/搜索、索引、函数、导入、权限、资源管理和公开运维 API；每个功能的请求参数、结果类型、状态查询和失败行为都属于范围。 +- GPU、分布式资源组、外部模型服务等能力属于目标，需要专用测试环境；缺少环境时标记“未验证”，不能算完成。 +- JOIN、跨集合事务、外键、通用 SQL 聚合/窗口函数、任意表达式 UPDATE、完整 MySQL/PostgreSQL 系统目录不属于 Milvus 原生能力。代理不以隐式全量拉取、读改写模拟这些语义。 +- Streaming Node、Woodpecker、Storage V2、JSON shredding 等服务端内部实现通过兼容性测试验证；安装、扩缩容、备份/CDC 工具和集群配置有各自运维边界。它们不等同于新增 SQL 运算符。 +- proto 中存在不等于服务端可用：废弃、未实现、内部复制/救援接口逐项列在 [API 盘点](docs/milvus-2.6-api-inventory-cn.md)，附依据和处理方式，不能无声遗漏或算作完成。 + +## 2. 当前基础与缺口 + +| 领域 | 当前已实现 | 距离完整支持的主要缺口 | +| --- | --- | --- | +| 协议 | MySQL text/prepared；PG simple/extended；双端口；TLS 配置 | 中立结果模型、更多类型编码、取消、流式结果、稳定错误映射 | +| SDK | `milvus-sdk-go/v2`、proto 均为 2.3.3 | 升级现代 `milvus/client/v2`，补齐 SDK 缺口和能力门控 | +| Schema | 基础标量、JSON、float32 vector、主键/AutoID | nullable/default、动态字段、ARRAY、其他向量、结构数组、GIS、时间类型、schema 演进 | +| 管理 | DB/collection CRUD 子集、手工分区、load/release/flush | 属性、别名、统计、状态、异步任务、分区键、资源组、compaction、RBAC | +| 数据 | insert、全行 upsert、带过滤 delete | 分区路由、partial upsert、自动 ID 结果、完整 mutation 计数、bulk import | +| 查询 | 投影、基础过滤、count、分页、单条 dense ANN | 全表达式、batch NQ、稀疏/BM25、hybrid、rerank、范围/分组/迭代搜索 | +| 索引 | FLAT/HNSW/IVF_FLAT/AUTOINDEX/INVERTED | 其余索引、参数矩阵、状态/进度、属性变更、JSON/文本/空间索引 | +| 验证 | 2.6.2，实际二进制 × 三种模式；覆盖率门槛 90% | 2.6.23 全能力验证、SDK 对照、类型逐值断言、分布式/GPU/模型测试 | + +依据：[go.mod](go.mod)、[执行层](pkg/conn.go)、[SQL 命令](pkg/commands.go)、[生命周期测试](pkg/integration_test.go)、[E2E](.github/workflows/e2e.yml)。这些基础能力仍需扩充参数和结果断言，不能整体标为“全功能完成”。 + +## 3. 设计约定 + +1. **一份 AST/计划，两种协议。** 将共享执行层当前使用的 MySQL result 类型替换为协议中立的列元数据、值、mutation 结果和结构化错误；协议层只负责绑定与编码。 +2. **结构化解析。** 扩展语法进入明确 AST，逐步替换 lifecycle/index 的正则分派。参数绑定携带类型，不拼接不可信 filter、JSON 或管理参数；复合类型有大小/维度/深度限制。 +3. **SQL 加显式 Milvus 扩展。** 常规 CRUD/DDL 使用 SQL；复杂搜索、异步任务及管理能力使用具名 `CALL milvus_*` 扩展。为每个过程固定参数 schema、结果列、权限、取消和版本要求，禁止提供任意 RPC/管理透传后门。 +4. **忠实保留语义。** 区分 SQL NULL、缺失动态键、JSON null；保留向量精度、距离方向、NQ 分组和排名；不把 ANN group-by 解释成关系聚合，不把异步提交成功解释成任务完成。 +5. **版本和环境共同决定能力。** `SHOW MILVUS CAPABILITIES`（草案）显示 server/SDK 版本、能力、限制、部署前提和验证状态。版本未知时不能猜测支持；必要时采用只读探测及显式配置。 +6. **权限贯穿执行链。** 每个会话有独立上游身份/数据库上下文；跨库、别名、导入、管理过程也必须鉴权。现有单个共享上游账号模式明确标为 service-account 模式，不能声称已有用户级 RBAC。 +7. **受控 SDK 补缺。** 首选固定版本官方 Go SDK；缺失能力封装到窄接口的 gRPC/REST v2 adapter，复用身份、TLS、超时和错误处理。不能因为 SDK 缺失就把 Milvus 能力从范围中删除。 + +## 4. 实施顺序与验收 + +阶段按依赖推进，不承诺未经估算的日期。P0 建立契约后，P1–P3 构成基础数据闭环；P4–P7 补齐高级与管理能力；P8 完成全量验收。P7 的身份设计从 P0 开始，管理功能发布必须受它约束。 + +### P0 — SDK、能力清单与双协议基础 + +- [ ] 升级到固定的现代 Go SDK/proto，逐项迁移 session client、schema、index、mutation 和异步等待行为；保留 2.6.2 已有功能回归。 +- [ ] 建立机器可读 feature registry：`id / operation / parameters / min_server / sdk_or_adapter / deployment / mysql / postgres / tests / status / exclusion_reason`。 +- [ ] 将 API 盘点扩展到参数、schema 枚举、表达式、索引及 SDK 组合操作；每个条目有阶段和实现/测试链接。 +- [ ] 建立协议中立的值/结果/错误模型；定义两端的 SQLSTATE/错误码、参数类型、64 位整数、NULL、二进制和复杂类型编码。 +- [ ] 定义取消与超时、mutation 重试边界、幂等性和任务状态契约；超时不自动重放可能已提交的写操作。 +- [ ] 将 E2E 增加固定 2.6.23 目标，保留 2.6.2 回归；先迁移再增加语法，避免 SDK 升级与全部新特性混成一个 PR。 + +**验收：** 原有测试与三模式 E2E 在两个固定版本上通过；已有 SQL 行为不回退；未知能力有明确错误，不能静默忽略参数。 + +### P1 — 完整数据类型与 Schema + +- [ ] 基础类型边界：整数范围、浮点精度、VARCHAR 长度、JSON、INT64/VARCHAR 主键、AutoID 和 `allow_insert_auto_id` 等适用属性。 +- [ ] nullable/default、字段省略、显式 NULL 与默认值；按 server 对类型/主键/分区键的限制校验，不能对所有类型一律开放默认值。 +- [ ] 动态字段开关、读写、投影、嵌套路径和 schema 描述；支持服务端允许的开启/演进操作。 +- [ ] ARRAY 的元素类型/max_capacity；FloatVector、Float16Vector、BFloat16Vector、Int8Vector、BinaryVector、SparseFloatVector 的构造、绑定与返回。 +- [ ] Array of Structs、其中的向量子字段/多向量列表、嵌套结果与元素级检索所需 schema。不能把内部 `ArrayOfStruct` 枚举直接当用户顶层任意 STRUCT。 +- [ ] GEOMETRY/WKT、TIMESTAMPTZ/时区、相应 NULL 与过滤/索引支持。 +- [ ] 字段描述、analyzer/function output、partition key、clustering key；新增字段及可修改字段属性，保留不允许的 schema 修改错误。 + +**验收：** 每个类型在 MySQL text/prepared 和 PG text/binary 结果中逐值往返；覆盖空数组、稀疏空向量、NULL、越界、坏 WKT、时区/DST、维度错误；Describe 不触发写入。类型/默认值限制以固定版本 schema 与执行结果为准。[类型定义](https://github.com/milvus-io/milvus-proto/blob/v2.6.23/proto/schema.proto) + +### P2 — DB、Collection、Partition 与生命周期 + +- [ ] Database list/describe/create/alter/drop；属性设置/删除和默认值继承；跨库 collection 访问与移动/rename 的适用限制。 +- [ ] Collection has/list/describe/batch describe/statistics/create/rename/drop/truncate；shards、consistency、TTL、mmap、时区等已支持属性与参数。 +- [ ] Alias create/alter/drop/list/describe；变更后失效旧 schema/index 缓存，跨库解析不能串库。 +- [ ] 手工 partition has/list/create/drop/statistics/load/release；partition key、自动分区数、partition-key isolation 和 clustering key。 +- [ ] Load/release 的 replica、resource groups、指定字段、skip dynamic field 等适用选项；load state/progress。 +- [ ] Flush/flush-all、异步状态和等待；明确“数据已提交”“已持久化”“已加载可查”的不同状态。 +- [ ] 需要的 `IF EXISTS / IF NOT EXISTS` 基于真实存在性与并发错误处理，不吞权限和网络错误。 + +**验收：** 对照 SDK 检查所有属性与统计；别名重指向、跨会话/跨库隔离、异步失败、reload、分区加载后可见性、truncate 保留 schema/index 等行为正确。 + +### P3 — DML 与完整过滤/查询 + +- [ ] INSERT/full UPSERT/partial UPSERT：命名列、分区选择、AutoID 语义、返回主键/时间戳/计数；没有上游精确计数时不能伪造。 +- [ ] partial upsert 的字段省略、动态键 merge、JSON 整列替换、ARRAY_APPEND/ARRAY_REMOVE；以原生 Upsert 请求实现，不做代理端隐式读改写。[Upsert 语义](https://milvus.io/docs/v2.6.x/upsert-entities.md) +- [ ] DELETE 按主键/过滤表达式及分区；显式全量删除接口与防误操作语法；不能将当前拒绝裸 DELETE 的行为悄悄改为全量删除。 +- [ ] Get-by-ID、query、count、字段/动态键/嵌套投影、别名和迭代读取；返回字段顺序、空结果元数据与计数语义。 +- [ ] 过滤比较/逻辑/算术、IN、LIKE、NULL、JSON/ARRAY contains/contains_all/contains_any、长度/下标/路径、存在性、文本和 GIS/时间表达式；逐运算符登记版本/类型约束。 +- [ ] 参数化过滤模板、unicode/转义/注入边界；处理缺失键、JSON null、类型不匹配的三值逻辑。 +- [ ] Strong/Bounded/Session/Eventual 及服务端公开的 consistency/时间戳选项；会话级与请求级覆盖、时间戳单位与适用限制。 +- [ ] Query iterator 生命周期、fetch/close/断连清理、背压和有界内存；不通过不断增加 offset 冒充迭代器。 + +**验收：** SDK 差分测试逐字段/计数核对；覆盖过滤真值表、写后读、分区隔离、多个客户端、超过单次窗口的数据遍历；partial upsert 的非事务并发语义写入文档。 + +### P4 — 向量搜索全能力 + +- [ ] 所有向量类型的 single/batch NQ；结果带 query index、rank、PK、distance/score，保留每个 query 的边界。 +- [ ] 搜索字段/分区、topK/offset、索引专用搜索参数、metric、round_decimal、ignore_growing、输出字段及动态字段。 +- [ ] 标准/迭代过滤、range search、search iterator；控制 radius/range_filter 的不同 metric 方向和边界。 +- [ ] Grouping search：group_by_field、group_size、strict_group_size 等固定版本支持项；不是通用 SQL GROUP BY。 +- [ ] 多路 HybridSearch、每路 ANN 请求/过滤/候选数，RRF 和 WeightedRanker、最终 limit/offset 与 score。[融合说明](https://milvus.io/docs/v2.6.x/reranking.md) +- [ ] Array-of-vector/EmbeddingList、结构数组元素搜索、服务端支持的聚合相似度与结果定位；不把多向量字段单独检索当 hybrid 已完成。 +- [ ] 按主键搜索等固定版本公开搜索输入，以及高级检索选项，完成 SDK/请求参数清单后逐项实现；不凭 proto 字段直接开放。 + +**验收：** FLAT 精确 oracle + 固定随机种子；ANN 使用明确 recall 门槛，距离浮点容差、并列排名规则、分组数及 NQ 隔离独立断言。Hybrid 分数/顺序对照官方 SDK，而非只检查非空结果。 + +### P5 — 全文、Analyzer、函数与重排 + +- [ ] 文本字段 analyzer 配置、tokenizer/filter、多语言/多 analyzer（按版本）、TEXT_MATCH、PHRASE_MATCH；RunAnalyzer 和 token 输出选项。 +- [ ] BM25 function/schema、稀疏索引、原始文本搜索、稀疏/稠密混合检索、函数输出字段读写限制。 +- [ ] Collection function 的 create/add/alter/drop/describe；TextEmbedding 的服务端已支持 provider/config，输入输出字段映射和错误处理。 +- [ ] Function rerank：目标版本实际支持的模型、decay、boost 等类型/参数；与 hybrid 的 RRF/weighted 分开登记。 +- [ ] Text highlighter 的来源、字段、标签、片段和结果结构；处理空值、unicode 和动态文本。 +- [ ] MinHash/去重链路：2.6 已支持的预计算签名 + MINHASH_LSH/MHJACCARD；**不把后续版本的服务端 MinHash function 移植承诺到 2.6**。 + +**验收：** 固定语料验证 token、BM25 排序和高亮；模型 adapter 使用契约测试，并在声明支持的真实 provider 上做可重复验证。日志不得泄露 provider 凭据；未跑真实 provider 的组合标为未验证。 + +### P6 — 索引与性能选项 + +- [ ] 建立“字段类型 × index × metric × build/search 参数 × CPU/GPU × 最低版本”清单，不以字符串透传替代支持。 +- [ ] dense：补齐 IVF_SQ8、IVF_PQ、SCANN、HNSW 的量化变体/精排选项、IVF_RABITQ 等目标版本支持项，以及 DISKANN、AISAQ；保留现有索引。 +- [ ] binary/sparse：BIN_FLAT、BIN_IVF_FLAT、MINHASH_LSH、SPARSE_INVERTED_INDEX 与适用算法；旧 SPARSE_WAND 按上游弃用策略兼容/报错。 +- [ ] GPU：GPU_CAGRA、GPU_IVF_FLAT、GPU_IVF_PQ、GPU_BRUTE_FORCE 等目标构建实际注册项；声明硬件/镜像/内存约束。 +- [ ] scalar：INVERTED、BITMAP、STL_SORT、TRIE、AUTOINDEX 等适用类型；JSON path/flat/cast 参数、ARRAY、NGRAM、文本匹配、GEOMETRY RTREE。 +- [ ] Index create/list/describe/drop/alter、statistics/state/progress、异步构建失败；mmap、缓存/预热等公开选项与实际生效边界。 + +**验收：** 从固定版本 index registry/validator 核对枚举；每个合法组合实际建索引、load、search/query、release、修改/删除并校验结果。非法组合明确失败；没有 GPU/磁盘环境的索引不能标完成。参考 [索引与 metric](https://milvus.io/docs/v2.6.x/index-vector-fields.md)（该概览已弃用，最终清单以固定版本实现与各索引文档为准）。 + +### P7 — 导入、权限、资源与运维管理 + +- [ ] Bulk import：原生 import job 创建/list/progress/state、文件格式/存储路径/选项、失败原因和幂等边界；REST v2 能力独立核对，不能只看旧 gRPC Import。 +- [ ] CSV/JSON/Parquet/NumPy 等目标版本实际支持格式逐项测试；数据库、分区、AutoID、nullable、所有支持类型与导入后索引/加载闭环。 +- [ ] User/password/role/member、grant/revoke/list、Privilege V2、privilege group、role description、RBAC backup/restore；定义 SQL 用户与 Milvus principal 的映射。 +- [ ] 管理默认关闭，显式启用且使用最小上游权限；密码更新、权限撤销、会话存活与跨租户隔离均测试。共享 root 后端不能冒充用户级授权。 +- [ ] Resource group create/update/describe/list/drop、node/replica transfer、replica 配置/查询；query/streaming 资源组支持范围按目标部署核对。 +- [ ] Manual/clustering compaction、state/plans、segment/replica/statistics；公开 load balance 管理动作独立权限与审计。 +- [ ] Version/health、公开 metrics、代理请求日志/trace/延迟/错误/在途数；敏感 SQL 参数脱敏，取消和超时可关联到上游。 +- [ ] CDC/replication 公共配置与状态接口先确认支持契约，必要时提供受限管理过程；复制数据流、WAL dump、内部协调接口交给原生工具并记录集成边界。 + +**验收：** 真实启用鉴权的独立 Milvus 验证拒绝与允许；对象存储导入失败/恢复与行值校验；分布式多 QueryNode 验证资源组和副本迁移。所有 mutation 只操作测试创建的资源并完成清理。 + +### P8 — 兼容性与发布验收 + +- [ ] MySQL text/binary/prepared、PG simple/extended/text/binary 的能力矩阵全部通过；NULL、空结果、复杂列元数据一致。 +- [ ] PostgreSQL CancelRequest 和 MySQL 查询取消路径、断连、statement/portal 关闭、超时后连接恢复、优雅退出；资源有界释放。 +- [ ] 真实 `mysql`/`psql` 和 Go/Python/JDBC 常用驱动 smoke；最小元数据兼容集单独文档化，不承诺所有 ORM。 +- [ ] 大 NQ、大批写入、大结果、并发会话、慢客户端、上游重启/连接失败、权限撤销与任务超时；规定吞吐、p95/p99、内存基线后测量代理开销。 +- [ ] 完成 capability registry 的参数与异常分支审计；公开状态、SQL/API 对照、最低版本和测试链接。 + +**验收：** 所有范围内条目均有双协议真实 E2E 证据；没有 P0/P1 缺陷；排除项有上游依据。专用环境未验证项目意味着“部分支持”，不能发布“Milvus 2.6 全功能支持”的声明。 + +## 5. SQL 接口草案 + +以下仅确定方向；实现前在对应 PR 固定语法、类型及错误契约，并增加 parser/protocol 测试。`CALL` 名称不是上游 Milvus SQL 标准。 + +```sql +-- P1/P2：扩展 DDL 与属性；WITH 的键和值按目标能力注册校验 +CREATE TABLE docs ( + id BIGINT PRIMARY KEY, + title VARCHAR(512), + rating DOUBLE DEFAULT 0, + tags ARRAY, + embedding VECTOR(3) +) WITH (enable_dynamic_field=true); +ALTER TABLE docs ADD COLUMN category VARCHAR(64) NULL; +SHOW MILVUS CAPABILITIES; + +-- P3：显式 partial update，不许隐式改成关系型 UPDATE +UPSERT INTO docs (id, title) VALUES (1, 'new title') + WITH (partial_update=true); + +-- P4/P5：复杂请求通过强类型、具名过程；JSON 仅为绑定载体 +CALL milvus_search('docs', '{"anns_field":"embedding","data":[[1,0,0]],"limit":10}'); +CALL milvus_hybrid_search('docs', ''); +CALL milvus_run_analyzer(''); + +-- P7：长任务返回原生 job ID，可独立查询/等待 +CALL milvus_import('docs', ''); +CALL milvus_import_status(''); +CALL milvus_compact('docs', ''); +``` + +MySQL 参数用 `?`，PostgreSQL 用 `$1` 等；对象名不能当普通值参数替换。复杂过程统一参数 schema，但两端分别定义结果列类型。最终语法需要保持现有 `json_vector(...)`、ANN LIKE 与 lifecycle 命令兼容。 + +## 6. CI 与完成定义 + +| 层级 | 计划运行方式 | 必须覆盖 | +| --- | --- | --- | +| Unit / fuzz | 每个 PR | parser、类型转换、参数校验、计划、错误映射；`-race`、`go vet`、actionlint；statement coverage ≥90% | +| Core E2E | 每个 PR / main | 2.6.23 × mysql/postgres/both；2.6.2 原有能力回归；真实二进制和独立 Milvus | +| Feature E2E | 每个特性 PR；全量定时运行 | 每项类型/索引/过滤/搜索参数的正负例；对照官方 SDK；新增功能在不支持版本上明确失败 | +| Distributed / import / RBAC | 对应 PR 必跑；全量定时运行 | 多节点、对象存储、真实认证、权限撤销、异步失败、资源迁移 | +| GPU / provider / load | 专用 runner；对应特性发布前必跑 | 每个声明支持的硬件/模型组合及负载、故障验证 | + +这些扩展 workflow 尚未实施；当前仍是 Readme 中的 2.6.2 测试。每个新阶段交付必须包含：实现、SQL 示例、权限/版本限制、双协议结果契约、单元测试、真实 E2E、review、CI 证据。 + +测试需分别核对数据值、字段类型、NULL/缺失、PK、计数、顺序/距离和状态；不能只检查请求无错误或结果非空。长任务用状态轮询与截止时间，禁止用固定 sleep 作为成功依据。失败上传脱敏日志/版本/配置；测试只清理自身唯一命名资源。 + +“完成比例”按登记的能力及参数合同计算，不使用代码覆盖率或已映射 RPC 数量代替。跳过专用环境的测试、仅 mock 通过、只实现一个协议，均不能记为已验收。 + +## 7. 首批 PR 拆分 + +| 顺序 | 可独立 review 的交付 | 前置 | +| --- | --- | --- | +| 1 | feature registry 初版、固定版本 SDK/API 参数盘点、2.6.23 E2E 基线 | 本 roadmap | +| 2 | 现代 Go SDK/adapter 迁移，保持现有 SQL 合同 | 1 | +| 3 | 协议中立结果/错误类型，绑定/NULL/复杂类型编码基础 | 2 | +| 4 | nullable/default + ARRAY/dynamic field，逐值 E2E | 3 | +| 5 | 稀疏/低精度/二进制向量与对应基础索引 | 3 | +| 6 | collection 属性、别名、schema 演进、分区路由 | 2–4 | +| 7 | partial upsert、完整过滤模板和 consistency | 4、6 | +| 8 | batch/range/iterator/grouping + hybrid 检索 | 5、7 | +| 9 | BM25/analyzer/function/rerank 与高级类型/索引分批交付 | P1/P4 相应基础 | +| 10 | 身份映射与 RBAC 后启用 import/resource/compaction 管理；最终 P8 | P0 身份设计、P2 | + +后续 PR 按能力族继续拆分；每个 PR 保持实现与 E2E 同步。先补基础语义和接口，再扩索引/函数数量，避免错误的数据类型或身份模型扩散。 diff --git a/ROADMAP.md b/ROADMAP.md index 7fdf3c0..a36adc0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,161 +1,163 @@ -# Milvus 2.6 全功能支持 Roadmap +# Milvus 2.6 Full-Feature Support Roadmap -更新日期：2026-09-18。当前实现基线：`077de63`（PR #2）。 +[中文版](ROADMAP-cn.md) -目标：通过 MySQL 和 PostgreSQL 两种协议，完整提供 **Milvus 2.6.23 已实现、面向用户的数据与管理能力**。两个协议使用同一个能力模型、执行计划和权限语义；`mysql`、`postgres`、`both` 三种启动模式持续通过 E2E。 +Updated: 2026-09-18. Implementation baseline: `077de63` (PR #2). -这是实现计划，文中的新增 SQL、过程名及阶段均为**待实现草案**，不能作为当前支持说明。当前可用语法以 [Readme.md](Readme.md) 为准。 +Goal: expose **the implemented, user-facing data and administration capabilities of Milvus 2.6.23** through both MySQL and PostgreSQL protocols. Both protocols share one capability model, execution plan, and authorization model. The `mysql`, `postgres`, and `both` startup modes must continue to pass E2E tests. -## 1. 版本与范围 +This is an implementation plan. New SQL syntax, procedure names, and delivery stages below are **unimplemented proposals**, not claims of current support. See [Readme.md](Readme.md) for the currently supported syntax. -- **完整支持目标固定为 2.6.23**；这是本次核对的官方 2.6 发布基线。后续 2.6 补丁通过独立兼容性 PR 更新目标，不能悄悄扩大支持声明。[发布说明](https://milvus.io/docs/v2.6.x/release_notes.md) -- **2.6.2 保留已有功能回归**，不承诺它拥有后续补丁新增的能力。每项功能记录最低已验证 server/SDK 版本、部署条件和测试证据。 -- 覆盖数据模型、DDL、DML、查询/搜索、索引、函数、导入、权限、资源管理和公开运维 API；每个功能的请求参数、结果类型、状态查询和失败行为都属于范围。 -- GPU、分布式资源组、外部模型服务等能力属于目标，需要专用测试环境；缺少环境时标记“未验证”，不能算完成。 -- JOIN、跨集合事务、外键、通用 SQL 聚合/窗口函数、任意表达式 UPDATE、完整 MySQL/PostgreSQL 系统目录不属于 Milvus 原生能力。代理不以隐式全量拉取、读改写模拟这些语义。 -- Streaming Node、Woodpecker、Storage V2、JSON shredding 等服务端内部实现通过兼容性测试验证；安装、扩缩容、备份/CDC 工具和集群配置有各自运维边界。它们不等同于新增 SQL 运算符。 -- proto 中存在不等于服务端可用：废弃、未实现、内部复制/救援接口逐项列在 [API 盘点](docs/milvus-2.6-api-inventory.md)，附依据和处理方式，不能无声遗漏或算作完成。 +## 1. Version and Scope -## 2. 当前基础与缺口 +- **The full-support target is pinned to 2.6.23**, the official 2.6 release baseline verified for this roadmap. Update the target through a separate compatibility PR for subsequent 2.6 patches; do not silently expand support claims. [Release notes](https://milvus.io/docs/v2.6.x/release_notes.md) +- **Keep regression coverage for existing features on 2.6.2.** This does not imply that it supports features introduced in later patches. Record each feature's minimum verified server/SDK versions, deployment requirements, and test evidence. +- Cover data models, DDL, DML, queries/searches, indexes, functions, imports, authorization, resource management, and public operational APIs. Request parameters, result types, status queries, and failure behavior are all part of each feature's scope. +- GPU, distributed resource groups, and external model services are in scope and require dedicated test environments. Mark capabilities without such validation as unverified, not complete. +- JOINs, cross-collection transactions, foreign keys, general SQL aggregation/window functions, arbitrary-expression UPDATEs, and complete MySQL/PostgreSQL system catalogs are not native Milvus capabilities. The proxy will not emulate these semantics through implicit full scans or read-modify-write operations. +- Validate compatibility with server internals such as Streaming Node, Woodpecker, Storage V2, and JSON shredding. Installation, scaling, backup/CDC tools, and cluster configuration have separate operational boundaries; they do not each require a new SQL operator. +- A proto declaration does not prove server availability. The [API inventory](docs/milvus-2.6-api-inventory.md) explicitly classifies deprecated, unimplemented, and internal replication/recovery interfaces, with evidence and handling rules. Do not silently omit them or count them as complete. -| 领域 | 当前已实现 | 距离完整支持的主要缺口 | +## 2. Current Foundation and Gaps + +| Area | Currently implemented | Main gaps to full support | | --- | --- | --- | -| 协议 | MySQL text/prepared；PG simple/extended；双端口；TLS 配置 | 中立结果模型、更多类型编码、取消、流式结果、稳定错误映射 | -| SDK | `milvus-sdk-go/v2`、proto 均为 2.3.3 | 升级现代 `milvus/client/v2`，补齐 SDK 缺口和能力门控 | -| Schema | 基础标量、JSON、float32 vector、主键/AutoID | nullable/default、动态字段、ARRAY、其他向量、结构数组、GIS、时间类型、schema 演进 | -| 管理 | DB/collection CRUD 子集、手工分区、load/release/flush | 属性、别名、统计、状态、异步任务、分区键、资源组、compaction、RBAC | -| 数据 | insert、全行 upsert、带过滤 delete | 分区路由、partial upsert、自动 ID 结果、完整 mutation 计数、bulk import | -| 查询 | 投影、基础过滤、count、分页、单条 dense ANN | 全表达式、batch NQ、稀疏/BM25、hybrid、rerank、范围/分组/迭代搜索 | -| 索引 | FLAT/HNSW/IVF_FLAT/AUTOINDEX/INVERTED | 其余索引、参数矩阵、状态/进度、属性变更、JSON/文本/空间索引 | -| 验证 | 2.6.2，实际二进制 × 三种模式；覆盖率门槛 90% | 2.6.23 全能力验证、SDK 对照、类型逐值断言、分布式/GPU/模型测试 | +| Protocols | MySQL text/prepared; PG simple/extended; dual listeners; TLS configuration | Neutral result model, additional type encodings, cancellation, streaming results, stable error mapping | +| SDK | `milvus-sdk-go/v2` and proto at 2.3.3 | Migrate to modern `milvus/client/v2`, fill SDK gaps, and gate capabilities | +| Schema | Basic scalars, JSON, float32 vectors, primary keys/AutoID | Nullable/default values, dynamic fields, ARRAY, other vector types, struct arrays, GIS, temporal types, schema evolution | +| Administration | Subset of database/collection CRUD, manual partitions, load/release/flush | Properties, aliases, statistics, status, asynchronous tasks, partition keys, resource groups, compaction, RBAC | +| Data | Insert, full-row upsert, filtered delete | Partition routing, partial upsert, generated IDs, complete mutation counts, bulk import | +| Queries | Projection, basic filters, count, pagination, single-query dense ANN | Complete expressions, batch NQ, sparse/BM25, hybrid search, reranking, range/grouping/iterator search | +| Indexes | FLAT/HNSW/IVF_FLAT/AUTOINDEX/INVERTED | Remaining indexes, parameter matrix, state/progress, property changes, JSON/text/spatial indexes | +| Validation | 2.6.2, real executable in three modes; 90% coverage gate | Full capability validation on 2.6.23, SDK comparisons, value assertions for every type, distributed/GPU/model tests | -依据：[go.mod](go.mod)、[执行层](pkg/conn.go)、[SQL 命令](pkg/commands.go)、[生命周期测试](pkg/integration_test.go)、[E2E](.github/workflows/e2e.yml)。这些基础能力仍需扩充参数和结果断言，不能整体标为“全功能完成”。 +Evidence: [go.mod](go.mod), [execution layer](pkg/conn.go), [SQL commands](pkg/commands.go), [lifecycle tests](pkg/integration_test.go), and [E2E workflow](.github/workflows/e2e.yml). Existing capabilities still need broader parameter and result assertions and cannot be marked collectively as feature-complete. -## 3. 设计约定 +## 3. Design Contracts -1. **一份 AST/计划，两种协议。** 将共享执行层当前使用的 MySQL result 类型替换为协议中立的列元数据、值、mutation 结果和结构化错误；协议层只负责绑定与编码。 -2. **结构化解析。** 扩展语法进入明确 AST，逐步替换 lifecycle/index 的正则分派。参数绑定携带类型，不拼接不可信 filter、JSON 或管理参数；复合类型有大小/维度/深度限制。 -3. **SQL 加显式 Milvus 扩展。** 常规 CRUD/DDL 使用 SQL；复杂搜索、异步任务及管理能力使用具名 `CALL milvus_*` 扩展。为每个过程固定参数 schema、结果列、权限、取消和版本要求，禁止提供任意 RPC/管理透传后门。 -4. **忠实保留语义。** 区分 SQL NULL、缺失动态键、JSON null；保留向量精度、距离方向、NQ 分组和排名；不把 ANN group-by 解释成关系聚合，不把异步提交成功解释成任务完成。 -5. **版本和环境共同决定能力。** `SHOW MILVUS CAPABILITIES`（草案）显示 server/SDK 版本、能力、限制、部署前提和验证状态。版本未知时不能猜测支持；必要时采用只读探测及显式配置。 -6. **权限贯穿执行链。** 每个会话有独立上游身份/数据库上下文；跨库、别名、导入、管理过程也必须鉴权。现有单个共享上游账号模式明确标为 service-account 模式，不能声称已有用户级 RBAC。 -7. **受控 SDK 补缺。** 首选固定版本官方 Go SDK；缺失能力封装到窄接口的 gRPC/REST v2 adapter，复用身份、TLS、超时和错误处理。不能因为 SDK 缺失就把 Milvus 能力从范围中删除。 +1. **One AST/plan, two protocols.** Replace the shared execution layer's MySQL result types with protocol-neutral column metadata, values, mutation results, and structured errors. Protocol adapters handle binding and encoding only. +2. **Structured parsing.** Give extensions explicit AST nodes and progressively replace lifecycle/index regex dispatch. Preserve types during binding; do not concatenate untrusted filters, JSON, or administration parameters. Bound composite values by size, dimension, and depth. +3. **SQL with explicit Milvus extensions.** Use SQL for ordinary CRUD/DDL and named `CALL milvus_*` extensions for complex searches, asynchronous tasks, and administration. Define each procedure's parameter schema, result columns, permissions, cancellation, and version requirements. Do not expose arbitrary RPC or administration passthrough. +4. **Preserve native semantics.** Distinguish SQL NULL, absent dynamic keys, and JSON null. Preserve vector precision, distance direction, NQ boundaries, and ranking. ANN grouping is not relational aggregation, and successful asynchronous submission is not task completion. +5. **Capabilities depend on both version and environment.** The proposed `SHOW MILVUS CAPABILITIES` reports server/SDK versions, capabilities, restrictions, deployment requirements, and validation status. Do not assume support when versions are unknown; use read-only probes and explicit configuration where needed. +6. **Authorization applies throughout execution.** Each session has an independent upstream identity/database context. Cross-database operations, aliases, imports, and administration procedures require authorization too. Label the current shared upstream account configuration as service-account mode; it does not provide per-user RBAC. +7. **Fill SDK gaps through controlled adapters.** Prefer a pinned official Go SDK. Encapsulate missing capabilities in narrowly scoped gRPC/REST v2 adapters that reuse identity, TLS, timeouts, and error handling. SDK omissions do not remove Milvus capabilities from scope. -## 4. 实施顺序与验收 +## 4. Delivery Stages and Acceptance -阶段按依赖推进，不承诺未经估算的日期。P0 建立契约后，P1–P3 构成基础数据闭环；P4–P7 补齐高级与管理能力；P8 完成全量验收。P7 的身份设计从 P0 开始，管理功能发布必须受它约束。 +Follow dependencies rather than committing to dates without estimates. After P0 establishes contracts, P1–P3 complete the basic data lifecycle; P4–P7 add advanced and administration capabilities; P8 completes acceptance. Identity design for P7 starts in P0 and gates the release of administration features. -### P0 — SDK、能力清单与双协议基础 +### P0 — SDK, Capability Inventory, and Protocol Foundation -- [ ] 升级到固定的现代 Go SDK/proto，逐项迁移 session client、schema、index、mutation 和异步等待行为；保留 2.6.2 已有功能回归。 -- [ ] 建立机器可读 feature registry：`id / operation / parameters / min_server / sdk_or_adapter / deployment / mysql / postgres / tests / status / exclusion_reason`。 -- [ ] 将 API 盘点扩展到参数、schema 枚举、表达式、索引及 SDK 组合操作；每个条目有阶段和实现/测试链接。 -- [ ] 建立协议中立的值/结果/错误模型；定义两端的 SQLSTATE/错误码、参数类型、64 位整数、NULL、二进制和复杂类型编码。 -- [ ] 定义取消与超时、mutation 重试边界、幂等性和任务状态契约；超时不自动重放可能已提交的写操作。 -- [ ] 将 E2E 增加固定 2.6.23 目标，保留 2.6.2 回归；先迁移再增加语法，避免 SDK 升级与全部新特性混成一个 PR。 +- [ ] Upgrade to a pinned modern Go SDK/proto; migrate session clients, schemas, indexes, mutations, and asynchronous waits individually. Preserve existing 2.6.2 regressions. +- [ ] Create a machine-readable feature registry: `id / operation / parameters / min_server / sdk_or_adapter / deployment / mysql / postgres / tests / status / exclusion_reason`. +- [ ] Extend the API inventory to parameters, schema enums, expressions, indexes, and SDK composite operations. Assign every entry a stage and implementation/test links. +- [ ] Establish neutral value/result/error models. Define SQLSTATE/error codes, parameter types, 64-bit integers, NULL, binary values, and complex encodings for both protocols. +- [ ] Define cancellation, timeouts, mutation retry boundaries, idempotency, and task status contracts. Do not automatically replay writes that may have committed before a timeout. +- [ ] Add a pinned 2.6.23 E2E target while retaining 2.6.2 regressions. Migrate before extending syntax; keep the SDK upgrade separate from the full feature expansion. -**验收：** 原有测试与三模式 E2E 在两个固定版本上通过；已有 SQL 行为不回退；未知能力有明确错误，不能静默忽略参数。 +**Acceptance:** existing tests and all three E2E modes pass on both pinned versions; existing SQL behavior remains intact; unknown capabilities produce explicit errors rather than silently ignoring parameters. -### P1 — 完整数据类型与 Schema +### P1 — Complete Data Types and Schema -- [ ] 基础类型边界：整数范围、浮点精度、VARCHAR 长度、JSON、INT64/VARCHAR 主键、AutoID 和 `allow_insert_auto_id` 等适用属性。 -- [ ] nullable/default、字段省略、显式 NULL 与默认值；按 server 对类型/主键/分区键的限制校验，不能对所有类型一律开放默认值。 -- [ ] 动态字段开关、读写、投影、嵌套路径和 schema 描述；支持服务端允许的开启/演进操作。 -- [ ] ARRAY 的元素类型/max_capacity；FloatVector、Float16Vector、BFloat16Vector、Int8Vector、BinaryVector、SparseFloatVector 的构造、绑定与返回。 -- [ ] Array of Structs、其中的向量子字段/多向量列表、嵌套结果与元素级检索所需 schema。不能把内部 `ArrayOfStruct` 枚举直接当用户顶层任意 STRUCT。 -- [ ] GEOMETRY/WKT、TIMESTAMPTZ/时区、相应 NULL 与过滤/索引支持。 -- [ ] 字段描述、analyzer/function output、partition key、clustering key；新增字段及可修改字段属性，保留不允许的 schema 修改错误。 +- [ ] Basic type boundaries: integer ranges, floating-point precision, VARCHAR length, JSON, INT64/VARCHAR primary keys, AutoID, and applicable properties such as `allow_insert_auto_id`. +- [ ] Nullable/default values, omitted fields, explicit NULL, and defaults. Enforce the server's type/primary-key/partition-key restrictions; do not enable defaults indiscriminately for every type. +- [ ] Dynamic field configuration, reads/writes, projection, nested paths, and schema descriptions, including server-supported enablement/evolution operations. +- [ ] ARRAY element types/max_capacity; construction, binding, and results for FloatVector, Float16Vector, BFloat16Vector, Int8Vector, BinaryVector, and SparseFloatVector. +- [ ] Arrays of Structs, their vector subfields/vector lists, nested results, and schemas required for element-level search. Do not expose the internal `ArrayOfStruct` enum as an arbitrary top-level STRUCT type. +- [ ] GEOMETRY/WKT, TIMESTAMPTZ/timezones, and their NULL, filtering, and indexing support. +- [ ] Field descriptions, analyzer/function outputs, partition keys, and clustering keys; add fields and modify supported properties while retaining errors for prohibited schema changes. -**验收：** 每个类型在 MySQL text/prepared 和 PG text/binary 结果中逐值往返；覆盖空数组、稀疏空向量、NULL、越界、坏 WKT、时区/DST、维度错误；Describe 不触发写入。类型/默认值限制以固定版本 schema 与执行结果为准。[类型定义](https://github.com/milvus-io/milvus-proto/blob/v2.6.23/proto/schema.proto) +**Acceptance:** every type round-trips with value assertions through MySQL text/prepared and PG text/binary results. Cover empty arrays, empty sparse vectors, NULL, overflow, invalid WKT, timezones/DST, and dimension errors. Describe must not mutate data. Type/default restrictions follow pinned schemas and actual server behavior. [Type definitions](https://github.com/milvus-io/milvus-proto/blob/v2.6.23/proto/schema.proto) -### P2 — DB、Collection、Partition 与生命周期 +### P2 — Databases, Collections, Partitions, and Lifecycle -- [ ] Database list/describe/create/alter/drop；属性设置/删除和默认值继承；跨库 collection 访问与移动/rename 的适用限制。 -- [ ] Collection has/list/describe/batch describe/statistics/create/rename/drop/truncate；shards、consistency、TTL、mmap、时区等已支持属性与参数。 -- [ ] Alias create/alter/drop/list/describe；变更后失效旧 schema/index 缓存，跨库解析不能串库。 -- [ ] 手工 partition has/list/create/drop/statistics/load/release；partition key、自动分区数、partition-key isolation 和 clustering key。 -- [ ] Load/release 的 replica、resource groups、指定字段、skip dynamic field 等适用选项；load state/progress。 -- [ ] Flush/flush-all、异步状态和等待；明确“数据已提交”“已持久化”“已加载可查”的不同状态。 -- [ ] 需要的 `IF EXISTS / IF NOT EXISTS` 基于真实存在性与并发错误处理，不吞权限和网络错误。 +- [ ] Database list/describe/create/alter/drop; property setting/removal and default inheritance; restrictions on cross-database collection access, moves, and renames. +- [ ] Collection has/list/describe/batch describe/statistics/create/rename/drop/truncate; supported properties and parameters including shards, consistency, TTL, mmap, and timezone. +- [ ] Alias create/alter/drop/list/describe; invalidate stale schema/index caches after changes and keep cross-database resolution isolated. +- [ ] Manual partition has/list/create/drop/statistics/load/release; partition keys, automatic partition counts, partition-key isolation, and clustering keys. +- [ ] Applicable load/release options for replicas, resource groups, selected fields, and skipping dynamic fields; load state/progress. +- [ ] Flush/flush-all, asynchronous status, and waits. Distinguish submitted data, durable data, and loaded/queryable data. +- [ ] Required `IF EXISTS / IF NOT EXISTS` behavior based on real existence checks and concurrent error handling, without swallowing authorization or network failures. -**验收：** 对照 SDK 检查所有属性与统计；别名重指向、跨会话/跨库隔离、异步失败、reload、分区加载后可见性、truncate 保留 schema/index 等行为正确。 +**Acceptance:** compare all properties and statistics with the SDK. Validate alias retargeting, session/database isolation, asynchronous failures, reloads, partition visibility after loading, and preservation of schema/indexes after truncation. -### P3 — DML 与完整过滤/查询 +### P3 — DML and Complete Filtering/Querying -- [ ] INSERT/full UPSERT/partial UPSERT：命名列、分区选择、AutoID 语义、返回主键/时间戳/计数；没有上游精确计数时不能伪造。 -- [ ] partial upsert 的字段省略、动态键 merge、JSON 整列替换、ARRAY_APPEND/ARRAY_REMOVE；以原生 Upsert 请求实现，不做代理端隐式读改写。[Upsert 语义](https://milvus.io/docs/v2.6.x/upsert-entities.md) -- [ ] DELETE 按主键/过滤表达式及分区；显式全量删除接口与防误操作语法；不能将当前拒绝裸 DELETE 的行为悄悄改为全量删除。 -- [ ] Get-by-ID、query、count、字段/动态键/嵌套投影、别名和迭代读取；返回字段顺序、空结果元数据与计数语义。 -- [ ] 过滤比较/逻辑/算术、IN、LIKE、NULL、JSON/ARRAY contains/contains_all/contains_any、长度/下标/路径、存在性、文本和 GIS/时间表达式；逐运算符登记版本/类型约束。 -- [ ] 参数化过滤模板、unicode/转义/注入边界；处理缺失键、JSON null、类型不匹配的三值逻辑。 -- [ ] Strong/Bounded/Session/Eventual 及服务端公开的 consistency/时间戳选项；会话级与请求级覆盖、时间戳单位与适用限制。 -- [ ] Query iterator 生命周期、fetch/close/断连清理、背压和有界内存；不通过不断增加 offset 冒充迭代器。 +- [ ] INSERT/full UPSERT/partial UPSERT: named columns, partition selection, AutoID semantics, returned primary keys/timestamps/counts. Never fabricate exact counts unavailable from upstream. +- [ ] Partial upsert field omission, dynamic-key merging, whole-value JSON replacement, and ARRAY_APPEND/ARRAY_REMOVE. Use native Upsert requests rather than implicit proxy-side read-modify-write. [Upsert semantics](https://milvus.io/docs/v2.6.x/upsert-entities.md) +- [ ] DELETE by primary key/filter and partition; explicit full-deletion interfaces and syntax that prevents accidental deletion. Do not silently change today's rejection of unfiltered DELETE into a full deletion. +- [ ] Get-by-ID, query, count, field/dynamic-key/nested projection, aliases, and iteration; result column order, empty-result metadata, and count semantics. +- [ ] Comparison/logical/arithmetic filters, IN, LIKE, NULL, JSON/ARRAY contains/contains_all/contains_any, length/subscript/path operations, existence checks, text, GIS, and temporal expressions. Record version/type constraints per operator. +- [ ] Parameterized filter templates, Unicode, escaping, and injection boundaries; three-valued logic for absent keys, JSON null, and type mismatches. +- [ ] Strong/Bounded/Session/Eventual and public server consistency/timestamp options; session/request overrides, timestamp units, and applicability restrictions. +- [ ] Query iterator lifecycle, fetch/close/disconnection cleanup, backpressure, and bounded memory. Increasing offsets is not a substitute for a native iterator. -**验收：** SDK 差分测试逐字段/计数核对；覆盖过滤真值表、写后读、分区隔离、多个客户端、超过单次窗口的数据遍历；partial upsert 的非事务并发语义写入文档。 +**Acceptance:** SDK differential tests compare every field and count. Cover filter truth tables, read-after-write, partition isolation, multiple clients, and traversal beyond a single result window. Document nontransactional concurrency semantics for partial upserts. -### P4 — 向量搜索全能力 +### P4 — Complete Vector Search -- [ ] 所有向量类型的 single/batch NQ；结果带 query index、rank、PK、distance/score，保留每个 query 的边界。 -- [ ] 搜索字段/分区、topK/offset、索引专用搜索参数、metric、round_decimal、ignore_growing、输出字段及动态字段。 -- [ ] 标准/迭代过滤、range search、search iterator；控制 radius/range_filter 的不同 metric 方向和边界。 -- [ ] Grouping search：group_by_field、group_size、strict_group_size 等固定版本支持项；不是通用 SQL GROUP BY。 -- [ ] 多路 HybridSearch、每路 ANN 请求/过滤/候选数，RRF 和 WeightedRanker、最终 limit/offset 与 score。[融合说明](https://milvus.io/docs/v2.6.x/reranking.md) -- [ ] Array-of-vector/EmbeddingList、结构数组元素搜索、服务端支持的聚合相似度与结果定位；不把多向量字段单独检索当 hybrid 已完成。 -- [ ] 按主键搜索等固定版本公开搜索输入，以及高级检索选项，完成 SDK/请求参数清单后逐项实现；不凭 proto 字段直接开放。 +- [ ] Single/batch NQ for all vector types; results include query index, rank, primary key, and distance/score while preserving each query's boundaries. +- [ ] Search fields/partitions, topK/offset, index-specific search parameters, metric, round_decimal, ignore_growing, output fields, and dynamic fields. +- [ ] Standard/iterative filtering, range search, and search iterators; enforce metric-specific radius/range_filter directions and boundaries. +- [ ] Grouping search: group_by_field, group_size, strict_group_size, and other options supported by the pinned version. This is not general SQL GROUP BY. +- [ ] Multi-request HybridSearch with per-request ANN options/filters/candidate counts, RRF and WeightedRanker, final limit/offset, and scores. [Reranking](https://milvus.io/docs/v2.6.x/reranking.md) +- [ ] Array-of-vector/EmbeddingList, struct-array element search, supported aggregate similarity, and result locations. Searching separate vector fields individually does not complete hybrid support. +- [ ] Public search inputs such as primary-key search and advanced retrieval options supported by the pinned version. Implement them after completing the SDK/request-parameter inventory, not merely because a proto field exists. -**验收：** FLAT 精确 oracle + 固定随机种子；ANN 使用明确 recall 门槛，距离浮点容差、并列排名规则、分组数及 NQ 隔离独立断言。Hybrid 分数/顺序对照官方 SDK，而非只检查非空结果。 +**Acceptance:** use a FLAT exact oracle and fixed random seeds. Set explicit ANN recall thresholds and separately assert floating-point distance tolerance, tie handling, group counts, and NQ isolation. Compare hybrid scores/order with the official SDK rather than only checking nonempty results. -### P5 — 全文、Analyzer、函数与重排 +### P5 — Full Text, Analyzers, Functions, and Reranking -- [ ] 文本字段 analyzer 配置、tokenizer/filter、多语言/多 analyzer（按版本）、TEXT_MATCH、PHRASE_MATCH；RunAnalyzer 和 token 输出选项。 -- [ ] BM25 function/schema、稀疏索引、原始文本搜索、稀疏/稠密混合检索、函数输出字段读写限制。 -- [ ] Collection function 的 create/add/alter/drop/describe；TextEmbedding 的服务端已支持 provider/config，输入输出字段映射和错误处理。 -- [ ] Function rerank：目标版本实际支持的模型、decay、boost 等类型/参数；与 hybrid 的 RRF/weighted 分开登记。 -- [ ] Text highlighter 的来源、字段、标签、片段和结果结构；处理空值、unicode 和动态文本。 -- [ ] MinHash/去重链路：2.6 已支持的预计算签名 + MINHASH_LSH/MHJACCARD；**不把后续版本的服务端 MinHash function 移植承诺到 2.6**。 +- [ ] Text-field analyzer configuration, tokenizers/filters, multilingual/multiple analyzers where supported, TEXT_MATCH, and PHRASE_MATCH; RunAnalyzer and token output options. +- [ ] BM25 functions/schemas, sparse indexes, raw-text search, sparse/dense hybrid search, and function-output read/write restrictions. +- [ ] Collection function create/add/alter/drop/describe; server-supported TextEmbedding providers/configuration, input/output field mapping, and error handling. +- [ ] Function reranking: models, decay, boost, and other types/parameters actually supported by the target version. Register these separately from hybrid RRF/weighted ranking. +- [ ] Text highlighting sources, fields, tags, fragments, and result structures; handle nulls, Unicode, and dynamic text. +- [ ] MinHash/deduplication: precomputed signatures with MINHASH_LSH/MHJACCARD supported in 2.6. **Do not promise later versions' server-side MinHash functions for 2.6.** -**验收：** 固定语料验证 token、BM25 排序和高亮；模型 adapter 使用契约测试，并在声明支持的真实 provider 上做可重复验证。日志不得泄露 provider 凭据；未跑真实 provider 的组合标为未验证。 +**Acceptance:** use a fixed corpus to verify tokens, BM25 ranking, and highlighting. Model adapters require contract tests and repeatable tests against each real provider claimed as supported. Logs must not expose provider credentials; combinations without real-provider tests remain unverified. -### P6 — 索引与性能选项 +### P6 — Indexes and Performance Options -- [ ] 建立“字段类型 × index × metric × build/search 参数 × CPU/GPU × 最低版本”清单，不以字符串透传替代支持。 -- [ ] dense：补齐 IVF_SQ8、IVF_PQ、SCANN、HNSW 的量化变体/精排选项、IVF_RABITQ 等目标版本支持项，以及 DISKANN、AISAQ；保留现有索引。 -- [ ] binary/sparse：BIN_FLAT、BIN_IVF_FLAT、MINHASH_LSH、SPARSE_INVERTED_INDEX 与适用算法；旧 SPARSE_WAND 按上游弃用策略兼容/报错。 -- [ ] GPU：GPU_CAGRA、GPU_IVF_FLAT、GPU_IVF_PQ、GPU_BRUTE_FORCE 等目标构建实际注册项；声明硬件/镜像/内存约束。 -- [ ] scalar：INVERTED、BITMAP、STL_SORT、TRIE、AUTOINDEX 等适用类型；JSON path/flat/cast 参数、ARRAY、NGRAM、文本匹配、GEOMETRY RTREE。 -- [ ] Index create/list/describe/drop/alter、statistics/state/progress、异步构建失败；mmap、缓存/预热等公开选项与实际生效边界。 +- [ ] Build an inventory of field type × index × metric × build/search parameters × CPU/GPU × minimum version. String passthrough alone is not support. +- [ ] Dense indexes: add IVF_SQ8, IVF_PQ, SCANN, HNSW quantization variants/refinement options, IVF_RABITQ, and other target-version capabilities, plus DISKANN and AISAQ. Preserve existing indexes. +- [ ] Binary/sparse indexes: BIN_FLAT, BIN_IVF_FLAT, MINHASH_LSH, SPARSE_INVERTED_INDEX, and applicable algorithms. Handle legacy SPARSE_WAND according to upstream deprecation policy. +- [ ] GPU indexes: GPU_CAGRA, GPU_IVF_FLAT, GPU_IVF_PQ, GPU_BRUTE_FORCE, and other entries actually registered in the target build. Document hardware/image/memory requirements. +- [ ] Scalar indexes: applicable INVERTED, BITMAP, STL_SORT, TRIE, and AUTOINDEX types; JSON path/flat/cast parameters, ARRAY, NGRAM, text matching, and GEOMETRY RTREE. +- [ ] Index create/list/describe/drop/alter, statistics/state/progress, and asynchronous build failures; public mmap/cache/warmup options and when they take effect. -**验收：** 从固定版本 index registry/validator 核对枚举；每个合法组合实际建索引、load、search/query、release、修改/删除并校验结果。非法组合明确失败；没有 GPU/磁盘环境的索引不能标完成。参考 [索引与 metric](https://milvus.io/docs/v2.6.x/index-vector-fields.md)（该概览已弃用，最终清单以固定版本实现与各索引文档为准）。 +**Acceptance:** reconcile enums with the pinned index registry/validators. For every legal combination, actually build, load, search/query, release, alter/drop, and verify results. Invalid combinations must fail explicitly. Indexes without GPU/disk validation cannot be complete. See [indexes and metrics](https://milvus.io/docs/v2.6.x/index-vector-fields.md); that overview is deprecated, so the final inventory must follow the pinned implementation and individual index documentation. -### P7 — 导入、权限、资源与运维管理 +### P7 — Import, Authorization, Resources, and Operations -- [ ] Bulk import：原生 import job 创建/list/progress/state、文件格式/存储路径/选项、失败原因和幂等边界；REST v2 能力独立核对，不能只看旧 gRPC Import。 -- [ ] CSV/JSON/Parquet/NumPy 等目标版本实际支持格式逐项测试；数据库、分区、AutoID、nullable、所有支持类型与导入后索引/加载闭环。 -- [ ] User/password/role/member、grant/revoke/list、Privilege V2、privilege group、role description、RBAC backup/restore；定义 SQL 用户与 Milvus principal 的映射。 -- [ ] 管理默认关闭，显式启用且使用最小上游权限；密码更新、权限撤销、会话存活与跨租户隔离均测试。共享 root 后端不能冒充用户级授权。 -- [ ] Resource group create/update/describe/list/drop、node/replica transfer、replica 配置/查询；query/streaming 资源组支持范围按目标部署核对。 -- [ ] Manual/clustering compaction、state/plans、segment/replica/statistics；公开 load balance 管理动作独立权限与审计。 -- [ ] Version/health、公开 metrics、代理请求日志/trace/延迟/错误/在途数；敏感 SQL 参数脱敏，取消和超时可关联到上游。 -- [ ] CDC/replication 公共配置与状态接口先确认支持契约，必要时提供受限管理过程；复制数据流、WAL dump、内部协调接口交给原生工具并记录集成边界。 +- [ ] Bulk import: native job creation/list/progress/state, file formats/storage paths/options, failure reasons, and idempotency boundaries. Audit REST v2 independently rather than relying solely on legacy gRPC Import. +- [ ] Test each format actually supported by the target version, including applicable CSV/JSON/Parquet/NumPy paths; cover databases, partitions, AutoID, nullable fields, all supported types, and post-import indexing/loading. +- [ ] Users/passwords/roles/membership, grant/revoke/list, Privilege V2, privilege groups, role descriptions, and RBAC backup/restore. Define SQL-user to Milvus-principal mapping. +- [ ] Disable administration by default; require explicit enablement and least-privilege upstream credentials. Test password changes, revocation, existing sessions, and tenant isolation. A shared root backend does not provide per-user authorization. +- [ ] Resource group create/update/describe/list/drop, node/replica transfers, and replica configuration/inspection. Verify query/streaming resource-group scope for the target deployment. +- [ ] Manual/clustering compaction, state/plans, and segment/replica/statistics APIs; separate permissions and auditing for public load-balancing actions. +- [ ] Version/health, public metrics, proxy request logs/traces/latency/errors/in-flight counts. Redact sensitive SQL parameters and correlate cancellation/timeouts with upstream requests. +- [ ] Verify public CDC/replication configuration/status contracts before exposing restricted administration procedures. Keep replication data streams, WAL dumps, and internal coordination in native tools, with documented integration boundaries. -**验收：** 真实启用鉴权的独立 Milvus 验证拒绝与允许；对象存储导入失败/恢复与行值校验；分布式多 QueryNode 验证资源组和副本迁移。所有 mutation 只操作测试创建的资源并完成清理。 +**Acceptance:** validate both allowed and denied requests against an isolated Milvus with authentication enabled. Test object-storage import failure/recovery and resulting values. Use distributed deployments with multiple QueryNodes to verify resource groups and replica transfers. Mutations and cleanup are restricted to resources created by the tests. -### P8 — 兼容性与发布验收 +### P8 — Compatibility and Release Acceptance -- [ ] MySQL text/binary/prepared、PG simple/extended/text/binary 的能力矩阵全部通过；NULL、空结果、复杂列元数据一致。 -- [ ] PostgreSQL CancelRequest 和 MySQL 查询取消路径、断连、statement/portal 关闭、超时后连接恢复、优雅退出；资源有界释放。 -- [ ] 真实 `mysql`/`psql` 和 Go/Python/JDBC 常用驱动 smoke；最小元数据兼容集单独文档化，不承诺所有 ORM。 -- [ ] 大 NQ、大批写入、大结果、并发会话、慢客户端、上游重启/连接失败、权限撤销与任务超时；规定吞吐、p95/p99、内存基线后测量代理开销。 -- [ ] 完成 capability registry 的参数与异常分支审计；公开状态、SQL/API 对照、最低版本和测试链接。 +- [ ] Pass the capability matrix for MySQL text/binary/prepared and PG simple/extended/text/binary; preserve NULL, empty results, and complex column metadata consistently. +- [ ] PostgreSQL CancelRequest and MySQL query-cancellation paths, disconnection, statement/portal closure, connection recovery after timeout, and graceful shutdown; release resources within bounded time. +- [ ] Smoke-test real `mysql`/`psql` clients and common Go/Python/JDBC drivers. Document the minimum metadata compatibility surface separately without promising all ORMs. +- [ ] Large NQ, batch writes/results, concurrent sessions, slow clients, upstream restarts/connection failures, permission revocation, and task timeouts. Define throughput, p95/p99, and memory baselines before measuring proxy overhead. +- [ ] Complete parameter and error-path audits of the capability registry. Publish status, SQL/API mappings, minimum versions, and test links. -**验收：** 所有范围内条目均有双协议真实 E2E 证据；没有 P0/P1 缺陷；排除项有上游依据。专用环境未验证项目意味着“部分支持”，不能发布“Milvus 2.6 全功能支持”的声明。 +**Acceptance:** every in-scope entry has real E2E evidence for both protocols, no severity-P0/P1 defects remain, and exclusions have upstream evidence. Unverified dedicated-environment capabilities mean partial support; do not release a claim of full Milvus 2.6 support. -## 5. SQL 接口草案 +## 5. Proposed SQL Interfaces -以下仅确定方向；实现前在对应 PR 固定语法、类型及错误契约，并增加 parser/protocol 测试。`CALL` 名称不是上游 Milvus SQL 标准。 +These examples establish direction only. Finalize syntax, types, and error contracts in the corresponding implementation PR, with parser/protocol tests. The `CALL` names are not an upstream Milvus SQL standard. ```sql --- P1/P2：扩展 DDL 与属性；WITH 的键和值按目标能力注册校验 +-- P1/P2: extended DDL/properties; validate WITH options against the registry CREATE TABLE docs ( id BIGINT PRIMARY KEY, title VARCHAR(512), @@ -166,52 +168,52 @@ CREATE TABLE docs ( ALTER TABLE docs ADD COLUMN category VARCHAR(64) NULL; SHOW MILVUS CAPABILITIES; --- P3：显式 partial update，不许隐式改成关系型 UPDATE +-- P3: explicit partial upsert, without implicit relational UPDATE semantics UPSERT INTO docs (id, title) VALUES (1, 'new title') WITH (partial_update=true); --- P4/P5：复杂请求通过强类型、具名过程；JSON 仅为绑定载体 +-- P4/P5: named, typed procedures; JSON is only the binding representation CALL milvus_search('docs', '{"anns_field":"embedding","data":[[1,0,0]],"limit":10}'); CALL milvus_hybrid_search('docs', ''); CALL milvus_run_analyzer(''); --- P7：长任务返回原生 job ID，可独立查询/等待 +-- P7: long-running tasks return native job IDs for separate status/wait calls CALL milvus_import('docs', ''); CALL milvus_import_status(''); CALL milvus_compact('docs', ''); ``` -MySQL 参数用 `?`，PostgreSQL 用 `$1` 等；对象名不能当普通值参数替换。复杂过程统一参数 schema，但两端分别定义结果列类型。最终语法需要保持现有 `json_vector(...)`、ANN LIKE 与 lifecycle 命令兼容。 +Use `?` parameters for MySQL and `$1`, etc. for PostgreSQL. Object identifiers cannot be substituted as ordinary value parameters. Complex procedures share parameter schemas but define result column types for each protocol. Final syntax must preserve compatibility with existing `json_vector(...)`, ANN LIKE, and lifecycle commands. -## 6. CI 与完成定义 +## 6. CI and Definition of Done -| 层级 | 计划运行方式 | 必须覆盖 | +| Layer | Planned execution | Required coverage | | --- | --- | --- | -| Unit / fuzz | 每个 PR | parser、类型转换、参数校验、计划、错误映射；`-race`、`go vet`、actionlint；statement coverage ≥90% | -| Core E2E | 每个 PR / main | 2.6.23 × mysql/postgres/both；2.6.2 原有能力回归；真实二进制和独立 Milvus | -| Feature E2E | 每个特性 PR；全量定时运行 | 每项类型/索引/过滤/搜索参数的正负例；对照官方 SDK；新增功能在不支持版本上明确失败 | -| Distributed / import / RBAC | 对应 PR 必跑；全量定时运行 | 多节点、对象存储、真实认证、权限撤销、异步失败、资源迁移 | -| GPU / provider / load | 专用 runner；对应特性发布前必跑 | 每个声明支持的硬件/模型组合及负载、故障验证 | +| Unit / fuzz | Every PR | Parser, conversions, parameter validation, plans, error mapping; `-race`, `go vet`, actionlint; statement coverage ≥90% | +| Core E2E | Every PR / main | 2.6.23 × mysql/postgres/both; existing-feature regressions on 2.6.2; real executable and isolated Milvus | +| Feature E2E | Each feature PR; full scheduled suite | Positive/negative cases for every type/index/filter/search parameter; official SDK comparisons; explicit rejection on unsupported versions | +| Distributed / import / RBAC | Required for relevant PRs; full scheduled suite | Multiple nodes, object storage, real authentication, revocation, asynchronous failures, resource transfers | +| GPU / provider / load | Dedicated runners; required before releasing relevant features | Each claimed hardware/model combination, load, and fault validation | -这些扩展 workflow 尚未实施；当前仍是 Readme 中的 2.6.2 测试。每个新阶段交付必须包含：实现、SQL 示例、权限/版本限制、双协议结果契约、单元测试、真实 E2E、review、CI 证据。 +These workflow extensions are not implemented yet; current tests still use 2.6.2 as described in the README. Every stage must deliver implementation, SQL examples, permission/version restrictions, result contracts for both protocols, unit tests, real E2E tests, review, and CI evidence. -测试需分别核对数据值、字段类型、NULL/缺失、PK、计数、顺序/距离和状态；不能只检查请求无错误或结果非空。长任务用状态轮询与截止时间，禁止用固定 sleep 作为成功依据。失败上传脱敏日志/版本/配置；测试只清理自身唯一命名资源。 +Tests must separately verify values, field types, NULL/absence, primary keys, counts, ordering/distances, and status. Success without errors or nonempty results is insufficient. Poll task states with deadlines; fixed sleeps do not prove completion. Upload redacted logs/versions/configuration on failure, and clean up only uniquely named test-owned resources. -“完成比例”按登记的能力及参数合同计算，不使用代码覆盖率或已映射 RPC 数量代替。跳过专用环境的测试、仅 mock 通过、只实现一个协议，均不能记为已验收。 +Measure completion against registered capabilities and parameter contracts, not code coverage or mapped RPC counts. Skipped dedicated-environment tests, mock-only success, or implementation of just one protocol do not meet acceptance. -## 7. 首批 PR 拆分 +## 7. Initial PR Breakdown -| 顺序 | 可独立 review 的交付 | 前置 | +| Order | Independently reviewable delivery | Prerequisites | | --- | --- | --- | -| 1 | feature registry 初版、固定版本 SDK/API 参数盘点、2.6.23 E2E 基线 | 本 roadmap | -| 2 | 现代 Go SDK/adapter 迁移，保持现有 SQL 合同 | 1 | -| 3 | 协议中立结果/错误类型，绑定/NULL/复杂类型编码基础 | 2 | -| 4 | nullable/default + ARRAY/dynamic field，逐值 E2E | 3 | -| 5 | 稀疏/低精度/二进制向量与对应基础索引 | 3 | -| 6 | collection 属性、别名、schema 演进、分区路由 | 2–4 | -| 7 | partial upsert、完整过滤模板和 consistency | 4、6 | -| 8 | batch/range/iterator/grouping + hybrid 检索 | 5、7 | -| 9 | BM25/analyzer/function/rerank 与高级类型/索引分批交付 | P1/P4 相应基础 | -| 10 | 身份映射与 RBAC 后启用 import/resource/compaction 管理；最终 P8 | P0 身份设计、P2 | - -后续 PR 按能力族继续拆分；每个 PR 保持实现与 E2E 同步。先补基础语义和接口，再扩索引/函数数量，避免错误的数据类型或身份模型扩散。 +| 1 | Initial feature registry, pinned SDK/API parameter inventory, 2.6.23 E2E baseline | This roadmap | +| 2 | Modern Go SDK/adapter migration preserving existing SQL contracts | 1 | +| 3 | Neutral result/error types and binding/NULL/complex-type encoding foundation | 2 | +| 4 | Nullable/default values and ARRAY/dynamic fields with value-level E2E assertions | 3 | +| 5 | Sparse/low-precision/binary vectors and corresponding basic indexes | 3 | +| 6 | Collection properties, aliases, schema evolution, partition routing | 2–4 | +| 7 | Partial upserts, complete filter templates, consistency | 4, 6 | +| 8 | Batch/range/iterator/grouping and hybrid search | 5, 7 | +| 9 | BM25/analyzers/functions/reranking and advanced types/indexes in separate batches | Relevant P1/P4 foundations | +| 10 | Identity mapping and RBAC before enabling import/resource/compaction administration; final P8 acceptance | P0 identity design, P2 | + +Split subsequent PRs by capability family, keeping implementation and E2E tests together. Establish core semantics and interfaces before expanding the number of indexes/functions so incorrect data-type or identity models do not spread. diff --git a/Readme.md b/Readme.md index 3d5277b..0d569c9 100644 --- a/Readme.md +++ b/Readme.md @@ -7,7 +7,7 @@ transactions and arbitrary SQL expressions are not supported. ## Roadmap -See the [Milvus 2.6 full-feature roadmap](ROADMAP.md) for staged delivery, +See the [Milvus 2.6 full-feature roadmap](ROADMAP.md) ([中文版](ROADMAP-cn.md)) for staged delivery, version boundaries, dual-protocol acceptance criteria, and the API inventory. Planned features are not current support claims. diff --git a/docs/milvus-2.6-api-inventory-cn.md b/docs/milvus-2.6-api-inventory-cn.md new file mode 100644 index 0000000..43fcb46 --- /dev/null +++ b/docs/milvus-2.6-api-inventory-cn.md @@ -0,0 +1,84 @@ +# Milvus 2.6.23 API 盘点 + +[English](milvus-2.6-api-inventory.md) + +更新日期：2026-09-18。配套 [Roadmap](../ROADMAP-cn.md)。 + +这是一份**范围与缺口清单**，不是实现完成清单。按固定版本 `MilvusService` 的 117 个 RPC 声明逐项分组，名称无遗漏/重复。范围分类依据公开用途、服务实现及项目边界；proto-only、deprecated、内部接口不能计作待实现的普通 SQL 能力。 + +源码依据： + +- [milvus.proto v2.6.23](https://github.com/milvus-io/milvus-proto/blob/v2.6.23/proto/milvus.proto)：RPC 请求/响应全集。 +- [schema.proto v2.6.23](https://github.com/milvus-io/milvus-proto/blob/v2.6.23/proto/schema.proto)：类型、函数、字段及搜索结果结构。 +- [Proxy impl v2.6.23](https://github.com/milvus-io/milvus/blob/v2.6.23/internal/proxy/impl.go)：实际实现、废弃及未实现返回。 +- [Proxy service v2.6.23](https://github.com/milvus-io/milvus/blob/v2.6.23/internal/distributed/proxy/service.go)：暴露入口和 Unimplemented server。 +- [REST v2 handler v2.6.23](https://github.com/milvus-io/milvus/blob/v2.6.23/internal/distributed/proxy/httpserver/handler_v2.go)：REST 补充入口，P0 需完整提取路由与请求字段。 + +## RPC 到阶段的映射 + +| 能力族 | 阶段/边界 | RPC | 当前情况与待办 | +| --- | --- | --- | --- | +| Database | P2 | `ListDatabases`, `CreateDatabase`, `DropDatabase`, `DescribeDatabase`, `AlterDatabase` | 已有 list/create/drop 子集；补 describe/alter/属性与跨库行为。 | +| Collection | P1/P2 | `CreateCollection`, `DropCollection`, `HasCollection`, `DescribeCollection`, `BatchDescribeCollection`, `ShowCollections`, `GetCollectionStatistics`, `AlterCollection`, `AlterCollectionField`, `AddCollectionField`, `RenameCollection`, `TruncateCollection` | 已有基础 create/drop/list/describe；其余操作及全部 schema/属性参数待补。 | +| Function DDL | P5 | `AddCollectionFunction`, `AlterCollectionFunction`, `DropCollectionFunction` | 待支持；创建时的 function schema 也纳入 P1/P5。 | +| Partition | P2/P3 | `CreatePartition`, `DropPartition`, `HasPartition`, `ShowPartitions`, `GetPartitionStatistics` | 已有 create/drop/list；补统计、存在性、路由与 key 分区语义。 | +| Load | P2 | `LoadCollection`, `ReleaseCollection`, `LoadPartitions`, `ReleasePartitions`, `GetLoadingProgress`, `GetLoadState` | 已有同步 load/release 子集；补参数、异步状态、进度和分布式行为。 | +| Alias | P2 | `CreateAlias`, `DropAlias`, `AlterAlias`, `DescribeAlias`, `ListAliases` | 待支持；涵盖缓存失效和权限/数据库边界。 | +| Index | P6 | `CreateIndex`, `AlterIndex`, `DescribeIndex`, `GetIndexStatistics`, `DropIndex` | 已有少量索引 create/describe/drop；补属性、状态及参数矩阵。 | +| 旧 index 状态接口 | P6/兼容 | `GetIndexState`, `GetIndexBuildProgress` | proto 标记 deprecated；优先统一到 DescribeIndex，保留语义映射证据，不另造过时 SQL。 | +| Mutation | P3 | `Insert`, `Delete`, `Upsert` | 已有基础路径；补 typed data、分区、partial update、结果和全部选项。 | +| Read/search | P3/P4/P5 | `Query`, `Search`, `HybridSearch` | 已有 query/search 子集；高级参数、表达式、迭代、函数、hybrid 待支持。 | +| Flush | P2 | `Flush`, `FlushAll`, `GetFlushState`, `GetFlushAllState` | 已有 collection flush；补异步、全局范围与状态。 | +| Compaction | P7 | `ManualCompaction`, `GetCompactionState`, `GetCompactionStateWithPlans` | 待支持；返回原生任务 ID，验证状态与 plans。 | +| Import | P7 | `Import`, `GetImportState`, `ListImportTasks` | 待支持；此组不代表 REST v2 import 全集，另盘点版本化 REST 路由。 | +| User/role | P7 | `CreateCredential`, `UpdateCredential`, `DeleteCredential`, `ListCredUsers`, `CreateRole`, `AlterRole`, `DropRole`, `OperateUserRole`, `SelectRole`, `SelectUser` | 待支持；SQL principal 到 Milvus principal 映射、角色描述及会话撤权。 | +| Privilege/RBAC | P7 | `OperatePrivilege`, `OperatePrivilegeV2`, `SelectGrant`, `BackupRBAC`, `RestoreRBAC`, `CreatePrivilegeGroup`, `DropPrivilegeGroup`, `ListPrivilegeGroups`, `OperatePrivilegeGroup` | 待支持；数据库/collection 范围、权限组和备份恢复。 | +| Resource group | P7 | `CreateResourceGroup`, `DropResourceGroup`, `UpdateResourceGroups`, `TransferNode`, `TransferReplica`, `ListResourceGroups`, `DescribeResourceGroup`, `GetReplicas` | 待支持；专用分布式环境验证。 | +| 公开诊断与受限管理 | P7 | `GetPersistentSegmentInfo`, `GetQuerySegmentInfo`, `GetMetrics`, `GetComponentStates`, `LoadBalance` | 待支持/逐项确认公开管理契约；管理鉴权、只读与 mutation 分开。 | +| Version/health | P0/P7 | `GetVersion`, `CheckHealth` | 待暴露能力/状态；SQL SELECT 1 就绪探测不能代替上游健康检查。 | +| Analyzer | P5 | `RunAnalyzer` | 待支持；参数、token、offset 等结果契约。 | +| 连接内部机制 | adapter 内部 | `Connect` | 由 SDK/连接 adapter 使用；不需要一条对用户开放的 SQL。 | +| 复制管理 | P7 待核契约 | `UpdateReplicateConfiguration`, `GetReplicateConfiguration`, `GetReplicateInfo` | 先验证目标版本公开/部署适用性，再选择受限管理过程或原生工具集成；关闭此项前不得宣称管理能力全覆盖。 | +| 复制/协调/救援 | 原生工具边界 | `ReplicateMessage`, `CreateReplicateStream`, `DumpMessages`, `AllocTimestamp`, `RegisterLink` | 内部数据流、时间戳/链路和 WAL 救援，不作为普通 SQL 入口；保留工具集成与运行兼容验证。 | +| 内部调试 | 不暴露 | `Dummy`, `ListIndexedSegment`, `DescribeSegmentIndexData` | 调试/索引内部数据接口，不以通用 SQL 任意访问；P0 审计仍需记录固定版本依据。 | +| 废弃距离 RPC | 上游不可用 | `CalcDistance` | 固定版本 Proxy 直接返回 CalcDistance deprecated；不承诺实现这条 RPC。 | +| 文件资源占位 RPC | 上游未实现 | `AddFileResource`, `RemoveFileResource`, `ListFileResources` | 固定版本 Proxy 返回 not implemented；不作为已发布用户能力。 | +| 标签/行策略占位 RPC | 上游未实现 | `AddUserTags`, `DeleteUserTags`, `GetUserTags`, `ListUsersWithTag`, `CreateRowPolicy`, `DropRowPolicy`, `ListRowPolicies` | 固定版本服务嵌入 UnimplementedMilvusServiceServer，未提供这些方法的 override；不能据 proto 承诺用户标签或行级策略。 | + +`ProxyService.RegisterLink` 是同一 proto 文件中的另一个服务，不计入上面的 MilvusService 数量，也不对 SQL 用户开放。SDK 内部调用 RPC 不代表用户 SQL 已覆盖该能力。 + +## RPC 表之外必须登记的能力 + +| 维度 | P0 清单要求 | 交付阶段 | +| --- | --- | --- | +| 类型/schema | 每个公开类型、元素/嵌套类型、nullable/default、PK、动态/partition/clustering key、字段属性及可修改范围 | P1/P2 | +| 表达式 | 算术/比较/逻辑、JSON/ARRAY、NULL/缺失、文本、GIS、时间、模板与各类型组合 | P3/P5 | +| 请求参数 | collection/database/partition、consistency、时间戳、超时、搜索/加载/写入所有公开选项；服务端默认值与限制 | P0–P7 | +| SDK 组合操作 | Get-by-ID、query/search iterator、等待任务、hybrid/rerank 等；不能因无独立 RPC 而漏掉 | P3–P5 | +| 索引/metric | 从固定版本 registry/validator 提取枚举和参数约束，再与 CPU/GPU 实际构建和官方索引文档交叉核对 | P6 | +| 函数与 provider | BM25、TextEmbedding、Rerank 的类型/参数/输入输出/环境约束，Analyzer 与 highlighter | P5 | +| REST-only/新入口 | 特别是 import v2 job create/list/progress/describe；确认与旧 Import 的差异 | P7 | +| 内部架构 | streaming/WAL/storage 的部署兼容、失败恢复；原生运维工具集成说明 | P7/P8 | + +类型注意：`schema.proto` 的 `Text` 枚举不证明支持 TEXT 列；2.6.23 发布说明明确修复了错误接受不支持 Text 类型的问题。全文能力使用支持的 VARCHAR/analyzer/function。`String` 等旧枚举、内部 `ArrayOfStruct` 也必须经 server 校验，不能直接作为 SQL 类型开放。[发布说明](https://milvus.io/docs/v2.6.x/release_notes.md) + +## 已知补丁门槛 + +以下为已核实的代表性门槛，**不是全部功能的最小版本表**。P0 需要填充完整 registry，按目标 server + SDK/adapter + 部署条件实际验证。 + +| 能力 | 上游标注门槛 | 实施要求 | +| --- | --- | --- | +| partial upsert merge | 2.6.2+ | 原生 partial_update；AutoID、缺失字段、动态/JSON 语义分别测试 | +| Array of Structs | 2.6.4+ | schema、嵌套类型和 search 选项分别登记，不认为所有后续扩展从 2.6.4 就可用 | +| text highlighter | 2.6.8+ | 字段/标签/结果结构测试；2.6.2 明确拒绝 | +| ARRAY_APPEND/ARRAY_REMOVE | 2.6.17+ | 原生 field_ops 与元素/容量约束测试 | +| nullable vectors、Struct 元素级搜索 | 2.6.18 新增 | 不能仅升级 schema 编码就宣称旧版本支持；字段/过滤限制单独测试 | + +来源：[版本记录](https://milvus.io/docs/v2.6.x/release_notes.md)、[Upsert](https://milvus.io/docs/v2.6.x/upsert-entities.md)、[Highlighter](https://milvus.io/docs/text-highlighter.md)。流动文档只作解释，固定 tag 和真实行为用于验收；2.6.23 之后的功能不自动进入本基线。 + +## 排除与未知项的关闭规则 + +- 上游未实现/废弃：引用固定 tag 中返回值或服务入口证据；以后目标版本恢复时重新评估。 +- 内部/工具边界：写明用途、为什么不开放普通 SQL、已有官方工具路径，以及代理所需兼容性测试。公开管理能力不能仅因实现复杂就改成“内部”。 +- 待核契约：必须补官方公开文档、服务实现、部署前提和最小调用验证，随后分配 P 阶段或有依据的边界；未关闭时不得宣布全覆盖。 +- 每项已实现能力继续按参数与结果合同拆分；本 RPC 表只防止遗漏，不作为支持百分比或完成率的分母。 diff --git a/docs/milvus-2.6-api-inventory.md b/docs/milvus-2.6-api-inventory.md index d940056..aa1d368 100644 --- a/docs/milvus-2.6-api-inventory.md +++ b/docs/milvus-2.6-api-inventory.md @@ -1,82 +1,84 @@ -# Milvus 2.6.23 API 盘点 +# Milvus 2.6.23 API Inventory -更新日期：2026-09-18。配套 [Roadmap](../ROADMAP.md)。 +[中文版](milvus-2.6-api-inventory-cn.md) -这是一份**范围与缺口清单**，不是实现完成清单。按固定版本 `MilvusService` 的 117 个 RPC 声明逐项分组，名称无遗漏/重复。范围分类依据公开用途、服务实现及项目边界；proto-only、deprecated、内部接口不能计作待实现的普通 SQL 能力。 +Updated: 2026-09-18. Companion to the [roadmap](../ROADMAP.md). -源码依据： +This is a **scope and gap inventory**, not an implementation checklist marked complete. It groups all 117 RPC declarations in the pinned `MilvusService`, without missing or duplicate names. Classification follows public purpose, server implementation, and project boundaries. Proto-only, deprecated, and internal interfaces must not be treated as ordinary SQL capabilities awaiting implementation. -- [milvus.proto v2.6.23](https://github.com/milvus-io/milvus-proto/blob/v2.6.23/proto/milvus.proto)：RPC 请求/响应全集。 -- [schema.proto v2.6.23](https://github.com/milvus-io/milvus-proto/blob/v2.6.23/proto/schema.proto)：类型、函数、字段及搜索结果结构。 -- [Proxy impl v2.6.23](https://github.com/milvus-io/milvus/blob/v2.6.23/internal/proxy/impl.go)：实际实现、废弃及未实现返回。 -- [Proxy service v2.6.23](https://github.com/milvus-io/milvus/blob/v2.6.23/internal/distributed/proxy/service.go)：暴露入口和 Unimplemented server。 -- [REST v2 handler v2.6.23](https://github.com/milvus-io/milvus/blob/v2.6.23/internal/distributed/proxy/httpserver/handler_v2.go)：REST 补充入口，P0 需完整提取路由与请求字段。 +Source evidence: -## RPC 到阶段的映射 +- [milvus.proto v2.6.23](https://github.com/milvus-io/milvus-proto/blob/v2.6.23/proto/milvus.proto): complete RPC request/response declarations. +- [schema.proto v2.6.23](https://github.com/milvus-io/milvus-proto/blob/v2.6.23/proto/schema.proto): types, functions, fields, and search result structures. +- [Proxy implementation v2.6.23](https://github.com/milvus-io/milvus/blob/v2.6.23/internal/proxy/impl.go): actual implementations and deprecated/unimplemented responses. +- [Proxy service v2.6.23](https://github.com/milvus-io/milvus/blob/v2.6.23/internal/distributed/proxy/service.go): exposed entry points and the unimplemented server base. +- [REST v2 handler v2.6.23](https://github.com/milvus-io/milvus/blob/v2.6.23/internal/distributed/proxy/httpserver/handler_v2.go): additional REST entry points; P0 must extract the complete routes and request fields. -| 能力族 | 阶段/边界 | RPC | 当前情况与待办 | +## RPC-to-Stage Mapping + +| Capability family | Stage/boundary | RPCs | Current status and remaining work | | --- | --- | --- | --- | -| Database | P2 | `ListDatabases`, `CreateDatabase`, `DropDatabase`, `DescribeDatabase`, `AlterDatabase` | 已有 list/create/drop 子集；补 describe/alter/属性与跨库行为。 | -| Collection | P1/P2 | `CreateCollection`, `DropCollection`, `HasCollection`, `DescribeCollection`, `BatchDescribeCollection`, `ShowCollections`, `GetCollectionStatistics`, `AlterCollection`, `AlterCollectionField`, `AddCollectionField`, `RenameCollection`, `TruncateCollection` | 已有基础 create/drop/list/describe；其余操作及全部 schema/属性参数待补。 | -| Function DDL | P5 | `AddCollectionFunction`, `AlterCollectionFunction`, `DropCollectionFunction` | 待支持；创建时的 function schema 也纳入 P1/P5。 | -| Partition | P2/P3 | `CreatePartition`, `DropPartition`, `HasPartition`, `ShowPartitions`, `GetPartitionStatistics` | 已有 create/drop/list；补统计、存在性、路由与 key 分区语义。 | -| Load | P2 | `LoadCollection`, `ReleaseCollection`, `LoadPartitions`, `ReleasePartitions`, `GetLoadingProgress`, `GetLoadState` | 已有同步 load/release 子集；补参数、异步状态、进度和分布式行为。 | -| Alias | P2 | `CreateAlias`, `DropAlias`, `AlterAlias`, `DescribeAlias`, `ListAliases` | 待支持；涵盖缓存失效和权限/数据库边界。 | -| Index | P6 | `CreateIndex`, `AlterIndex`, `DescribeIndex`, `GetIndexStatistics`, `DropIndex` | 已有少量索引 create/describe/drop；补属性、状态及参数矩阵。 | -| 旧 index 状态接口 | P6/兼容 | `GetIndexState`, `GetIndexBuildProgress` | proto 标记 deprecated；优先统一到 DescribeIndex，保留语义映射证据，不另造过时 SQL。 | -| Mutation | P3 | `Insert`, `Delete`, `Upsert` | 已有基础路径；补 typed data、分区、partial update、结果和全部选项。 | -| Read/search | P3/P4/P5 | `Query`, `Search`, `HybridSearch` | 已有 query/search 子集；高级参数、表达式、迭代、函数、hybrid 待支持。 | -| Flush | P2 | `Flush`, `FlushAll`, `GetFlushState`, `GetFlushAllState` | 已有 collection flush；补异步、全局范围与状态。 | -| Compaction | P7 | `ManualCompaction`, `GetCompactionState`, `GetCompactionStateWithPlans` | 待支持；返回原生任务 ID，验证状态与 plans。 | -| Import | P7 | `Import`, `GetImportState`, `ListImportTasks` | 待支持；此组不代表 REST v2 import 全集，另盘点版本化 REST 路由。 | -| User/role | P7 | `CreateCredential`, `UpdateCredential`, `DeleteCredential`, `ListCredUsers`, `CreateRole`, `AlterRole`, `DropRole`, `OperateUserRole`, `SelectRole`, `SelectUser` | 待支持；SQL principal 到 Milvus principal 映射、角色描述及会话撤权。 | -| Privilege/RBAC | P7 | `OperatePrivilege`, `OperatePrivilegeV2`, `SelectGrant`, `BackupRBAC`, `RestoreRBAC`, `CreatePrivilegeGroup`, `DropPrivilegeGroup`, `ListPrivilegeGroups`, `OperatePrivilegeGroup` | 待支持；数据库/collection 范围、权限组和备份恢复。 | -| Resource group | P7 | `CreateResourceGroup`, `DropResourceGroup`, `UpdateResourceGroups`, `TransferNode`, `TransferReplica`, `ListResourceGroups`, `DescribeResourceGroup`, `GetReplicas` | 待支持；专用分布式环境验证。 | -| 公开诊断与受限管理 | P7 | `GetPersistentSegmentInfo`, `GetQuerySegmentInfo`, `GetMetrics`, `GetComponentStates`, `LoadBalance` | 待支持/逐项确认公开管理契约；管理鉴权、只读与 mutation 分开。 | -| Version/health | P0/P7 | `GetVersion`, `CheckHealth` | 待暴露能力/状态；SQL SELECT 1 就绪探测不能代替上游健康检查。 | -| Analyzer | P5 | `RunAnalyzer` | 待支持；参数、token、offset 等结果契约。 | -| 连接内部机制 | adapter 内部 | `Connect` | 由 SDK/连接 adapter 使用；不需要一条对用户开放的 SQL。 | -| 复制管理 | P7 待核契约 | `UpdateReplicateConfiguration`, `GetReplicateConfiguration`, `GetReplicateInfo` | 先验证目标版本公开/部署适用性，再选择受限管理过程或原生工具集成；关闭此项前不得宣称管理能力全覆盖。 | -| 复制/协调/救援 | 原生工具边界 | `ReplicateMessage`, `CreateReplicateStream`, `DumpMessages`, `AllocTimestamp`, `RegisterLink` | 内部数据流、时间戳/链路和 WAL 救援，不作为普通 SQL 入口；保留工具集成与运行兼容验证。 | -| 内部调试 | 不暴露 | `Dummy`, `ListIndexedSegment`, `DescribeSegmentIndexData` | 调试/索引内部数据接口，不以通用 SQL 任意访问；P0 审计仍需记录固定版本依据。 | -| 废弃距离 RPC | 上游不可用 | `CalcDistance` | 固定版本 Proxy 直接返回 CalcDistance deprecated；不承诺实现这条 RPC。 | -| 文件资源占位 RPC | 上游未实现 | `AddFileResource`, `RemoveFileResource`, `ListFileResources` | 固定版本 Proxy 返回 not implemented；不作为已发布用户能力。 | -| 标签/行策略占位 RPC | 上游未实现 | `AddUserTags`, `DeleteUserTags`, `GetUserTags`, `ListUsersWithTag`, `CreateRowPolicy`, `DropRowPolicy`, `ListRowPolicies` | 固定版本服务嵌入 UnimplementedMilvusServiceServer，未提供这些方法的 override；不能据 proto 承诺用户标签或行级策略。 | - -`ProxyService.RegisterLink` 是同一 proto 文件中的另一个服务，不计入上面的 MilvusService 数量，也不对 SQL 用户开放。SDK 内部调用 RPC 不代表用户 SQL 已覆盖该能力。 - -## RPC 表之外必须登记的能力 - -| 维度 | P0 清单要求 | 交付阶段 | +| Database | P2 | `ListDatabases`, `CreateDatabase`, `DropDatabase`, `DescribeDatabase`, `AlterDatabase` | List/create/drop subset exists; add describe/alter, properties, and cross-database behavior. | +| Collection | P1/P2 | `CreateCollection`, `DropCollection`, `HasCollection`, `DescribeCollection`, `BatchDescribeCollection`, `ShowCollections`, `GetCollectionStatistics`, `AlterCollection`, `AlterCollectionField`, `AddCollectionField`, `RenameCollection`, `TruncateCollection` | Basic create/drop/list/describe exists; add remaining operations and complete schema/property parameters. | +| Function DDL | P5 | `AddCollectionFunction`, `AlterCollectionFunction`, `DropCollectionFunction` | Planned; function schemas at collection creation are also covered by P1/P5. | +| Partition | P2/P3 | `CreatePartition`, `DropPartition`, `HasPartition`, `ShowPartitions`, `GetPartitionStatistics` | Create/drop/list exists; add statistics, existence checks, routing, and partition-key semantics. | +| Load | P2 | `LoadCollection`, `ReleaseCollection`, `LoadPartitions`, `ReleasePartitions`, `GetLoadingProgress`, `GetLoadState` | Synchronous load/release subset exists; add parameters, asynchronous status, progress, and distributed behavior. | +| Alias | P2 | `CreateAlias`, `DropAlias`, `AlterAlias`, `DescribeAlias`, `ListAliases` | Planned, including cache invalidation and authorization/database boundaries. | +| Index | P6 | `CreateIndex`, `AlterIndex`, `DescribeIndex`, `GetIndexStatistics`, `DropIndex` | Create/describe/drop exists for a few indexes; add properties, status, and the parameter matrix. | +| Legacy index status | P6/compatibility | `GetIndexState`, `GetIndexBuildProgress` | Proto marks these deprecated. Prefer a unified DescribeIndex mapping with semantic evidence rather than new obsolete SQL interfaces. | +| Mutation | P3 | `Insert`, `Delete`, `Upsert` | Basic paths exist; add typed data, partitions, partial updates, results, and all options. | +| Read/search | P3/P4/P5 | `Query`, `Search`, `HybridSearch` | Query/search subset exists; advanced parameters, expressions, iteration, functions, and hybrid search remain planned. | +| Flush | P2 | `Flush`, `FlushAll`, `GetFlushState`, `GetFlushAllState` | Collection flush exists; add asynchronous behavior, global scope, and status. | +| Compaction | P7 | `ManualCompaction`, `GetCompactionState`, `GetCompactionStateWithPlans` | Planned; return native task IDs and verify state/plans. | +| Import | P7 | `Import`, `GetImportState`, `ListImportTasks` | Planned. This group is not the complete REST v2 import surface; audit versioned REST routes separately. | +| User/role | P7 | `CreateCredential`, `UpdateCredential`, `DeleteCredential`, `ListCredUsers`, `CreateRole`, `AlterRole`, `DropRole`, `OperateUserRole`, `SelectRole`, `SelectUser` | Planned; SQL-principal to Milvus-principal mapping, role descriptions, and revocation for existing sessions. | +| Privilege/RBAC | P7 | `OperatePrivilege`, `OperatePrivilegeV2`, `SelectGrant`, `BackupRBAC`, `RestoreRBAC`, `CreatePrivilegeGroup`, `DropPrivilegeGroup`, `ListPrivilegeGroups`, `OperatePrivilegeGroup` | Planned; database/collection scopes, privilege groups, and backup/restore. | +| Resource group | P7 | `CreateResourceGroup`, `DropResourceGroup`, `UpdateResourceGroups`, `TransferNode`, `TransferReplica`, `ListResourceGroups`, `DescribeResourceGroup`, `GetReplicas` | Planned; validate in a dedicated distributed environment. | +| Public diagnostics and restricted administration | P7 | `GetPersistentSegmentInfo`, `GetQuerySegmentInfo`, `GetMetrics`, `GetComponentStates`, `LoadBalance` | Planned, subject to verifying each public administration contract; distinguish authorization, reads, and mutations. | +| Version/health | P0/P7 | `GetVersion`, `CheckHealth` | Capability/status exposure is planned. A SQL SELECT 1 readiness probe does not replace upstream health checks. | +| Analyzer | P5 | `RunAnalyzer` | Planned; define parameter and token/offset result contracts. | +| Connection internals | Adapter-internal | `Connect` | Used by the SDK/connection adapter; no separate user-facing SQL command is required. | +| Replication administration | P7; contract verification pending | `UpdateReplicateConfiguration`, `GetReplicateConfiguration`, `GetReplicateInfo` | First verify public availability and deployment applicability, then choose restricted procedures or native-tool integration. Do not claim complete administration coverage while unresolved. | +| Replication/coordination/recovery | Native-tool boundary | `ReplicateMessage`, `CreateReplicateStream`, `DumpMessages`, `AllocTimestamp`, `RegisterLink` | Internal streams, timestamp/link coordination, and WAL recovery are not ordinary SQL interfaces. Retain tool integration and runtime compatibility validation. | +| Internal debugging | Not exposed | `Dummy`, `ListIndexedSegment`, `DescribeSegmentIndexData` | Debugging/internal index data APIs are not exposed through arbitrary SQL access. The P0 audit must still record pinned-version evidence. | +| Deprecated distance RPC | Unavailable upstream | `CalcDistance` | The pinned Proxy returns CalcDistance deprecated directly; do not promise support for this RPC. | +| File-resource placeholder RPCs | Unimplemented upstream | `AddFileResource`, `RemoveFileResource`, `ListFileResources` | The pinned Proxy returns not implemented; these are not released user capabilities. | +| Tag/row-policy placeholder RPCs | Unimplemented upstream | `AddUserTags`, `DeleteUserTags`, `GetUserTags`, `ListUsersWithTag`, `CreateRowPolicy`, `DropRowPolicy`, `ListRowPolicies` | The pinned service embeds UnimplementedMilvusServiceServer without overriding these methods. Proto declarations do not justify promises of user tags or row-level policies. | + +`ProxyService.RegisterLink` belongs to a separate service in the same proto file. It is excluded from the MilvusService count above and is not exposed to SQL users. An RPC used internally by the SDK does not mean its user-facing capability is covered by SQL. + +## Capabilities Beyond the RPC Table + +| Dimension | Required P0 inventory | Delivery stage | | --- | --- | --- | -| 类型/schema | 每个公开类型、元素/嵌套类型、nullable/default、PK、动态/partition/clustering key、字段属性及可修改范围 | P1/P2 | -| 表达式 | 算术/比较/逻辑、JSON/ARRAY、NULL/缺失、文本、GIS、时间、模板与各类型组合 | P3/P5 | -| 请求参数 | collection/database/partition、consistency、时间戳、超时、搜索/加载/写入所有公开选项；服务端默认值与限制 | P0–P7 | -| SDK 组合操作 | Get-by-ID、query/search iterator、等待任务、hybrid/rerank 等；不能因无独立 RPC 而漏掉 | P3–P5 | -| 索引/metric | 从固定版本 registry/validator 提取枚举和参数约束，再与 CPU/GPU 实际构建和官方索引文档交叉核对 | P6 | -| 函数与 provider | BM25、TextEmbedding、Rerank 的类型/参数/输入输出/环境约束，Analyzer 与 highlighter | P5 | -| REST-only/新入口 | 特别是 import v2 job create/list/progress/describe；确认与旧 Import 的差异 | P7 | -| 内部架构 | streaming/WAL/storage 的部署兼容、失败恢复；原生运维工具集成说明 | P7/P8 | +| Types/schema | Every public type, element/nested type, nullable/default behavior, primary key, dynamic/partition/clustering keys, field properties, and permitted alterations | P1/P2 | +| Expressions | Arithmetic/comparison/logic, JSON/ARRAY, NULL/absence, text, GIS, time, templates, and type combinations | P3/P5 | +| Request parameters | Collection/database/partition, consistency, timestamps, timeouts, and all public search/load/write options; server defaults and limits | P0–P7 | +| SDK composite operations | Get-by-ID, query/search iterators, task waits, hybrid search/reranking; do not omit operations because they lack a dedicated RPC | P3–P5 | +| Indexes/metrics | Extract enums and constraints from pinned registries/validators, then reconcile with actual CPU/GPU builds and official index documentation | P6 | +| Functions/providers | BM25, TextEmbedding, and Rerank types/parameters/inputs/outputs/environment restrictions; analyzers and highlighting | P5 | +| REST-only/new entry points | Especially import v2 job create/list/progress/describe; verify differences from legacy Import | P7 | +| Internal architecture | Streaming/WAL/storage deployment compatibility and failure recovery; native operations-tool integration | P7/P8 | -类型注意：`schema.proto` 的 `Text` 枚举不证明支持 TEXT 列；2.6.23 发布说明明确修复了错误接受不支持 Text 类型的问题。全文能力使用支持的 VARCHAR/analyzer/function。`String` 等旧枚举、内部 `ArrayOfStruct` 也必须经 server 校验，不能直接作为 SQL 类型开放。[发布说明](https://milvus.io/docs/v2.6.x/release_notes.md) +Type caveat: the `Text` enum in `schema.proto` does not establish TEXT column support. The 2.6.23 release notes explicitly describe a fix rejecting the unsupported Text type. Full-text capabilities use supported VARCHAR/analyzer/function facilities. Legacy enums such as `String` and internal `ArrayOfStruct` must also be validated against the server rather than exposed directly as SQL types. [Release notes](https://milvus.io/docs/v2.6.x/release_notes.md) -## 已知补丁门槛 +## Known Patch-Version Gates -以下为已核实的代表性门槛，**不是全部功能的最小版本表**。P0 需要填充完整 registry，按目标 server + SDK/adapter + 部署条件实际验证。 +These are verified representative gates, **not a complete minimum-version table**. P0 must populate the full registry and validate each target server + SDK/adapter + deployment combination. -| 能力 | 上游标注门槛 | 实施要求 | +| Capability | Upstream version gate | Implementation requirement | | --- | --- | --- | -| partial upsert merge | 2.6.2+ | 原生 partial_update；AutoID、缺失字段、动态/JSON 语义分别测试 | -| Array of Structs | 2.6.4+ | schema、嵌套类型和 search 选项分别登记，不认为所有后续扩展从 2.6.4 就可用 | -| text highlighter | 2.6.8+ | 字段/标签/结果结构测试；2.6.2 明确拒绝 | -| ARRAY_APPEND/ARRAY_REMOVE | 2.6.17+ | 原生 field_ops 与元素/容量约束测试 | -| nullable vectors、Struct 元素级搜索 | 2.6.18 新增 | 不能仅升级 schema 编码就宣称旧版本支持；字段/过滤限制单独测试 | +| Partial upsert merge | 2.6.2+ | Native partial_update; separately test AutoID, omitted fields, and dynamic/JSON semantics | +| Array of Structs | 2.6.4+ | Register schema, nested types, and search options separately; do not assume later extensions were all available in 2.6.4 | +| Text highlighter | 2.6.8+ | Test fields/tags/result structures; explicitly reject on 2.6.2 | +| ARRAY_APPEND/ARRAY_REMOVE | 2.6.17+ | Native field_ops and element/capacity constraints | +| Nullable vectors and Struct element-level search | Introduced in 2.6.18 | A schema-encoding upgrade does not make older servers support them; test field/filter restrictions separately | -来源：[版本记录](https://milvus.io/docs/v2.6.x/release_notes.md)、[Upsert](https://milvus.io/docs/v2.6.x/upsert-entities.md)、[Highlighter](https://milvus.io/docs/text-highlighter.md)。流动文档只作解释，固定 tag 和真实行为用于验收；2.6.23 之后的功能不自动进入本基线。 +Sources: [release history](https://milvus.io/docs/v2.6.x/release_notes.md), [Upsert](https://milvus.io/docs/v2.6.x/upsert-entities.md), and [Highlighter](https://milvus.io/docs/text-highlighter.md). Living documentation explains behavior; pinned tags and real execution establish acceptance. Features introduced after 2.6.23 do not automatically enter this baseline. -## 排除与未知项的关闭规则 +## Closing Exclusions and Unknowns -- 上游未实现/废弃：引用固定 tag 中返回值或服务入口证据；以后目标版本恢复时重新评估。 -- 内部/工具边界：写明用途、为什么不开放普通 SQL、已有官方工具路径，以及代理所需兼容性测试。公开管理能力不能仅因实现复杂就改成“内部”。 -- 待核契约：必须补官方公开文档、服务实现、部署前提和最小调用验证，随后分配 P 阶段或有依据的边界；未关闭时不得宣布全覆盖。 -- 每项已实现能力继续按参数与结果合同拆分；本 RPC 表只防止遗漏，不作为支持百分比或完成率的分母。 +- Unimplemented/deprecated upstream: cite responses or service entry-point evidence at the pinned tag. Reevaluate if a future target restores the capability. +- Internal/tool boundaries: document purpose, why ordinary SQL does not expose the interface, the official tool path, and required proxy compatibility tests. Implementation difficulty alone cannot turn a public administration capability into an internal exclusion. +- Unverified contracts: supply official public documentation, server implementation, deployment prerequisites, and a minimal execution test. Then assign a delivery stage or an evidenced boundary. Do not claim full coverage while these remain unresolved. +- Break each implemented capability down further by parameter and result contracts. This RPC table prevents omissions; it is not the denominator for support percentages or completion rates.