Metadata-Version: 2.4
Name: pyvastbase
Version: 0.3.0
Summary: Python SDK for Vastbase
Author-email: zhangzhijie <zhangzj@vastdata.com.cn>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: psycopg[binary]>=3.2
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=26.5.1; python_version >= "3.10" and extra == "dev"
Requires-Dist: isort<10,>=9.0.1; python_version >= "3.10" and extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: vermin>=1.6; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: pandas>=1.5; extra == "dev"
Requires-Dist: numpy>=1.24; extra == "dev"
Provides-Extra: pool
Requires-Dist: psycopg-pool>=3.2; extra == "pool"
Provides-Extra: async
Requires-Dist: psycopg_pool>=3.2; extra == "async"
Provides-Extra: all
Requires-Dist: pytest>=7.4.0; extra == "all"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
Requires-Dist: pytest-cov>=4.1.0; extra == "all"
Requires-Dist: black>=26.5.1; python_version >= "3.10" and extra == "all"
Requires-Dist: isort<10,>=9.0.1; python_version >= "3.10" and 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"
Requires-Dist: pandas>=1.5; extra == "all"
Requires-Dist: numpy>=1.24; extra == "all"

# pyvastbase

pyvastbase 是 Vastbase 向量数据库的 Python SDK（Vastbase 为 PostgreSQL 系内核加向量扩展）。单一运行时依赖 `psycopg[binary]`；支持 Vastbase V100 V3.0 / VexDB Enterprise Edition / Vastbase G100 V2.2 三条产品线，自动识别产品与版本，并对 3.0.9+ 新特性做自动功能门控。API 姿态与 pymilvus 对齐（`MilvusClient` / `MilvusException` 等为兼容别名），同步与异步两套并行实现。

> ### ⚠️ 0.3.0 破坏性变更：client 面检索结果改为 dict-hit 协议
>
> 自 0.3.0 起，`VastbaseClient` / `MilvusClient` / `AsyncVastbaseClient` / `AsyncMilvusClient` 的
> `search` / `search_fulltext` / `hybrid_search` 返回 **`list[list[dict]]`**——每个查询向量一组，
> 每个命中为 `{"id": ..., "distance": ..., "entity": {...}}`，输出字段嵌套在 `entity` 下，与
> pymilvus `MilvusClient` 的结果协议一致。0.2.12 的属性 / 扁平访问需要迁移：
>
> | 0.2.12（属性 / 扁平访问） | 0.3.0（dict 访问） |
> |---------------------------|---------------------|
> | `hit.id` | `hit["id"]` |
> | `hit.distance` | `hit["distance"]` |
> | `hit.data.get("price")` / `hit["price"]` | `hit["entity"]["price"]` |
>
> 迁移代码可用 `isinstance(results, list)` 区分新旧协议。ORM 层 `Collection.search` /
> `Collection.hybrid_search` 仍保持自有 `SearchResult` 属性容器——转换只发生在 client 出口。
>
> 0.3.0 的其余破坏性变更：insert / upsert / search **维度严格校验**（不再零填充，维度不匹配抛
> `VectorDimensionError`）；`MutationResult` 变为 **dict 容器**（delete 结果无 `ids` 键）；
> `has_collection` 探测失败**改抛错**（`False` 仅表示不存在）；`describe_index` 未命中返回
> `None`；COSINE / IP 距离值改用 Milvus 极性语义；`WeightedRanker` 归一化公式重校准；异步
> 连接池默认收敛为 1/10；未注册连接别名抛错；错误类型面统一（写路径 `DataError` / 读与元数据
> 路径 `CollectionError`）。完整清单见 `CHANGELOG.md` 0.3.0 节；pymilvus 迁移
> 说明见 `docs/migration-from-pymilvus.md`。

## 安装

```bash
pip install pyvastbase
```

- Python ≥ 3.9
- 唯一运行时依赖：`psycopg[binary]`（≥ 3.2）
- 可选 extras：`[pool]`（psycopg-pool 连接池）、`[async]`、`[all]`

## 快速开始

### 方式一：VastbaseClient

