milvus-sdk-node

@zilliz/milvus2-sdk-node is the official Node.js client for Milvus, the open-source vector database used for similarity search, retrieval-augmented generation, and recommendation systems. It exposes a single MilvusClient (or the gRPC-free HttpClient for edge runtimes like Cloudflare Workers and Vercel Edge) covering collection, index, partition, database, user/role, and alias management alongside data operations such as insert, upsert, delete, search, hybrid search, and filtered query.

The SDK wraps Milvus’s protobuf-defined gRPC service with generated TypeScript types, a connection pool built on generic-pool, retry/backoff interceptors, and optional OpenTelemetry tracing. A BulkWriter utility generates Parquet or JSON import files offline for large-scale bulk imports, and async iterators (searchIterator, queryIterator) handle pagination over large result sets without holding entire result sets in memory.

Beyond core CRUD and search, the client supports advanced Milvus capabilities directly: sparse vector and BM25 full-text search, multi-vector hybrid search with weighted or RRF reranking, partition-key based multi-tenant routing, dynamic schema fields, and resource-group based query routing for multi-replica deployments. It targets both self-hosted Milvus clusters and Zilliz Cloud, authenticating via username/password or API token.

What You Get

• A single MilvusClient class covering collection, index, partition, database, alias, user/role, and resource-group management
• Vector similarity search with metric types (L2, IP, COSINE, HAMMING, JACCARD, BM25) and index types (HNSW, IVF_*, DISKANN, sparse indexes)
• Hybrid multi-vector search with weighted or RRF reranking, plus scalar filter expressions with template parameters
• An HTTP-only client variant for serverless/edge runtimes where gRPC isn’t available (Cloudflare Workers, Vercel Edge, AWS Lambda)
• A BulkWriter for generating offline Parquet/JSON import files, plus server-side bulk import APIs
• Async iterators for paginated search and query over large result sets
• Built-in connection pooling, retry/backoff, and optional OpenTelemetry tracing

Common Use Cases

• Building retrieval-augmented generation (RAG) pipelines that store and search document embeddings
• Powering semantic and hybrid (vector + keyword) search features in Node.js backends
• Multi-tenant SaaS applications partitioning vector data by tenant using partition keys
• Bulk-loading large embedding datasets into Milvus via offline Parquet generation
• Connecting serverless functions (Vercel, Cloudflare Workers) to Milvus or Zilliz Cloud over HTTP

Under The Hood

Architecture The SDK layers a public MilvusClient (milvus/MilvusClient.ts) over a GRPCClient base (milvus/grpc/GrpcClient.ts), which itself extends a chain of mixins (User, Resource, MilvusIndex, Partition, Database, Collection, Data) that each add one domain’s methods to the client’s prototype. The gRPC client manages a generic-pool connection pool with retry, metadata, and tracing interceptors layered onto every call, and a parallel HttpClient (milvus/HttpClient.ts) with matching per-domain files under milvus/http/ reimplements the same operations over plain HTTP for environments without gRPC support. A MilvusClientSession wrapper adds cluster-scoped DQL calls without duplicating client state. Request/response shapes are generated from the Milvus .proto definitions (proto/, milvus/proto-json/), and a separate bulkwriter/ module handles offline Parquet/JSON generation independent of the live client path. Changing the base GRPCClient pooling or interceptor behavior ripples through every domain mixin since they all share one connection pool and one config object.

Tech Stack Written in TypeScript targeting Node.js 18+, using @grpc/grpc-js and @grpc/proto-loader for gRPC transport, protobufjs for protobuf (de)serialization, generic-pool for connection pooling, winston for logging, dayjs for time handling, lru-cache for client-side caching, @petamoriken/float16 for float16 vector encoding, and @opentelemetry/api for optional tracing. The @shanghaikid/parquetjs fork backs the BulkWriter’s Parquet output. Builds run through tsc plus a custom build.js post-processing step; docs are a separate Astro site under docs/.

Code Quality Testing is extensive and uses Jest (jest.config.js) with roughly 89 spec files under test/, organized by domain (test/grpc, test/http, test/bulkwriter, test/telemetry) plus shared test tooling in test/tools and test/utils. Tests exercise real Milvus server interaction patterns (collection lifecycle, sparse vectors, dynamic fields) rather than pure mocks. The codebase is fully typed, uses explicit ErrorCode-based error responses layered with thrown Errors for transport failures, and CI (.github/workflows/test.yml) runs the suite plus a separate coverage/codecov pipeline.

What Makes It Unique Unlike most vector-database clients, it ships two parallel transports — gRPC for full-featured server environments and a pure-HTTP client for edge/serverless runtimes that can’t open gRPC connections — while keeping the same request/response API surface across both. It also bundles an offline bulk-import writer capable of producing Parquet files client-side, letting large-scale imports be prepared without a live connection to the cluster, and layers a lightweight cluster-scoped session API on top of the base client for multi-cluster deployments.