pymilvus

PyMilvus is the official Python client for Milvus, the open-source vector database used to store, index, and search dense and sparse embeddings at scale. It wraps Milvus’s gRPC API behind both a high-level MilvusClient (collections, indexes, inserts, hybrid search, and RBAC in a handful of method calls) and a lower-level ORM layer (Collection, Schema, Partition, connections) for teams that need finer control over schema design and connection lifecycle.

Beyond core CRUD and ANN search, PyMilvus ships optional extras for common production needs: a bulk_writer for high-throughput remote imports into object storage, a model extra for embedding generation, async client variants built on grpc.aio, search iterators for paging through large result sets, and support for Milvus Lite (an embedded, file-based mode for local development without a server). It is the reference client used across Milvus’s own documentation and by RAG frameworks that need a stable vector-store backend.

What You Get

• MilvusClient — a simplified, single-object API for connecting, creating collections, inserting data, and running vector/hybrid search without manually managing schemas or connections
• A full ORM layer (Collection, CollectionSchema, FieldSchema, Partition, connections) for applications that need explicit schema and index control
• Async support via AsyncMilvusClient built on grpc.aio, plus search/query iterators for paging through large result sets without loading everything into memory
• A bulk_writer extra for writing large datasets to remote object storage (S3/MinIO/Azure Blob) for high-throughput bulk import into Milvus
• Milvus Lite support — an embedded, file-backed mode for local development and testing without running a Milvus server
• Built-in retry, error classification, and reconnection handling around gRPC calls (decorators.py), plus a typed MilvusException hierarchy with retriable/non-retriable classification

Common Use Cases

• Building retrieval-augmented generation (RAG) pipelines that need a vector store for document/chunk embeddings
• Semantic search and recommendation systems over large embedding collections (text, image, or multimodal)
• Bulk-importing millions of pre-computed vectors into Milvus for offline-indexed similarity search
• Local prototyping with Milvus Lite before deploying against a full Milvus cluster or Zilliz Cloud
• Hybrid search combining dense vector similarity with sparse/keyword signals and metadata filtering in one query

Under The Hood

Architecture PyMilvus is layered around a gRPC transport: pymilvus/grpc_gen/ holds generated protobuf/gRPC stubs (milvus_pb2_grpc.py), client/grpc_handler.py (and its async twin async_grpc_handler.py) wrap those stubs with connection management, retry, and response parsing, and client/connection_manager.py pools and reuses channels. Two public surfaces sit on top: milvus_client/milvus_client.py (MilvusClient/AsyncMilvusClient, ~3,600 lines) offers a flattened, single-object API for the common case, while orm/ (Collection, Schema, Partition, connections, Index) exposes a more explicit, stateful model closer to Milvus’s own schema/index/partition concepts. A change to the core abstract.py/types.py request-response shapes ripples into both surfaces, since MilvusClient internally composes ORM/client primitives rather than duplicating them. decorators.py centralizes cross-cutting concerns — retry-on-RPC-failure, retry-on-schema-mismatch, deprecation warnings — as function decorators applied across both handler layers. Tech Stack The library targets Python 3.9–3.14, built with hatchling and versioned via setuptools_scm/vcs-versioning. Core runtime dependencies are grpcio (pinned away from several known-bad point releases), protobuf, orjson for fast JSON handling, pandas for DataFrame-based insert/query results, cachetools, and python-dotenv. Optional extras add pymilvus.model for embeddings, minio/pyarrow/ml_dtypes/azure-storage-blob for the bulk_writer path, milvus-lite for the embedded mode, and xxhash for an optional native bloom-filter implementation. Protobuf/gRPC code is generated from a milvus-proto git submodule via a make gen_proto target rather than hand-written. Code Quality The repo carries a substantial test suite (114+ files under tests/unit, tests/integration, and tests/benchmark) covering error classification, async client behavior, bulk-writer buffering, search iterators, and gRPC diagnostics, run via pytest with coverage and timeout plugins. Linting is enforced with ruff (configured in pyproject.toml) plus a pre-commit hook running make format/make lint before each commit, and CI workflows (code_checker.yml, pull_request.yml) gate merges. Exceptions are modeled as a typed hierarchy (MilvusException with an ErrorCode IntEnum and explicit is_input_error/retriable flags) rather than bare exceptions, and gRPC failures are enriched with channel connectivity state and debug strings for diagnosability. What Makes It Unique PyMilvus’s distinguishing choice is offering two coexisting API surfaces — a minimal MilvusClient and a full ORM — over the same underlying gRPC transport, letting teams start simple and drop into explicit schema/index control without switching libraries. Its retry/error-classification layer (distinguishing retriable gRPC failures, schema-mismatch retries, and rate-limit/force-deny server codes) and Milvus Lite’s embedded-mode support for local iteration without a server are less common in comparable vector-database clients, which more often ship a single thin wrapper with limited retry semantics.