```python
from pyvastbase import VastbaseClient

client = VastbaseClient(uri="postgresql://user:password@host:5432/vastbase")

# 不传 schema 时自动构造默认两字段（id 主键 + vector 向量列）
# 注意：维度参数名是 dimension（不是 dim）
client.create_collection("my_vectors", dimension=128)

client.insert("my_vectors", [
    {"id": 1, "vector": [0.1] * 128},
    {"id": 2, "vector": [0.2] * 128},
])

# client 面检索走 dict-hit 协议（见头部破坏性变更声明）
hits = client.search("my_vectors", data=[0.15] * 128, limit=5)
for hit in hits[0]:
    print(hit["id"], hit["distance"])

# 数据库元信息：键为 name / encoding / collate / ctype（缺库抛 CollectionError）
print(client.describe_database("vastbase"))
```

### 方式二：Collection / CollectionSchema

```python
from pyvastbase import (
    connect, Collection, CollectionSchema, FieldSchema, DataType,
)

connect(
    host="your_host",
    port=5432,
    database="vastbase",
    user="your_user",
    password="your_password",
)

# FieldSchema 一律 keyword-only：位置参数会 TypeError
schema = CollectionSchema(
    name="my_vectors",
    fields=[
        FieldSchema(name="id", dtype=DataType.INT64, is_primary_key=True),
        FieldSchema(name="embedding", dtype=DataType.FLOAT_VECTOR, dim=128),
        FieldSchema(name="text", dtype=DataType.VARCHAR, max_length=65535),
    ],
)

# 便捷 schema 工厂（参数名同样是 dimension）：
# quick = create_collection_schema(name="quick_vectors", dimension=128)

col = Collection("my_vectors", schema=schema)
col.create()

col.insert([
    {"id": 1, "embedding": [0.1] * 128, "text": "hello world"},
    {"id": 2, "embedding": [0.2] * 128, "text": "goodbye"},
])

# ORM 面检索返回 SearchResult 属性容器（与 client 面协议不同，见"检索"一节）
results = col.search(
    data=[[0.15] * 128],
    anns_field="embedding",
    limit=5,
    expr="id < 100",
)
for item in results[0]:
    print(item.id, item.distance, item.data)
```

## 数据类型

### 向量类型

| SQL 类型 | DataType | 说明 | SDK 版本门控 |
|----------|----------|------|--------------|
| `floatvector(N)` | `FLOAT_VECTOR` | 4 字节浮点稠密向量，dim 1–16384 | 无（所有版本可建） |
| `int8vector(N)` | `INT8_VECTOR` | 1 字节有符号整型向量 | ≥ 3.0.9 patch:1 |
| `halfvector(N)` | `FLOAT16_VECTOR`（别名 `HALF_VECTOR`） | 2 字节半精度 fp16 | ≥ 3.0.9 patch:1 |
| `sparsevector` | `SPARSE_FLOAT_VECTOR`（别名 `SPARSE_VECTOR`） | 稀疏浮点向量，无维度 | ≥ 3.0.9 patch:1 |
| `bit(dim)` | `BINARY_VECTOR` | 二值向量 | ≥ 3.0.9 patch:3（`binary_vector_ops` 特性门控） |
| — | `BFLOAT16_VECTOR` | **拒绝建表**（`FieldSchema` 抛 `SchemaError`，仅保留枚举位） | — |

引擎侧 floatvector 最早出现于 3.0.8 patch 3——这是引擎版本史实；SDK 对 floatvector **无任何
代码门控**，旧版本服务器是否可用以引擎文档为准。

`BINARY_VECTOR` 细节：写入接受 0/1 字符串、等长 0/1 整数列表或 bytes，读回为 0/1 字符串；度量仅
`HAMMING`（缺省）/ `JACCARD`，无 L2 / COSINE / IP 通道；二值索引仅 `graph_index` 访问方法。

