pyxvector

pyxvector is a thin, dependency-light Python HTTP client for Xvector — a vector database service that speaks Milvus REST v2 style APIs. It covers collections, partitions, indexes, aliases, entities (insert / upsert / delete / get / query), vector search, hybrid search, RBAC (users / roles / privileges) and bulk-import jobs.

Supported Python versions

pyxvector supports Python 3.9 – 3.13 (any Python >= 3.9):

Dependencies

pyxvector only requires one runtime dependency:

Install from PyPI:

pip install pyxvector

Quick start

from pyxvector import XvectorClient

client = XvectorClient(uri="http://127.0.0.1:19530", token="root:Xvector")

# 1. Create a collection with an Int64 primary key and a 4-dim float vector field
client.create_collection(
    "demo",
    schema={
        "fields": [
            {"name": "id", "dataType": "Int64", "isPrimaryKey": True},
            {"name": "vector", "dataType": "FloatVector", "dim": 4},
        ]
    },
)

# 2. Create an index and load the collection into memory
client.create_index("demo", "vector", index_type="FLAT", metric_type="L2")
client.load_collection("demo")

# 3. Insert rows
client.insert("demo", [{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4]}])

# 4. Search immediately after write (refresh=True forces read-after-write consistency;
#    otherwise writes become visible within ~10s)
hits = client.search(
    "demo",
    [[0.1, 0.2, 0.3, 0.4]],
    anns_field="vector",
    limit=3,
    refresh=True,
)
print(hits)

# 5. Clean up
client.drop_collection("demo")
client.close()

XvectorClient is also a context manager:

from pyxvector import XvectorClient

with XvectorClient(uri="http://127.0.0.1:19530", token="root:Xvector") as client:
    print(client.list_collections())

Multi-database

client.using_database("my_db")   # subsequent calls target the "my_db" database

Error handling

All server-side errors are raised as XvectorApiError (a subclass of XvectorError), carrying the numeric code and message returned by the server:

from pyxvector import XvectorClient, XvectorApiError

client = XvectorClient(uri="http://127.0.0.1:19530", token="root:Xvector")
try:
    client.describe_collection("not_exist")
except XvectorApiError as e:
    print(e.code, e.message)

API overview

All methods map 1:1 to the Milvus REST v2 style endpoints (/v2/vectordb/...) exposed by Xvector.

More examples

Hybrid search with RRF rerank

client.hybrid_search(
    "demo",
    search=[
        {"data": [[0.1, 0.2, 0.3, 0.4]], "annsField": "vector", "limit": 10},
    ],
    rerank={"strategy": "rrf", "params": {"k": 60}},
    limit=5,
)

Filtered query

rows = client.query("demo", filter="id >= 1", output_fields=["id"], limit=100, refresh=True)

Bulk import from files

job = client.create_import_job("demo", files=["/data/batch1.json"], format="json")
client.wait_import_complete(job["jobId"])

Wait until a collection is loaded

client.load_collection("demo")
client.wait_loaded("demo", timeout=30)

Project links

• Project home / Xvector server: https://github.com/lxl0928/Xvector
• pyxvector source: https://github.com/lxl0928/pyxvector
• Issue tracker: https://github.com/lxl0928/Xvector/issues
• PyPI: https://pypi.org/project/pyxvector/

GitHub statistics

Live stats for the Xvector repository:

Maintainers

• Li Xiaolong (Timilong) — timilong928@gmail.com — github.com/lxl0928

License

MIT