pyvastbase 0.2.6__tar.gz → 0.2.8__tar.gz

{pyvastbase-0.2.6 → pyvastbase-0.2.8}/CLAUDE.md

@@ -16,6 +16,10 @@ pyvastbase is a Python SDK for Vastbase V3 vector database — a PyMilvus-style
 # Install dev dependencies
 pip install -e ".[dev]"
 
+# Install with connection pool / async extras
+pip install -e ".[pool]"      # psycopg-pool only
+pip install -e ".[all]"       # dev + pool
+
 # Run all tests (unit; integration skipped without VASTBASE_HOST)
 pytest
 
@@ -36,8 +40,21 @@ pytest --cov=pyvastbase --cov-report=term-missing
 black . --line-length 100
 isort . --profile black
 
-# Type check
-mypy .
+# Type check (advisory — NOT in the release gate; see ADR 0002)
+make typecheck
+```
+
+### Makefile release workflow
+
+```bash
+make check-fast     # black + isort + vermin --target=3.9- (static version scan)
+make check          # check-fast + pytest (mypy demoted — see typecheck)
+make check-versions # uv 3.9/3.10/3.11/3.12: import smoke + pytest (release gate)
+make typecheck      # advisory mypy (NOT in release chain; ~140 real errors, see ADR 0002)
+make build          # clean + python -m build
+make smoke-test     # install from testpypi into temp venv, import smoke check
+make release-test   # clean -> check -> check-versions -> build -> twine check -> upload testpypi
+make release        # same flow -> upload pypi
 ```
 
 ## Architecture
@@ -64,6 +81,7 @@ Two-layer design — every module has a synchronous implementation and a paralle
 - [client.py](client.py) — `VastbaseClient` (aliased as `MilvusClient`): pymilvus-compatible high-level entry point. 40+ implemented methods delegating to Collection/utility, plus ~30 NotSupportedError stubs for PG-incompatible features (partition, role, replica, etc.). New pymilvus compat methods: `hybrid_search`, `query_iterator`, `search_iterator`, `describe_index`, `describe_database`, `describe_user`, `update_password`, `list_aliases`, `describe_alias`, `alter_index_properties`, `drop_index_properties`, `alter_collection_properties`, `drop_collection_properties`, `add_collection_field`, `flush_all`, `get_flush_all_state`
 - [operations/](operations/) — Pure SQL generation layer used by both sync and async paths. Each function returns `(sql, params)` tuple. Modules: admin (user/privilege/database SQL), ddl (drop/truncate/refresh/alter_table/add_column), index (drop/list/get/describe/alter_index), insert, delete, query, result, schema_reflect, search_result
 - [orm/](orm/) — Django-style ORM: `Entity` base class, `Model` decorator, `Field`/`VectorField` descriptors, field validators. Generates `CollectionSchema` from decorated classes.
+- [executor/](executor/) — **Sole seam to the database.** All SQL execution crosses the `Executor` interface, never `VastbaseConnection` directly. Implementations: `SyncExecutor` / `AsyncExecutor` (psycopg 3, return `list[dict]`), `FakeExecutor` / `FakeAsyncExecutor` (in-memory test doubles). `SyncCollection` / `AsyncCollection` are thin adapters (~50 lines) that supply connection + Executor and delegate business logic to `CollectionCore` (sync-only). AsyncCollection bypasses Core for properties like `num_entities` / `index_params_async` — calls `_executor.execute()` directly. Utility functions access an Executor via `@with_executor` / `@async_with_executor` decorators. Only `create_database` / `drop_database` bypass the seam (need autocommit toggle — decorator passes both `_executor` and `_conn`). `VastbaseConnection.execute/fetch_one/fetch_all` are private (`_execute` / `_fetch_one` / `_fetch_all`); callers must cross the Executor seam.
 
 ### Supporting modules
 
@@ -71,9 +89,16 @@ Two-layer design — every module has a synchronous implementation and a paralle
 - [search/search_builder.py](search/search_builder.py) — `SearchParams`, `SearchResult`/`SearchResults`, `SearchQueryBuilder`, `FulltextSearchBuilder`
 - [utils/](utils/) — Internal SQL generation, vector serialization, distance calculation, filter expression building, result parsing
 
-### Version detection & feature gating
+### hybrid_search vs hybrid_ann_search
+
+Two distinct `hybrid_*` methods, easy to confuse:
+
+- `hybrid_search` — **SDK-layer multi-way recall**. Issues multiple independent ANN SQL queries (one per vector field), merges via reranker (`RRFRanker`, `WeightedRRFRanker`, `WeightedRanker`). Vastbase has no native multi-way recall (no `rrf`/`fusion`/`rerank` in `pg_proc` on V3.0 Build 9), so reranking is client-side. Parallel by default (asyncio.gather / thread pool), serial optional. Returns `SearchResult` with `distance` = merged score.
+- `hybrid_ann_search` — **Vastbase-native single-vector + scalar filter**. Queries one vector field using HybridANN index with WHERE-style scalar predicates. Not multi-way recall. Confirmed distinct by DB inspection.
+
+See `docs/adr/0001-sdk-layer-multi-way-recall.md`.
 
-Vastbase exposes version via `SELECT vb_version()`, which returns both a Build number and a patch level (e.g., `version:V3.0 (Build 9)` + `patch:1`). Feature gating for 3.0.9+ features checks **both** `build >= 9 AND patch_level >= 1`. Version is cached per connection (one query, reused). New vector types (int8vector, halfvector, sparsevector), BM25 highlight, and auto-quantization all gate on this dual check. See [core/connections.py:219](core/connections.py#L219) `require_version()`.
+### Version detection & feature gating which returns product info, version, build number, patch level, and commit. Three product lines are auto-detected via the `product name:` line: Vastbase V3 (`V3.0 (Build 9) + patch:1`), VexDB Enterprise Edition (`V3.0.0.3` four-segment), and Vastbase G100 V2.2 (`V2.2 (Build 19) + patch:6`). VexDB and V2.2 versions are mapped to canonical V3-equivalent `(major, minor, build, patch_level)` tuples via lookup tables in [core/constants.py](core/constants.py). Unknown future versions default to `(99,99,99,99)` with a warning. Feature gating for 3.0.9+ features checks **both** `build >= 9 AND patch_level >= 1` against the canonical values. Version is cached per connection (one query, reused). New vector types (int8vector, halfvector, sparsevector), BM25 highlight, and auto-quantization all gate on this dual check. See `_parse_v3()`, `_parse_vexdb()`, `_parse_v2()` static methods in [core/connections.py](core/connections.py) and `require_version()`.
 
 ### Test conventions
 

{pyvastbase-0.2.6 → pyvastbase-0.2.8}/CONTEXT.md

@@ -6,7 +6,7 @@ A named set of data organized by a schema. Maps to a PostgreSQL table. Composed
 
 ## DataType
 
-An IntEnum holding the type of a field. Members carry both the Python-facing enum value and the PostgreSQL column type string via the `.pg_type` property. Example: `DataType.FLOAT_VECTOR` (value=101) maps to `floatvector`. The IntEnum design supports pymilvus-compatible `if dtype == DataType.INT64` comparisons while retaining PG type mapping for DDL generation. Aliases exist for backward compatibility (`DataType.INT64 == DataType.INT64`).
+An IntEnum holding the type of a field. Members carry a pymilvus-aligned numeric value; the PostgreSQL column type string is obtained via the `DataType.to_pg_type()` classmethod (reverse via `DataType.from_pg_type()`). Example: `DataType.FLOAT_VECTOR` (value=16) maps to `floatvector`. PG-only types extend the range at values ≥100 (`TEXT`, `DATE`, `UUID`, `TIMESTAMP`). The IntEnum design supports pymilvus-compatible `if dtype == DataType.INT64` comparisons while retaining PG type mapping for DDL generation. Backward-compatible aliases: `HALF_VECTOR == FLOAT16_VECTOR`, `SPARSE_VECTOR == SPARSE_FLOAT_VECTOR`.
 
 ## MetricType
 
@@ -77,3 +77,19 @@ High-level pymilvus `MilvusClient`-compatible entry point. Delegates all operati
 ## Connection Provider
 
 A module that supplies database connections by alias. The `ConnectionProvider` protocol defines a single method `get_connection(alias) -> VastbaseConnection`. The default implementation (`VastbaseConnections`) holds a registry of named connection configurations. Consumers (Collection, utility functions) accept an optional `_connection_provider` parameter, defaulting to the global singleton instance. VastbaseConnection is an internal implementation detail of SyncExecutor/AsyncExecutor — callers should not use `_execute/_fetch_one/_fetch_all` directly; they cross the Executor seam instead.
+
+## VexDB Enterprise Edition
+
+Vastbase enterprise variant. Uses a four-segment dotted version format (`V<major>.<minor>.<build>.<patch>`) in `vb_version()` output. Identified by `product name:VexDB Enterprise Edition`. Functionally equivalent to Vastbase V3; version mapping converts the raw version to a canonical V3 representation for feature gating.
+
+## Vastbase G100
+
+Vastbase V2.2 product line. Uses the same `vb_version()` output format as V3 (`V<major>.<minor> (Build <N>)` + `patch:<P>`) but with `V2.2` major.minor. Identified by `product name:Vastbase G100`. Version mapping converts the raw version to a canonical V3 representation for feature gating.
+
+## Product Name
+
+Identified by the `product name:` line in `vb_version()` output. Determines which version parser and mapping table to use. Known values: `VexDB Enterprise Edition`, `Vastbase G100`, and the default (Vastbase V3, when the line is absent or unrecognized).
+
+## Canonical Version
+
+The V3-equivalent `(major, minor, build, patch)` tuple used internally for all feature gating, regardless of which product the SDK connects to. Obtained by parsing `vb_version()` output according to the product's format, then applying the product's mapping table. All version constants (e.g. `VB_VERSION_3_0_9`) and `require_version()` operate on canonical versions.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyvastbase
-Version: 0.2.6
+Version: 0.2.8
 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+ 新特性自动版本检测与功能门控。
 
 ## 安装
 
@@ -150,19 +152,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 +176,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+ 操作在执行前会**自动校验**服务器版本。若服务器版本过低，会返回具体的错误信息，明确指出哪个条件未满足。
@@ -579,7 +586,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.8}/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+ 新特性自动版本检测与功能门控。
 
 ## 安装
 
@@ -114,19 +114,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 +138,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+ 操作在执行前会**自动校验**服务器版本。若服务器版本过低，会返回具体的错误信息，明确指出哪个条件未满足。
@@ -543,7 +548,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.8}/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
 
@@ -110,19 +110,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 +132,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.
@@ -540,7 +543,7 @@ pyvastbase/
 
 - Python >= 3.9
 - psycopg[binary] >= 3.1
-- Vastbase >= 3.0.8 (3.0.9+ for new vector types and features)
+- Vastbase V3 / VexDB Enterprise Edition / Vastbase G100 V2.2 (3.0.9+ for new vector types and features)
 
 ## License