```python
from pyvastbase import FieldSchema, DataType

# FieldSchema 全部参数 keyword-only（位置参数抛 TypeError）
schema.add_field(FieldSchema(name="vec", dtype=DataType.INT8_VECTOR, dim=256))
schema.add_field(FieldSchema(name="half", dtype=DataType.FLOAT16_VECTOR, dim=512))
schema.add_field(FieldSchema(name="sparse", dtype=DataType.SPARSE_FLOAT_VECTOR))  # 无维度

# 稀疏向量以 indices + values 字典写入
col.insert([{
    "id": 1,
    "sparse": {"indices": [0, 5, 100], "values": [0.5, 0.8, 0.3]},
}])
```

### 标量类型

```python
DataType.BOOL, DataType.INT8, DataType.INT16, DataType.INT32, DataType.INT64,
DataType.FLOAT, DataType.DOUBLE, DataType.VARCHAR, DataType.ARRAY,
DataType.JSON, DataType.TEXT, DataType.DATE, DataType.UUID, DataType.TIMESTAMP

# 辅助判断
DataType.is_vector_type(dtype)
DataType.is_sparse_type(dtype)
DataType.is_dimensionless_type(dtype)
```

注意：`DataType` 成员**名称**与 pymilvus 一致但**数值有意不同**（如 `INT64` 为 6，pymilvus 为 5）；
跨 SDK 边界用 `DataType.to_pymilvus_value()` / `DataType.from_pymilvus_value()` 桥接，不要裸 int
比较。

## 动态字段（enable_dynamic_field）

`CollectionSchema(enable_dynamic_field=True)`（复数拼写 `enable_dynamic_fields` 为弃用别名）建表时
追加一列 `dynamic_fields jsonb` 溢写列，schema 外字段随行存取：

```python
from pyvastbase import CollectionSchema, FieldSchema, DataType

schema = CollectionSchema(
    name="docs",
    fields=[
        FieldSchema(name="id", dtype=DataType.INT64, is_primary_key=True),
        FieldSchema(name="embedding", dtype=DataType.FLOAT_VECTOR, dim=128),
    ],
    enable_dynamic_field=True,
)

col.insert([{"id": 1, "embedding": [0.1] * 128, "author": "ada", "score": 0.87}])

# 动态键可读回、可过滤（字符串 expr 与 dict filter 均可命中）
rows = col.query(expr='author == "ada"')
rows = col.query(expr="score > 0.5")
```

未开启 `enable_dynamic_field` 的集合，SDK 在客户端直接拒绝未声明键（`ParamError`，报错指向该
开关），不会把错误泄漏给引擎。

## 版本检测与功能门控

SDK 通过 `SELECT vb_version()` 自动检测产品线与版本，映射为统一的 V3 等效
`(major, minor, build, patch_level)` 元组后做门控。版本信息**按连接缓存**（只查询一次，探测失败
也缓存）。

### 多产品线支持

| 产品 | 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` |

```python
from pyvastbase import get_server_version, get_vb_version, check_vb_version

get_server_version()            # 'V3.0 (Build 9) + patch:1'（vb_version() 原串）
ver = get_vb_version()          # 解析 dict，按连接缓存
print(ver["major"], ver["build"], ver["patch_level"])
print(ver["product_name"], ver["commit"])
print(ver["has_sparsevector"])  # 特性旗标：build >= 9 且 patch_level >= 1

# 手动达标检查（用映射后的 V3 等效版本；所有产品线统一）
check_vb_version((3, 0, 9, 1))  # True
check_vb_version((3, 0, 9, 2))  # False — patch 1 < 2
```

### FEATURE_GATES 功能门控表

`core/version.py` 的 `FEATURE_GATES` 共 **5 个 key**，门控在调用点自动执行（低版本定向报错）：

| key | 最低版本 | 门控对象 |
|-----|----------|----------|
| `bm25_highlight` | (3, 0, 9, 1) | `bm25_search_highlight` |
| `vectorbuffer_inspect` | (3, 0, 9, 1) | `vectorbuffer_inspect` |
| `bulkbuffer_inspect` | (3, 0, 9, 1) | `bulkbuffer_inspect` |
| `custom_dictionary_synonyms` | (3, 0, 9, 1) | `dictionary_add_synonyms` / `dictionary_delete_synonyms` |
| `binary_vector_ops` | (3, 0, 9, 3) | `BINARY_VECTOR`（bit 列）建表前置校验 |

向量类型的版本门控另有独立注册表（`get_min_version(dtype)`）：int8vector / halfvector /
sparsevector 均为 (3, 0, 9, 1)，floatvector 无门控。

## 索引管理

```python
from pyvastbase import IndexParams

