Schema 与 Collection(Milvus 风格)

基础的 PistaDB API 存储 (id, label, vector) 三元组,在元数据能塞进 256 字节 label 时已经足够。当你需要在每条记录上附带多个类型化字段(章节、键、语言、行号、token 数等)时,Collection 层提供与 Milvus 兼容的 schema API。

你会得到什么

• FieldSchema / CollectionSchema / DataType——声明 INT64、VARCHAR、FLOAT、DOUBLE、BOOL、JSON、FLOAT_VECTOR 字段,is_primary / auto_id / max_length / dim 语义与 pymilvus 逐行对齐。
• Collection.insert(rows)——接收以字段名为 key 的 dict 列表;校验类型与长度;auto_id=True 时自动生成 id。
• Collection.search(query, k, output_fields=…)——返回的 hit 同时携带被投影的标量字段。
• JSON sidecar(<path>.meta.json)——向量保留在 .pst 文件中;标量字段写入同名 JSON 文件,采用稳定的线协议格式,任意语言创建的 collection 都可以在其他语言中干净打开。

Python 示例

import numpy as np
from pistadb import FieldSchema, DataType, create_collection, Metric, Index

fields = [
    FieldSchema("lc_id",      DataType.INT64,        is_primary=True, auto_id=True),
    FieldSchema("lc_section", DataType.VARCHAR,      max_length=100),
    FieldSchema("lc_key",     DataType.VARCHAR,      max_length=200),
    FieldSchema("lc_lang",    DataType.VARCHAR,      max_length=10),
    FieldSchema("lc_lineno",  DataType.INT64),
    FieldSchema("lc_tokens",  DataType.INT64),
    FieldSchema("lc_vector",  DataType.FLOAT_VECTOR, dim=1536),
]

coll = create_collection(
    "common_text", fields, "Common text search",
    metric=Metric.COSINE, index=Index.HNSW, base_dir="./db",
)

ids = coll.insert([
    {"lc_section": "common", "lc_key": "btn_ok",
     "lc_lang": "en", "lc_lineno": 12, "lc_tokens": 3,
     "lc_vector": np.random.rand(1536).astype("float32")},
])

hits = coll.search(query, limit=10, output_fields=["lc_key", "lc_lang"])[0]
for h in hits:
    print(h.id, h.distance, h["lc_key"], h["lc_lang"])

coll.flush()
coll.close()

完整可运行的 Milvus create_database() 移植版本见 examples/example_schema.py。

Schema 规则

• 有且仅有一个 is_primary 字段——必须为 INT64。
• 有且仅有一个 FLOAT_VECTOR 字段——必须有正的 dim。
• 唯一的字段名。

校验在构造期完成。Python、Go、Rust、C#、C++、Java、Kotlin、Swift、WASM 中的约束完全一致。

同一套 API,所有语言

Go、Rust、C#、C++、Java、Kotlin、Swift、WASM 都暴露相同的 FieldSchema / Collection 表面。完整的多语言代码片段见语言绑定。