vectorstores/milvus/v2/README.md
This package provides a Milvus vector store implementation using the new Milvus SDK v2 (github.com/milvus-io/milvus/client/v2).
The original vectorstores/milvus package uses the archived github.com/milvus-io/milvus-sdk-go/v2 SDK, which was deprecated by the Milvus maintainers on March 21, 2025. This new v2 package uses the actively maintained SDK at github.com/milvus-io/milvus/client/v2.
Update imports:
// Old
import "github.com/tmc/langchaingo/vectorstores/milvus"
// New
import "github.com/tmc/langchaingo/vectorstores/milvus/v2"
Update configuration (optional - v1 configs are automatically converted):
// Old
config := client.Config{Address: "localhost:19530"}
// New (recommended)
config := milvusclient.ClientConfig{Address: "localhost:19530"}
// Or keep v1 config (automatically converted)
config := client.Config{Address: "localhost:19530"} // Still works!
Update function calls:
// Old
store, err := milvus.New(ctx, config, opts...)
// New
store, err := milvusv2.New(ctx, config, opts...)
The v2 package includes compatibility adapters that allow gradual migration:
client.Config is automatically converted to v2 milvusclient.ClientConfigWithIndexV1() for v1 index typesWithSearchParametersV1() for v1 search parametersWithMetricTypeV1() for v1 metric types// During migration - mix v1 and v2 configurations
store, err := milvusv2.New(ctx,
client.Config{Address: "localhost:19530"}, // v1 config
milvusv2.WithEmbedder(embedder),
milvusv2.WithIndexV1(oldIndex), // v1 index
milvusv2.WithCollectionName("my_collection"),
)
package main
import (
"context"
"github.com/milvus-io/milvus/client/v2/entity"
"github.com/milvus-io/milvus/client/v2/index"
"github.com/milvus-io/milvus/client/v2/milvusclient"
"github.com/tmc/langchaingo/embeddings"
"github.com/tmc/langchaingo/llms/openai"
"github.com/tmc/langchaingo/schema"
"github.com/tmc/langchaingo/vectorstores/milvus/v2"
)
func main() {
ctx := context.Background()
// Create embedder
llm, err := openai.New()
if err != nil {
panic(err)
}
embedder, err := embeddings.NewEmbedder(llm)
if err != nil {
panic(err)
}
// Configure Milvus connection
config := milvusclient.ClientConfig{
Address: "localhost:19530",
}
// Create vector store
store, err := v2.New(ctx, config,
v2.WithEmbedder(embedder),
v2.WithCollectionName("my_documents"),
v2.WithIndex(index.NewAutoIndex(entity.L2)),
)
if err != nil {
panic(err)
}
// Add documents
docs := []schema.Document{
{
PageContent: "This is a document about AI",
Metadata: map[string]any{"topic": "AI", "source": "example"},
},
{
PageContent: "This document discusses machine learning",
Metadata: map[string]any{"topic": "ML", "source": "example"},
},
}
ids, err := store.AddDocuments(ctx, docs)
if err != nil {
panic(err)
}
// Search for similar documents
results, err := store.SimilaritySearch(ctx, "artificial intelligence", 5)
if err != nil {
panic(err)
}
for _, doc := range results {
fmt.Printf("Score: %.3f, Content: %s\n", doc.Score, doc.PageContent)
}
}
store, err := v2.New(ctx, config,
v2.WithEmbedder(embedder), // Required: embedder for vector generation
v2.WithCollectionName("my_collection"), // Collection name
v2.WithPartitionName("my_partition"), // Partition name (optional)
v2.WithTextField("content"), // Text field name (default: "text")
v2.WithMetaField("metadata"), // Metadata field name (default: "meta")
v2.WithVectorField("embedding"), // Vector field name (default: "vector")
v2.WithPrimaryField("id"), // Primary field name (default: "pk")
v2.WithMaxTextLength(1000), // Max text length (default: 65535)
v2.WithShards(2), // Number of shards (default: 1)
v2.WithIndex(index.NewAutoIndex(entity.L2)), // Vector index configuration
v2.WithMetricType(entity.L2), // Distance metric
v2.WithDropOld(), // Drop existing collection
v2.WithSkipFlushOnWrite(), // Skip flushing after writes
)
New(ctx, config, opts...) - Create new Milvus vector storeAddDocuments(ctx, docs, opts...) - Add documents to the storeSimilaritySearch(ctx, query, numDocs, opts...) - Search for similar documentsWithEmbedder(embedder) - Set the embedder (required)WithCollectionName(name) - Set collection nameWithPartitionName(name) - Set partition nameWithTextField(name) - Set text field nameWithMetaField(name) - Set metadata field nameWithVectorField(name) - Set vector field nameWithPrimaryField(name) - Set primary key field nameWithMaxTextLength(length) - Set maximum text lengthWithShards(num) - Set number of shardsWithSkipFlushOnWrite() - Skip flushing after writesWithIndex(index) - Set vector indexWithMetricType(metric) - Set distance metricWithEF(ef) - Set EF parameter for HNSWWithIndexV1(index) - Use v1 index typeWithSearchParametersV1(params) - Use v1 search parametersWithMetricTypeV1(metric) - Use v1 metric typeWithConsistencyLevelV1(level) - Use v1 consistency levelThe v2 package supports the new index types from the Milvus SDK v2:
// Auto index (recommended for most use cases)
index.NewAutoIndex(entity.L2)
// Flat index
index.NewFlatIndex(entity.L2)
// IVF Flat index
index.NewIvfFlatIndex(entity.L2, 1024) // metric, nlist
// HNSW index
index.NewHNSWIndex(entity.L2, 16, 200) // metric, M, efConstruction
Supported distance metrics:
entity.L2 - L2 (Euclidean) distanceentity.IP - Inner productentity.COSINE - Cosine similarityentity.HAMMING - Hamming distance (for binary vectors)entity.JACCARD - Jaccard distance (for binary vectors)The package defines specific error types:
ErrEmbedderWrongNumberVectors - Vector count mismatchErrColumnNotFound - Missing required columnErrInvalidFilters - Invalid filter formatErrInvalidOptions - Invalid configuration optionsThe package includes comprehensive tests that cover:
Run tests with:
go test ./vectorstores/milvus/v2/...