# Graph 索引（HNSW 族）
params = IndexParams.graph_index(m=16, ef_construction=64, parallel_workers=4)
col.create_index(field_name="embedding", index_params=params)

# 全文索引（BM25）——dictionary 是"词典名引用"，不是内联词典内容
ft = IndexParams.fulltext_index(dictionary="cn_tokenizer", algorithm="BM25")
col.create_index(field_name="content", index_params=ft)
```

两条重要边界：

- **`IndexParams.fulltext_index(synonyms=...)` 会抛 `ParamError`**——`synonyms` 不是合法的全文
  索引参数（响亮失败，不是静默忽略）。同义词内容的正确机制是词典级 API：`create_dictionary`
  之后用 `dictionary_add_synonyms` 写入（见"自定义词典"一节）。
- `IndexParams` 的 `auto_quantization` 旋钮**仅为兼容保留**：参数被接受但从不写入 DDL——量化由
  引擎自管（3.0.9 起 1 万行自动启用，无关闭开关），不要把它当作可控功能。

`IndexType` 共 12 个成员，可建 7 种：`GRAPH_INDEX` / `HNSW` / `IVFFLAT` / `IVFPQ` / `DISKANN` /
`HYBRID_ANN` / `FULLTEXT`；`FLAT` / `IVF_SQ8` / `IVF_SQ8H` / `ANNOY` / `RNSG` 抛
`IndexNotSupportedError`。

## 检索

### 向量检索：client 面 dict-hit，ORM 面属性容器

0.3.0 起两层结果协议不同（见头部声明），同一份数据两种访问方式：

```python
# client 面：list[list[dict]]，输出字段嵌套在 entity 下
hits = client.search("my_vectors", data=[0.15] * 128, limit=5, output_fields=["text"])
for hit in hits[0]:
    print(hit["id"], hit["distance"], hit["entity"]["text"])

# ORM 面：SearchResult 属性容器（0.2.x 行为不变）
results = col.search(data=[[0.15] * 128], anns_field="embedding", limit=5)
for item in results[0]:
    print(item.id, item.distance, item.data)
```

### hybrid_search：三路混合召回

SDK 层多路召回（Vastbase 无原生多路融合，重排发生在客户端）。每个 `AnnSearchRequest` 一路，
共支持三种路：**稠密向量路 / 稀疏向量路 / BM25 全文路**（字符串查询 + 文本字段）：

```python
from pyvastbase import AnnSearchRequest, RRFRanker

results = col.hybrid_search(
    reqs=[
        # 稠密向量路
        AnnSearchRequest(
            data=[0.1] * 128, anns_field="embedding",
            param={"metric_type": "l2"}, limit=20,
        ),
        # 稀疏向量路（dict 查询）
        AnnSearchRequest(
            data={"indices": [0, 5], "values": [0.5, 0.8]},
            anns_field="sparse_vec", param={}, limit=20,
        ),
        # BM25 全文路（字符串查询 + 文本字段）
        AnnSearchRequest(
            data="向量数据库", anns_field="content", param={}, limit=20,
        ),
    ],
    rerank=RRFRanker(),   # 也可 WeightedRRFRanker / WeightedRanker；rerank 与 ranker 等价
    limit=20,
)
for item in results[0]:
    print(item.id, item.distance)   # distance 槽为融合分数
```

`metric_type="bm25"` 会被拒——全文是一种路，不是度量。`ranker` 槽也可传 BM25 `Function` 声明
（被翻译为一路全文召回 + 默认 `RRFRanker()` 融合）。

### BM25 全文检索与高亮

```python
# ORM 面 / client 面的 search_fulltext；distance 槽为 bm25_score
results = col.search_fulltext(text_field="content", query_text="向量数据库", limit=10)
for item in results[0]:
    print(item.id, item.distance)

