pyvastbase 0.2.6__tar.gz → 0.2.9__tar.gz

{pyvastbase-0.2.6 → pyvastbase-0.2.9}/MANIFEST.in

@@ -18,5 +18,10 @@ prune .ruff_cache
 prune .coverage
 prune .claude
 prune .scratch
+# Internal dev-convention docs — not shipped in the published package
+exclude CLAUDE.md
+exclude CONTEXT.md
+prune docs/adr
+prune docs/agents
 global-exclude *.pyc
 global-exclude __pycache__

{pyvastbase-0.2.6 → pyvastbase-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyvastbase
-Version: 0.2.6
+Version: 0.2.9
 Summary: Python SDK for Vastbase V3 (PyMilvus-style API)
 Author-email: "zhangzhijie(字节)" <zhangzj@vastdata.com.cn>
 License-Expression: MIT
@@ -21,6 +21,7 @@ Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: isort>=5.12.0; extra == "dev"
 Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: vermin>=1.6; extra == "dev"
 Provides-Extra: pool
 Requires-Dist: psycopg-pool>=3.2; extra == "pool"
 Provides-Extra: async
@@ -32,11 +33,12 @@ Requires-Dist: pytest-cov>=4.1.0; extra == "all"
 Requires-Dist: black>=23.0.0; extra == "all"
 Requires-Dist: isort>=5.12.0; extra == "all"
 Requires-Dist: mypy>=1.5.0; extra == "all"
+Requires-Dist: vermin>=1.6; extra == "all"
 Requires-Dist: psycopg-pool>=3.2; extra == "all"
 
 # pyvastbase
 
-Python SDK for Vastbase V3 — 对标 PyMilvus 接口风格，面向 Vastbase 向量引擎。支持 Vastbase 3.0.8+，对 3.0.9+ 新特性自动版本检测与功能门控。
+Python SDK for Vastbase 向量引擎 — 对标 PyMilvus 接口风格。支持 Vastbase V3 / VexDB Enterprise Edition / Vastbase G100 V2.2，自动识别产品线并映射版本，对 3.0.9+ 新特性自动版本检测与功能门控。
 
 ## 安装
 
@@ -70,7 +72,10 @@ results = client.search("my_vectors", data=[0.15] * 128, limit=5)
 db_info = client.describe_database("vastbase")
 print(db_info)  # {'name': 'vastbase', 'table_count': 5, ...}
 
-results = client.hybrid_search("my_vectors", data=[0.15] * 128, filter="price < 1000", limit=20)
+# 多路向量召回 + 重排序（pymilvus 兼容）
+from pyvastbase import AnnSearchRequest, RRFRanker
+req = AnnSearchRequest(data=[0.15] * 128, anns_field="embedding", limit=20)
+results = client.hybrid_search("my_vectors", reqs=[req], ranker=RRFRanker(), limit=20)
 ```
 
 ### 方式二：传统 Collection 风格
@@ -150,19 +155,23 @@ col.insert([{
 
 ## 版本检测与自动门控
 
-SDK 通过 `SELECT vb_version()` 自动检测已连接的 Vastbase 版本，并对 3.0.9+ 特性进行功能门控。版本信息**按连接缓存**——仅查询一次，后续所有检查复用缓存结果。
+SDK 通过 `SELECT vb_version()` 自动检测已连接的产品及版本，并对 3.0.9+ 特性进行功能门控。支持三种产品线，自动映射到统一的 V3 等效版本号。版本信息**按连接缓存**——仅查询一次，后续所有检查复用缓存结果。
 
-### 双重校验：Build + Patch（来自 vb_version()）
+### 多产品支持
 
-Vastbase 通过 Build 号和 Patch 级别共同标识版本：
+SDK 根据 `vb_version()` 输出中的 `product name:` 行自动识别产品，并应用对应的版本映射：
 
-```
-vb_version() 输出:
-  version:V3.0 (Build 9)    -> build = 9
-  patch:1                   -> patch_level = 1
-```
+| 产品 | product name 标识 | 版本格式 | 示例 |
+|------|-------------------|----------|------|
+| Vastbase V3 | 默认 / Vastbase V100 | `V<M>.<m> (Build <B>) + patch:<P>` | `V3.0 (Build 9) + patch:1` |
+| VexDB Enterprise Edition | VexDB Enterprise Edition | `V<M>.<m>.<B>.<P>` 四段式 | `V3.0.0.3` |
+| Vastbase G100 V2.2 | Vastbase G100 | `V<M>.<m> (Build <B>) + patch:<P>` | `V2.2 (Build 19) + patch:6` |
+
+所有产品线的版本号均映射为 V3 等效 `(major, minor, build, patch_level)` 元组，功能门控统一使用映射后的值。
+
+### 双重校验：Build + Patch（来自 vb_version()）
 
-功能门控**同时检查**两个条件：`build >= 9 AND patch_level >= 1`。
+功能门控**同时检查**两个条件：`build >= required_build AND patch_level >= required_patch`。
 
 ```python
 from pyvastbase import get_vb_version, check_vb_version
@@ -170,15 +179,16 @@ from pyvastbase import get_vb_version, check_vb_version
 ver = get_vb_version()
 print(ver["major"])              # 3
 print(ver["minor"])              # 0
-print(ver["build"])              # 9  (来自 version:V3.0 (Build 9))
-print(ver["patch_level"])        # 1  (来自 patch:1)
+print(ver["build"])              # 9
+print(ver["patch_level"])        # 1
+print(ver["product_name"])       # "VexDB Enterprise Edition"
+print(ver["commit"])             # "31338"
 print(ver["has_sparsevector"])   # True (build>=9 AND patch_level>=1)
 print(ver["has_int8vector"])     # True
 
-# 手动版本检查 (major, minor, build, patch_level)
-check_vb_version((3, 0, 9, 1))   # True — build 9 >= 9, patch 1 >= 1
+# 手动版本检查 (major, minor, build, patch_level) — 使用映射后的 V3 等效版本
+check_vb_version((3, 0, 9, 1))   # True — 所有产品线统一检查
 check_vb_version((3, 0, 9, 2))   # False — patch 1 < 2
-check_vb_version((3, 0, 8, 1))   # True — 服务器版本高于最低要求
 ```
 
 所有 3.0.9+ 操作在执行前会**自动校验**服务器版本。若服务器版本过低，会返回具体的错误信息，明确指出哪个条件未满足。
@@ -231,12 +241,12 @@ results = bm25_search_highlight(
 # 返回: ['<b>向量</b>数据库是AI应用的核心', ...]
 ```
 
-## 混合搜索
+## 混合 ANN 搜索（hybrid_ann_search）
 
-将向量相似度与标量字段过滤结合，实现灵活的复合查询：
+Vastbase 原生单向量相似度 + 标量字段过滤（HybridANN 索引），实现灵活的复合查询：
 
 ```python
-results = col.hybrid_search(
+results = col.hybrid_ann_search(
     data=[0.1] * 128,
     filter={
         "$and": [
@@ -266,7 +276,7 @@ for buf in bulkbuffer_inspect():
 
 ## MutationResult
 
-所有变更操作返回 `MutationResultWrapper`，同时支持向后兼容的列表访问和完整的 `MutationResult` 接口：
+所有变更操作返回 `MutationResult`，支持列表访问和结构化字段（`MutationResultWrapper` 为废弃别名，访问会触发 `DeprecationWarning`，但仍可用）：
 
 ```python
 result = col.insert([{"id": 1, "embedding": [0.1] * 128, "text": "hello"}])
@@ -382,7 +392,7 @@ except ConnectionError:
 | [ORM](docs/api-reference_zh.md#orm) | Entity, Model, Field, VectorField |
 | [Exceptions](docs/api-reference_zh.md#exceptions) | VastbaseException 继承层次 |
 | [Async API](docs/api-reference_zh.md#async-api) | AsyncCollection, AsyncConnections |
-| [MutationResult](docs/api-reference_zh.md#mutationresult) | MutationResult, MutationResultWrapper |
+| [MutationResult](docs/api-reference_zh.md#mutationresult) | MutationResult（MutationResultWrapper 为废弃别名） |
 
 ## 快速 API 参考
 
@@ -436,12 +446,13 @@ col.create()
 col.drop()
 col.exists()
 col.truncate()
-col.insert(data, normalize_vectors=False)          # -> MutationResultWrapper
+col.insert(data, normalize_vectors=False)          # -> MutationResult
 col.batch_insert(data, batch_size=100)
 col.delete(expr="id > 10") | delete(pks=[1, 2, 3])
 col.upsert(data)
 col.search(data, anns_field, param, limit, expr, output_fields)
-col.hybrid_search(data, anns_field, param, limit, filter, output_fields)
+col.hybrid_search(reqs, rerank, limit, output_fields)
+col.hybrid_ann_search(data, anns_field, param, limit, filter, output_fields)
 col.query(expr="id < 100", limit=10, offset=0, batch_size=None)
 col.get(ids=[1, 2, 3])
 col.num_entities / col.is_empty
@@ -493,7 +504,7 @@ get_config()  # -> {"default_connection": "default", "timeout": 30.0, ...}
 以下功能已与 pymilvus API 对齐：
 
 - **DataType IntEnum** — 所有标量和向量类型使用 IntEnum，与 pymilvus 枚举值兼容
-- **MutationResult** — `insert`/`upsert`/`delete` 返回 `MutationResultWrapper`，同时支持列表访问和结构化字段（`insert_count`, `delete_count`, `primary_keys`）
+- **MutationResult** — `insert`/`upsert`/`delete` 返回 `MutationResult`，支持列表访问和结构化字段（`insert_count`, `delete_count`, `primary_keys`）；`MutationResultWrapper` 为废弃别名
 - **SearchResult** — 搜索结果结构与 pymilvus 一致，支持 `result.id`, `result.distance`, `result.data`
 - **connect(uri)** — 支持通过 URI 连接字符串连接（`postgresql://user:pass@host:port/db`）
 - **hybrid_search** — SDK 层多路向量召回 + RRF/WeightedRRF/WeightedRanker 重排序（pymilvus 兼容 API）
@@ -558,7 +569,7 @@ pyvastbase/
 │   ├── constants.py       # IndexType, DistanceType, 版本常量, 算子映射
 │   ├── connections.py     # ConnectionConfig, VastbaseConnection (含版本缓存)
 │   ├── exceptions.py      # 19 个异常类
-│   ├── mutation_result.py # MutationResult, MutationResultWrapper
+│   ├── mutation_result.py # MutationResult（含 MutationResultWrapper 废弃别名）
 │   └── schema.py          # FieldSchema, CollectionSchema, DataType
 ├── collection.py          # Collection 类，完整的 CRUD、搜索、索引操作
 ├── utility.py             # 50+ 工具函数：用户/数据库/权限, flush/compact, 3.0.9+特性
@@ -569,7 +580,7 @@ pyvastbase/
 ├── utils/                 # SQL 生成, 向量/距离/过滤/结果工具
 ├── orm/                   # Entity/Model ORM 层 (Django 风格装饰器)
 ├── async_impl/            # AsyncCollection 等异步对应实现
-├── tests/                 # 1100+ 测试覆盖所有模块
+├── tests/                 # 1700+ 测试覆盖所有模块
 └── docs/
     ├── api-reference.md   # 完整 API 参考（英文）
     └── api-reference_zh.md # 完整 API 参考（简体中文）
@@ -579,7 +590,7 @@ pyvastbase/
 
 - Python >= 3.9
 - psycopg[binary] >= 3.2
-- Vastbase >= 3.0.8（新向量类型和特性需要 3.0.9+）
+- Vastbase V3 / VexDB Enterprise Edition / Vastbase G100 V2.2（新向量类型和特性需要 3.0.9+）
 
 ## License
 

{pyvastbase-0.2.6 → pyvastbase-0.2.9}/README.md

@@ -1,6 +1,6 @@
 # pyvastbase
 
-Python SDK for Vastbase V3 — 对标 PyMilvus 接口风格，面向 Vastbase 向量引擎。支持 Vastbase 3.0.8+，对 3.0.9+ 新特性自动版本检测与功能门控。
+Python SDK for Vastbase 向量引擎 — 对标 PyMilvus 接口风格。支持 Vastbase V3 / VexDB Enterprise Edition / Vastbase G100 V2.2，自动识别产品线并映射版本，对 3.0.9+ 新特性自动版本检测与功能门控。
 
 ## 安装
 
@@ -34,7 +34,10 @@ results = client.search("my_vectors", data=[0.15] * 128, limit=5)
 db_info = client.describe_database("vastbase")
 print(db_info)  # {'name': 'vastbase', 'table_count': 5, ...}
 
-results = client.hybrid_search("my_vectors", data=[0.15] * 128, filter="price < 1000", limit=20)
+# 多路向量召回 + 重排序（pymilvus 兼容）
+from pyvastbase import AnnSearchRequest, RRFRanker
+req = AnnSearchRequest(data=[0.15] * 128, anns_field="embedding", limit=20)
+results = client.hybrid_search("my_vectors", reqs=[req], ranker=RRFRanker(), limit=20)
 ```
 
 ### 方式二：传统 Collection 风格
@@ -114,19 +117,23 @@ col.insert([{
 
 ## 版本检测与自动门控
 
-SDK 通过 `SELECT vb_version()` 自动检测已连接的 Vastbase 版本，并对 3.0.9+ 特性进行功能门控。版本信息**按连接缓存**——仅查询一次，后续所有检查复用缓存结果。
+SDK 通过 `SELECT vb_version()` 自动检测已连接的产品及版本，并对 3.0.9+ 特性进行功能门控。支持三种产品线，自动映射到统一的 V3 等效版本号。版本信息**按连接缓存**——仅查询一次，后续所有检查复用缓存结果。
 
-### 双重校验：Build + Patch（来自 vb_version()）
+### 多产品支持
 
-Vastbase 通过 Build 号和 Patch 级别共同标识版本：
+SDK 根据 `vb_version()` 输出中的 `product name:` 行自动识别产品，并应用对应的版本映射：
 
-```
-vb_version() 输出:
-  version:V3.0 (Build 9)    -> build = 9
-  patch:1                   -> patch_level = 1
-```
+| 产品 | product name 标识 | 版本格式 | 示例 |
+|------|-------------------|----------|------|
+| Vastbase V3 | 默认 / Vastbase V100 | `V<M>.<m> (Build <B>) + patch:<P>` | `V3.0 (Build 9) + patch:1` |
+| VexDB Enterprise Edition | VexDB Enterprise Edition | `V<M>.<m>.<B>.<P>` 四段式 | `V3.0.0.3` |
+| Vastbase G100 V2.2 | Vastbase G100 | `V<M>.<m> (Build <B>) + patch:<P>` | `V2.2 (Build 19) + patch:6` |
+
+所有产品线的版本号均映射为 V3 等效 `(major, minor, build, patch_level)` 元组，功能门控统一使用映射后的值。
+
+### 双重校验：Build + Patch（来自 vb_version()）
 
-功能门控**同时检查**两个条件：`build >= 9 AND patch_level >= 1`。
+功能门控**同时检查**两个条件：`build >= required_build AND patch_level >= required_patch`。
 
 ```python
 from pyvastbase import get_vb_version, check_vb_version
@@ -134,15 +141,16 @@ from pyvastbase import get_vb_version, check_vb_version
 ver = get_vb_version()
 print(ver["major"])              # 3
 print(ver["minor"])              # 0
-print(ver["build"])              # 9  (来自 version:V3.0 (Build 9))
-print(ver["patch_level"])        # 1  (来自 patch:1)
+print(ver["build"])              # 9
+print(ver["patch_level"])        # 1
+print(ver["product_name"])       # "VexDB Enterprise Edition"
+print(ver["commit"])             # "31338"
 print(ver["has_sparsevector"])   # True (build>=9 AND patch_level>=1)
 print(ver["has_int8vector"])     # True
 
-# 手动版本检查 (major, minor, build, patch_level)
-check_vb_version((3, 0, 9, 1))   # True — build 9 >= 9, patch 1 >= 1
+# 手动版本检查 (major, minor, build, patch_level) — 使用映射后的 V3 等效版本
+check_vb_version((3, 0, 9, 1))   # True — 所有产品线统一检查
 check_vb_version((3, 0, 9, 2))   # False — patch 1 < 2
-check_vb_version((3, 0, 8, 1))   # True — 服务器版本高于最低要求
 ```
 
 所有 3.0.9+ 操作在执行前会**自动校验**服务器版本。若服务器版本过低，会返回具体的错误信息，明确指出哪个条件未满足。
@@ -195,12 +203,12 @@ results = bm25_search_highlight(
 # 返回: ['<b>向量</b>数据库是AI应用的核心', ...]
 ```
 
-## 混合搜索
+## 混合 ANN 搜索（hybrid_ann_search）
 
-将向量相似度与标量字段过滤结合，实现灵活的复合查询：
+Vastbase 原生单向量相似度 + 标量字段过滤（HybridANN 索引），实现灵活的复合查询：
 
 ```python
-results = col.hybrid_search(
+results = col.hybrid_ann_search(
     data=[0.1] * 128,
     filter={
         "$and": [
@@ -230,7 +238,7 @@ for buf in bulkbuffer_inspect():
 
 ## MutationResult
 
-所有变更操作返回 `MutationResultWrapper`，同时支持向后兼容的列表访问和完整的 `MutationResult` 接口：
+所有变更操作返回 `MutationResult`，支持列表访问和结构化字段（`MutationResultWrapper` 为废弃别名，访问会触发 `DeprecationWarning`，但仍可用）：
 
 ```python
 result = col.insert([{"id": 1, "embedding": [0.1] * 128, "text": "hello"}])
@@ -346,7 +354,7 @@ except ConnectionError:
 | [ORM](docs/api-reference_zh.md#orm) | Entity, Model, Field, VectorField |
 | [Exceptions](docs/api-reference_zh.md#exceptions) | VastbaseException 继承层次 |
 | [Async API](docs/api-reference_zh.md#async-api) | AsyncCollection, AsyncConnections |
-| [MutationResult](docs/api-reference_zh.md#mutationresult) | MutationResult, MutationResultWrapper |
+| [MutationResult](docs/api-reference_zh.md#mutationresult) | MutationResult（MutationResultWrapper 为废弃别名） |
 
 ## 快速 API 参考
 
@@ -400,12 +408,13 @@ col.create()
 col.drop()
 col.exists()
 col.truncate()
-col.insert(data, normalize_vectors=False)          # -> MutationResultWrapper
+col.insert(data, normalize_vectors=False)          # -> MutationResult
 col.batch_insert(data, batch_size=100)
 col.delete(expr="id > 10") | delete(pks=[1, 2, 3])
 col.upsert(data)
 col.search(data, anns_field, param, limit, expr, output_fields)
-col.hybrid_search(data, anns_field, param, limit, filter, output_fields)
+col.hybrid_search(reqs, rerank, limit, output_fields)
+col.hybrid_ann_search(data, anns_field, param, limit, filter, output_fields)
 col.query(expr="id < 100", limit=10, offset=0, batch_size=None)
 col.get(ids=[1, 2, 3])
 col.num_entities / col.is_empty
@@ -457,7 +466,7 @@ get_config()  # -> {"default_connection": "default", "timeout": 30.0, ...}
 以下功能已与 pymilvus API 对齐：
 
 - **DataType IntEnum** — 所有标量和向量类型使用 IntEnum，与 pymilvus 枚举值兼容
-- **MutationResult** — `insert`/`upsert`/`delete` 返回 `MutationResultWrapper`，同时支持列表访问和结构化字段（`insert_count`, `delete_count`, `primary_keys`）
+- **MutationResult** — `insert`/`upsert`/`delete` 返回 `MutationResult`，支持列表访问和结构化字段（`insert_count`, `delete_count`, `primary_keys`）；`MutationResultWrapper` 为废弃别名
 - **SearchResult** — 搜索结果结构与 pymilvus 一致，支持 `result.id`, `result.distance`, `result.data`
 - **connect(uri)** — 支持通过 URI 连接字符串连接（`postgresql://user:pass@host:port/db`）
 - **hybrid_search** — SDK 层多路向量召回 + RRF/WeightedRRF/WeightedRanker 重排序（pymilvus 兼容 API）
@@ -522,7 +531,7 @@ pyvastbase/
 │   ├── constants.py       # IndexType, DistanceType, 版本常量, 算子映射
 │   ├── connections.py     # ConnectionConfig, VastbaseConnection (含版本缓存)
 │   ├── exceptions.py      # 19 个异常类
-│   ├── mutation_result.py # MutationResult, MutationResultWrapper
+│   ├── mutation_result.py # MutationResult（含 MutationResultWrapper 废弃别名）
 │   └── schema.py          # FieldSchema, CollectionSchema, DataType
 ├── collection.py          # Collection 类，完整的 CRUD、搜索、索引操作
 ├── utility.py             # 50+ 工具函数：用户/数据库/权限, flush/compact, 3.0.9+特性
@@ -533,7 +542,7 @@ pyvastbase/
 ├── utils/                 # SQL 生成, 向量/距离/过滤/结果工具
 ├── orm/                   # Entity/Model ORM 层 (Django 风格装饰器)
 ├── async_impl/            # AsyncCollection 等异步对应实现
-├── tests/                 # 1100+ 测试覆盖所有模块
+├── tests/                 # 1700+ 测试覆盖所有模块
 └── docs/
     ├── api-reference.md   # 完整 API 参考（英文）
     └── api-reference_zh.md # 完整 API 参考（简体中文）
@@ -543,7 +552,7 @@ pyvastbase/
 
 - Python >= 3.9
 - psycopg[binary] >= 3.2
-- Vastbase >= 3.0.8（新向量类型和特性需要 3.0.9+）
+- Vastbase V3 / VexDB Enterprise Edition / Vastbase G100 V2.2（新向量类型和特性需要 3.0.9+）
 
 ## License
 

{pyvastbase-0.2.6 → pyvastbase-0.2.9}/README_en.md

@@ -1,6 +1,6 @@
 # pyvastbase
 
-Python SDK for Vastbase V3 — a PyMilvus-style API for Vastbase's vector engine. Supports Vastbase 3.0.8+ with automatic version detection and feature gating for 3.0.9+ features.
+Python SDK for Vastbase vector engine — a PyMilvus-style API. Supports Vastbase V3 / VexDB Enterprise Edition / Vastbase G100 V2.2 with automatic product detection, version mapping, and feature gating for 3.0.9+ features.
 
 ## Installation
 
@@ -30,7 +30,10 @@ results = client.search("my_vectors", data=[0.15] * 128, limit=5)
 db_info = client.describe_database("vastbase")
 print(db_info)  # {'name': 'vastbase', 'table_count': 5, ...}
 
-results = client.hybrid_search("my_vectors", data=[0.15] * 128, filter="price < 1000", limit=20)
+# Multi-way vector recall + reranking (pymilvus-compatible)
+from pyvastbase import AnnSearchRequest, RRFRanker
+req = AnnSearchRequest(data=[0.15] * 128, anns_field="embedding", limit=20)
+results = client.hybrid_search("my_vectors", reqs=[req], ranker=RRFRanker(), limit=20)
 ```
 
 ### Traditional Collection-based
@@ -110,19 +113,21 @@ col.insert([{
 
 ## Version Detection & Auto-Gating
 
-The SDK automatically detects the connected Vastbase version via `SELECT vb_version()` and gates 3.0.9+ features. The version is **cached per connection** — only one query, reused for all subsequent checks.
+The SDK automatically detects the connected product and version via `SELECT vb_version()`. Three product lines are recognized through the `product name:` line, with versions mapped to canonical V3-equivalent `(major, minor, build, patch_level)` tuples. The version is **cached per connection** — only one query, reused for all subsequent checks.
 
-### Dual-Check: Build + Patch from vb_version()
+### Multi-Product Support
 
-Vastbase identifies versions with both a Build number and a Patch level:
+| Product | product name | Version Format | Example |
+|---------|-------------|----------------|---------|
+| Vastbase V3 | default / Vastbase V100 | `V<M>.<m> (Build <B>) + patch:<P>` | `V3.0 (Build 9) + patch:1` |
+| VexDB Enterprise Edition | VexDB Enterprise Edition | `V<M>.<m>.<B>.<P>` 4-segment | `V3.0.0.3` |
+| Vastbase G100 V2.2 | Vastbase G100 | `V<M>.<m> (Build <B>) + patch:<P>` | `V2.2 (Build 19) + patch:6` |
 
-```
-vb_version() output:
-  version:V3.0 (Build 9)    -> build = 9
-  patch:1                   -> patch_level = 1
-```
+All products are mapped to canonical V3-equivalent versions for unified feature gating.
+
+### Dual-Check: Build + Patch
 
-Feature gating checks **both** conditions: `build >= 9 AND patch_level >= 1`.
+Feature gating checks **both** conditions: `build >= required_build AND patch_level >= required_patch`.
 
 ```python
 from pyvastbase import get_vb_version, check_vb_version
@@ -130,15 +135,16 @@ from pyvastbase import get_vb_version, check_vb_version
 ver = get_vb_version()
 print(ver["major"])              # 3
 print(ver["minor"])              # 0
-print(ver["build"])              # 9  (from version:V3.0 (Build 9))
-print(ver["patch_level"])        # 1  (from patch:1)
+print(ver["build"])              # 9
+print(ver["patch_level"])        # 1
+print(ver["product_name"])       # "VexDB Enterprise Edition"
+print(ver["commit"])             # "31338"
 print(ver["has_sparsevector"])   # True (build>=9 AND patch_level>=1)
 print(ver["has_int8vector"])     # True
 
-# Manual version check (major, minor, build, patch_level)
-check_vb_version((3, 0, 9, 1))   # True — build 9 >= 9, patch 1 >= 1
+# Manual version check (major, minor, build, patch_level) — uses canonical V3 values
+check_vb_version((3, 0, 9, 1))   # True — works across all product lines
 check_vb_version((3, 0, 9, 2))   # False — patch 1 < 2
-check_vb_version((3, 0, 8, 1))   # True — server exceeds minimum
 ```
 
 All 3.0.9+ operations automatically validate the server version before executing. If the server is too old, specific error messages indicate which requirement failed.
@@ -191,12 +197,12 @@ results = bm25_search_highlight(
 # Returns: ['<b>向量</b>数据库是AI应用的核心', ...]
 ```
 
-## Hybrid Search
+## Hybrid ANN Search (hybrid_ann_search)
 
-Combine vector similarity with scalar field filtering for flexible queries:
+Vastbase-native single-vector similarity + scalar field filtering (HybridANN index) for flexible queries:
 
 ```python
-results = col.hybrid_search(
+results = col.hybrid_ann_search(
     data=[0.1] * 128,
     filter={
         "$and": [
@@ -226,7 +232,7 @@ for buf in bulkbuffer_inspect():
 
 ## MutationResult
 
-All mutation operations return `MutationResultWrapper` which provides both backward-compatible list access and the full `MutationResult` interface:
+All mutation operations return a `MutationResult` providing both list access and structured fields (`MutationResultWrapper` is a deprecated alias that still works but emits a `DeprecationWarning`):
 
 ```python
 result = col.insert([{"id": 1, "embedding": [0.1] * 128, "text": "hello"}])
@@ -342,7 +348,7 @@ Full API reference: [docs/api-reference.md](docs/api-reference.md)
 | [ORM](docs/api-reference.md#orm) | Entity, Model, Field, VectorField |
 | [Exceptions](docs/api-reference.md#exceptions) | VastbaseException hierarchy |
 | [Async API](docs/api-reference.md#async-api) | AsyncCollection, AsyncConnections |
-| [MutationResult](docs/api-reference.md#mutationresult) | MutationResult, MutationResultWrapper |
+| [MutationResult](docs/api-reference.md#mutationresult) | MutationResult (MutationResultWrapper is a deprecated alias) |
 
 ## Quick API Reference
 
@@ -396,12 +402,13 @@ col.create()
 col.drop()
 col.exists()
 col.truncate()
-col.insert(data, normalize_vectors=False)          # -> MutationResultWrapper
+col.insert(data, normalize_vectors=False)          # -> MutationResult
 col.batch_insert(data, batch_size=100)
 col.delete(expr="id > 10") | delete(pks=[1, 2, 3])
 col.upsert(data)
 col.search(data, anns_field, param, limit, expr, output_fields)
-col.hybrid_search(data, anns_field, param, limit, filter, output_fields)
+col.hybrid_search(reqs, rerank, limit, output_fields)
+col.hybrid_ann_search(data, anns_field, param, limit, filter, output_fields)
 col.query(expr="id < 100", limit=10, offset=0, batch_size=None)
 col.get(ids=[1, 2, 3])
 col.num_entities / col.is_empty
@@ -451,7 +458,7 @@ get_config()  # -> {"default_connection": "default", "timeout": 30.0, ...}
 ### Aligned (matches pymilvus API)
 
 - **DataType IntEnum** -- Numeric values match pymilvus (e.g. `FLOAT_VECTOR=16`, `INT64=6`); PG-only types use values >= 100
-- **MutationResult** -- Same `.insert_count`, `.delete_count`, `.upsert_count`, `.primary_keys` fields; `MutationResultWrapper` adds backward-compatible list access
+- **MutationResult** -- Same `.insert_count`, `.delete_count`, `.upsert_count`, `.primary_keys` fields with backward-compatible list access (`MutationResultWrapper` is a deprecated alias)
 - **SearchResult** -- Same `.id`, `.distance`, `.entity` attribute pattern on result hits
 - **connect(uri)** -- Accepts PostgreSQL connection URI strings, same parameter pattern as pymilvus `connect()`
 - **hybrid_search** -- SDK-layer multi-way vector recall with RRF/WeightedRRF/WeightedRanker reranking (pymilvus-compatible API; N SQL round trips vs Milvus single gRPC call)
@@ -520,7 +527,7 @@ pyvastbase/
 │   ├── constants.py       # IndexType, DistanceType, version constants, operator mapping
 │   ├── connections.py     # ConnectionConfig, VastbaseConnection (with version cache)
 │   ├── exceptions.py      # 19 exception classes
-│   ├── mutation_result.py # MutationResult, MutationResultWrapper
+│   ├── mutation_result.py # MutationResult (incl. MutationResultWrapper deprecated alias)
 │   └── schema.py          # FieldSchema, CollectionSchema, DataType
 ├── collection.py          # Collection class with full CRUD, search, index ops
 ├── utility.py             # 50+ utility functions: user/DB/privilege, flush/compact, 3.0.9+
@@ -531,7 +538,7 @@ pyvastbase/
 ├── utils/                 # SQL generation, vector/distance/filter/result utilities
 ├── orm/                   # Entity/Model ORM layer (Django-style decorators)
 ├── async_impl/            # AsyncCollection, async counterparts
-├── tests/                 # 1100+ tests (unit + integration)
+├── tests/                 # 1700+ tests (unit + integration)
 └── docs/
     └── api-reference.md   # Full API reference in PyMilvus format
 ```
@@ -539,8 +546,8 @@ pyvastbase/
 ## Requirements
 
 - Python >= 3.9
-- psycopg[binary] >= 3.1
-- Vastbase >= 3.0.8 (3.0.9+ for new vector types and features)
+- psycopg[binary] >= 3.2
+- Vastbase V3 / VexDB Enterprise Edition / Vastbase G100 V2.2 (3.0.9+ for new vector types and features)
 
 ## License