hits = client.search_fulltext("my_vectors", "content", "向量数据库", limit=10)
for hit in hits[0]:
    print(hit["id"], hit["distance"])
```

```python
from pyvastbase import bm25_search_highlight   # 3.0.9+ 门控（bm25_highlight）

# 直接模式：高亮单段文本的匹配片段（自定义起止标记）
bm25_search_highlight(
    "Vastbase is a vector database for AI",
    "vector database",
    start_sel="<b>", stop_sel="</b>",
)

# 表模式：对表中匹配行做高亮
bm25_search_highlight(
    query="向量", table_name="articles", text_column="content",
    dict_name="cn_tokenizer",
)
```

## 自定义词典（vexjieba）

全文索引的词典体系是独立对象：`create_dictionary` 建词典，**CREATE 期的 `userdict` /
`stopwords` / `synonyms` 选项是词典名引用而非内联内容**，内容用 `dictionary_add_*` 族写入，
`dictionary_reload` 重载生效：

```python
from pyvastbase import (
    create_dictionary, dictionary_add_userdict, dictionary_add_stopwords,
    dictionary_add_synonyms, dictionary_reload, list_dictionaries,
)

create_dictionary("my_dict")
dictionary_add_userdict("my_dict", ["向量数据库", "召回率"])
dictionary_add_stopwords("my_dict", ["的", "了"])
# 同义词：Dict[str, List[str]]；3.0.9 patch:1+ 门控（custom_dictionary_synonyms）
dictionary_add_synonyms("my_dict", {"向量数据库": ["vecdb", "vector db"]})
dictionary_reload("my_dict")          # 重载生效
print(list_dictionaries())
```

词典内容变更后，已建全文索引需 rebuild 方可生效（相关操作会给出警告）。

## 集合函数（BM25 Function 声明）

`add_collection_function` 接受 pymilvus 2.6 风格的 `Function` 声明，语义是**在目标文本字段上创建
fulltext 索引**并记录声明（`describe_collection()["functions"]` 可读回；同目标幂等）：

```python
from pyvastbase import Function, FunctionType

index_name = client.add_collection_function(
    "my_vectors",
    Function("bm25_fn", FunctionType.BM25, input_field_names="text"),
)
# 词典缺省 cn_tokenizer，可由 Function 的 params 覆写；
# alter_collection_function = 索引参数变更（改输入字段须先 drop）；
# drop_collection_function = 删除该 fulltext 索引。
```

与 Milvus 2.6 的偏差：Vastbase **没有 output 稀疏列**——BM25 在检索期经 fulltext 索引计算，不在
写入时物化稀疏字段；`output_field_names` 非 None 会被显式拒绝并说明原因。

## 混合 ANN 搜索（hybrid_ann_search）

Vastbase 原生的**单向量相似度 + 标量过滤**（HybridANN 索引，两列索引含一个标量列）——注意它不是
`hybrid_search` 那种多路召回：

```python
results = col.hybrid_ann_search(
    data=[0.1] * 128,
    anns_field="embedding",
    filter={
        "$and": [
            {"price": {"$lte": 1000}},
            {"category": {"$in": ["electronics", "books"]}},
        ]
    },
    limit=20,
)
for item in results[0]:
    print(item.id, item.distance, item.data)
```

## 集合生命周期

```python
from pyvastbase import (
    list_collections, has_collection, describe_collection,
    create_collection, drop_collection, rename_collection,
    load_collection, release_collection,
)

create_collection(name="temp", fields=[
    {"name": "id", "dtype": DataType.INT64, "is_primary_key": True},
    {"name": "vec", "dtype": DataType.FLOAT_VECTOR, "dim": 256},
])

print(has_collection("temp"))       # True（探测失败抛错；False 仅表示不存在）
info = describe_collection("temp")  # fields / auto_id / columns / indexes / row_count

load_collection("temp")     # PG 数据常驻：no-op 式成功（pymilvus 兼容语义）
release_collection("temp")
rename_collection("temp", "temp2")
drop_collection("temp2")
```

## 迭代器：同名类辨析

库里存在**多个同名的 SearchIterator / AsyncSearchIterator / QueryIterator 类**，import 来源不同
即不同类，勿混用：

| 创建入口 | 迭代器类（来源模块） | 迭代协议 |
|----------|----------------------|----------|
| `Collection.search_iterator(...)` / `VastbaseClient.search_iterator(...)` | `pyvastbase.SearchIterator`（`collection` 模块） | `__iter__` / `__next__` |
| `utility.search_iterator(...)` | `pyvastbase.utility.SearchIterator`（独立同名类） | `__iter__` / `__next__` |
| `AsyncCollection.search_iterator(...)` | `async_impl.collection.AsyncSearchIterator` | `__aiter__` / `__anext__` |
| `async_search_iterator(...)`（utility 孪生） | `async_impl.utility.AsyncSearchIterator`（同名异步类；`async_impl` 顶层导出的是它） | `__aiter__` / `__anext__` |
| `Collection.query_iterator(...)` / `col.query(batch_size=...)` | `pyvastbase.QueryIterator`（`collection` 模块） | `__iter__` / `__next__` |
| `AsyncCollection.query_iterator(...)` | `async_impl.collection.QueryIterator`（同名异步类） | `__aiter__` / `__anext__` |

```python
# 同步搜索迭代：大批量取回搜索结果
for batch in col.search_iterator(
    data=[0.1] * 128, limit=1000, batch_size=100,
):
    for item in batch:
        process(item)

# 同步查询迭代
for batch in col.query_iterator(expr="id < 10000", batch_size=1000):
    for record in batch:
        process(record)
```

搜索迭代器状态面：`iteration_token`（`"offset:<n>"` 续跑令牌）、`total_count`、`exhausted`；
查询迭代器有 `total_count` / `remaining`（仅客户端切片模式）。`next()` 是 `__next__` 的兼容
别名，`close()` 为 no-op。

## MutationResult

所有变更操作返回 `MutationResult`——一个 **dict 容器**（`isinstance(result, dict)` 为 True，键集
按操作对齐 pymilvus），同时保留类型化属性与列表访问面（`MutationResultWrapper` 为弃用别名，
访问触发 `DeprecationWarning`）：

```python
result = col.insert([{"id": 1, "embedding": [0.1] * 128}])

# dict 契约（pymilvus MilvusClient 迁移面）
result["insert_count"]      # 1
result["ids"]               # [1]

# 类型化属性 + 列表兼容面
result.insert_count         # 1
result.primary_keys         # [1]
list(result)                # [1]
len(result)                 # 1

# 键集 per-operation：delete 结果是 {delete_count, cost}，没有 ids 键
result = col.delete(expr="id >= 100")
result["delete_count"]      # 5
```

## 异步 API

每个同步模块都有 `async_impl/` 并行实现（完整实现，不是薄适配层）。主要入口：

- `AsyncCollection`——与 `Collection` 同形构造，方法面一一对应（无
  `construct_from_dataframe`、无 `alias` 属性）；`num_entities` / `is_empty` 是
  **返回协程的 property**（取值即协程：`await coll.num_entities`）
- `AsyncConnections` / `AsyncVastbaseConnection`——异步连接注册单例与连接包装
- `AsyncVastbaseClient`（= `AsyncMilvusClient`，同一类对象）——71 个 async 方法、**0 个桩**
  （未异步化的长尾方法不做 NotSupportedError 桩，直接改用 `async_impl` 模块级函数）
- `AsyncIndexBuilder` / `AsyncSearchQueryBuilder`（= `AsyncSearchBuilder`）——异步索引与搜索
  构建器
- utility 的 `async_*` 孪生函数（如 `async_list_collections` / `async_describe_collection` /
  `async_search_iterator`）

```python
import asyncio

from pyvastbase import AsyncCollection, AsyncConnections

async def main():
    await AsyncConnections.connect(
        alias="default",
        host="your_host", port=5432, database="vastbase",
        user="your_user", password="your_password",
    )

    col = AsyncCollection("my_vectors")
    await col.insert([{"id": 1, "vector": [0.1] * 128}])
    results = await col.search(data=[[0.15] * 128], limit=5)

    # num_entities / is_empty 是返回协程的 property——直接 await
    print(await col.num_entities, await col.is_empty)

asyncio.run(main())
```

```python
from pyvastbase import AsyncVastbaseClient
from pyvastbase.async_impl import async_list_collections

async def main():
    async with AsyncVastbaseClient(
        uri="postgresql://user:password@host:5432/vastbase",
    ) as client:
        await client.create_collection("docs", dimension=128)  # 返回 None
        hits = await client.search("docs", data=[0.15] * 128, limit=5)
        print(await async_list_collections())

asyncio.run(main())
```

## 用户、权限与数据库管理

```python
from pyvastbase import (
    create_user, drop_user, list_users, grant, revoke,
    create_database, drop_database, list_databases, describe_database,
)

create_user(user="reader", password="securepass")
grant(privilege="SELECT", object_type="COLLECTION", object_name="my_vectors", user="reader")
revoke(privilege="SELECT", object_type="COLLECTION", object_name="my_vectors", user="reader")
print(list_users())
drop_user(user="reader")

create_database(database="newdb")
print(list_databases())              # ['postgres', 'vastbase', 'newdb']
print(describe_database("newdb"))    # 键为 name / encoding / collate / ctype
drop_database(database="newdb")
```

权限走 PostgreSQL 原生 GRANT / REVOKE（非 Milvus privilege API）；角色 / 权限组等 Milvus 概念
见"不支持"清单。

## 异常处理

```python
from pyvastbase import (
    VastbaseConnectionError,     # 注意：裸 ConnectionError 不能从包根导入
    CollectionNotExistsError,
    VectorDimensionError,
    VastbaseException,
)

try:
    col.search(data=[[0.1] * 128], limit=5)
except CollectionNotExistsError as e:
    print(f"集合不存在: {e.collection_name}")
except VectorDimensionError as e:
    print(f"维度不匹配: 期望 {e.expected}, 实际 {e.actual}")
except VastbaseConnectionError:
    print("数据库连接失败")
except VastbaseException:
    print("其他 SDK 错误")
```

要点：

- 全部 20 个异常类（1 基类 + 19 具体子类）都根在 **`VastbaseException`**；`MilvusException` 是
  它的 identity 别名——`except MilvusException` 两个名字都能捕获
- 包根**刻意不导出裸 `ConnectionError`**（避免遮蔽 Python 内置同名异常），SDK 连接错误的导入名
  是 `VastbaseConnectionError`
- 领域异常携带专属属性：`VectorDimensionError.expected/.actual`、
  `CollectionNotExistsError.collection_name`、`NotSupportedError.feature/.reason` 等
- bool 型存在性探测（`has_collection` / `exists` / `has_index`）**失败必抛错**——`False` 只表示
  "不存在"

## pymilvus 兼容性

### 已对齐

- **`VastbaseClient` / `MilvusClient` 为同一类对象**（`AsyncVastbaseClient` / `AsyncMilvusClient`
  同理）；client 面共 128 个方法 = 76 已实现 + 52 个 `NotSupportedError` 桩
- **`DataType`**——成员名与 pymilvus 一致、数值有意不同，经 `to_pymilvus_value()` /
  `from_pymilvus_value()` 桥接
- **检索结果协议**——client 面 dict-hit（`hit["entity"]["field"]`，0.3.0 起）；ORM 面
  `SearchResult` 属性容器（`.id` / `.distance` / `.data`）
- **`MutationResult`**——dict 容器 + 列表兼容面，键集按操作对齐 pymilvus
- **距离值极性**——COSINE 返回相似度（1−d，越大越好）、IP 返回正内积，对齐 Milvus 值语义
- **`round_decimal`**——search / hybrid_search 的距离舍入参数实际生效（>0 舍入，极性换算后应用）
- **双名别名**——`expr` / `filter`、`pks` / `ids`、`param` / `search_params`、`rerank` / `ranker`
  （同传双名抛 `ParamError`）
- **`connect(uri)`**——`postgresql://` / `vastbase://` URI 连接契约，与 host/port 形式语义等价；
  Milvus 风格 `http://` 抛 `ParamError`
- **`hybrid_search`**——`AnnSearchRequest` + `RRFRanker` / `WeightedRRFRanker` / `WeightedRanker`
  的 pymilvus 兼容 API
- **弃用别名**——`get_entity_by_id`（用 `get`）、`MutationResultWrapper`（用 `MutationResult`）
- **异常别名族**——`MilvusException` / `CollectionNotExistException` / `ConnectError` 等
  pymilvus 名 identity 映射，`except` 直接兼容
- **`describe_index`**——未命中返回 `None`（对齐 pymilvus 2.6 miss 契约）

### 扩展功能（pymilvus 没有）

- `normalize_vectors`——insert / search 前自动向量归一化
- `delete(pks=[...])` 按主键列表删除；`query` 原生 `limit` / `offset` 分页
- `hybrid_ann_search`——Vastbase 原生 HybridANN 单向量 + 标量过滤
- `bm25_search_highlight`——BM25 高亮（3.0.9+ 门控）
- 自定义词典（vexjieba）12 函数族——userdict / stopwords / synonyms 内容管理
- `vectorbuffer_inspect` / `bulkbuffer_inspect`——缓冲区巡检（3.0.9+ 门控）
- PG 原生向量类型：`int8vector` / `halfvector` / `sparsevector` / `bit` 二值向量
- `vb_version()` Build + patch 双校验门控，三条产品线自动映射

### 不支持（显式拒绝）

- **Milvus 分区体系**（partition 家族 7 方法），以及**角色 / 权限组 / 资源组 / 副本 / 快照 / 段 /
  Milvus compaction / bulk_insert / 文件资源 / analyzer / alter_database** 等 15 个家族共 52 个
  client 方法——调用即抛 `NotSupportedError(feature, reason)`，从不静默 no-op
- **`token` 鉴权**——传入即抛 `ParamError`（Vastbase 用 `user` / `password`）
- **索引类型** `FLAT` / `IVF_SQ8` / `IVF_SQ8H` / `ANNOY` / `RNSG`——抛 `IndexNotSupportedError`
- **`BFLOAT16_VECTOR` 建表**——`FieldSchema` 直接抛 `SchemaError`
- **`IndexParams.fulltext_index(synonyms=...)`**——抛 `ParamError`（同义词走词典 API）

## 架构

```
pyvastbase/
├── core/                  # 核心类型：schema / exceptions / connections / version / search_result
├── collection.py          # 同步 Collection（CRUD、检索、索引、分页迭代器）
├── client.py              # VastbaseClient = MilvusClient（高级入口：76 实现 + 52 桩）
├── utility.py             # 89 个模块级工具函数（连接 / 服务器 / 用户 / 数据库 / 词典 / flush）
├── index/                 # IndexParams / IndexBuilder
├── search/                # SearchParams / SearchQueryBuilder / FulltextSearchBuilder / Rankers
├── operations/            # 纯 SQL 生成层 + 驱动无关计划层（sync / async 共用）
├── executor/              # 数据库执行缝（唯一 SQL 出口）
├── orm/                   # Entity / Model 装饰器 ORM
├── async_impl/            # 异步并行实现（collection / client / connections / utility / builders）
└── tests/                 # 测试套件
```

## 环境要求

- Python ≥ 3.9
- psycopg[binary] ≥ 3.2（唯一运行时依赖；连接池另装 `[pool]` extra）
- Vastbase V100 V3.0 / VexDB Enterprise Edition / Vastbase G100 V2.2（新向量类型与门控特性需
  3.0.9 对应 patch 级别，见 FEATURE_GATES 表）

## 文档

以下文档随源码分发（sdist）附带，路径相同。PyPI 页面不解析仓库内相对链接，故此处列为路径：

- API 参考（简体中文）：`docs/api-reference_zh.md`
- API reference (English): `docs/api-reference.md`
- pymilvus 迁移指南：`docs/migration-from-pymilvus.md`
- 变更日志：`CHANGELOG.md`
- 0.3.0 发布说明：`docs/release-notes/0.3.0.md`

## License

MIT
