tw2/examples/functionality/vector_store/mongodb

MongoDB Vector Store

This example demonstrates how to use MongoDBStore for vector storage and semantic search in AgentScope using MongoDB's Vector Search capabilities. It includes comprehensive test scenarios covering CRUD operations, metadata filtering, document chunking, and distance metrics.

Quick Start

Install agentscope first, and then the MongoDB dependency:

pip install pymongo

Important: Before running the example, you need to set the MONGODB_HOST environment variable with your MongoDB connection string:

# For local MongoDB
export MONGODB_HOST="mongodb://localhost:27017/?directConnection=true"

# For MongoDB Atlas (replace with your connection string)
# export MONGODB_HOST=${YOUR_MONGODB_HOST}

Run the example script, which showcases adding, searching, and deleting in MongoDB vector store:

python main.py

Note: The script connects to MongoDB Atlas or local MongoDB instance. Make sure you have a valid MongoDB connection string.

Prerequisites

• Confirm your MongoDB instance supports Vector Search functionality
• Valid MongoDB connection string (local or Atlas)

Usage

Initialize Store

from agentscope.rag import MongoDBStore

# For MongoDB Atlas
store = MongoDBStore(
    host="mongodb+srv://username:password@cluster.mongodb.net/",
    db_name="test_db",
    collection_name="test_collection",
    dimensions=768,              # Match your embedding model
    distance="cosine",           # cosine, euclidean, or dotProduct
)

# For local MongoDB
store = MongoDBStore(
    host="mongodb://localhost:27017/?directConnection=true",
    db_name="test_db",
    collection_name="test_collection",
    dimensions=768,
    distance="cosine",
)

# To enable filtering in search, specify filter_fields:
store = MongoDBStore(
    host="mongodb://localhost:27017/?directConnection=true",
    db_name="test_db",
    collection_name="test_collection",
    dimensions=768,
    distance="cosine",
    filter_fields=["payload.doc_id", "payload.chunk_id"],  # Fields for filtering
)

# No manual initialization needed - everything is automatic!
# Database, collection, and vector search index are created automatically
# when you first call add() or search()

Add Documents

from agentscope.rag import Document, DocMetadata
from agentscope.message import TextBlock

doc = Document(
    metadata=DocMetadata(
        content=TextBlock(type="text", text="Your document text"),
        doc_id="doc_1",
        chunk_id=0,
        total_chunks=1,
    ),
    embedding=[0.1, 0.2, ...],  # Your embedding vector
)

await store.add([doc])

Search

results = await store.search(
    query_embedding=[0.15, 0.25, ...],
    limit=5,
    score_threshold=0.9,                                # Optional
    filter={"payload.doc_id": {"$in": ["doc_1", "doc_2"]}},  # Optional filter
)
# Note:
# - To use filter, the field must be declared in filter_fields when creating store
# - MongoDB $vectorSearch filter supports: $gt, $gte, $lt, $lte,
#   $eq, $ne, $in, $nin, $exists, $not (NOT $regex)

Delete

# Delete by document IDs (no initialization needed)
await store.delete(ids=["doc_1", "doc_2"])

# Delete entire collection (use with caution)
await store.delete_collection()

# Delete entire database (use with caution)
await store.delete_database()

Distance Metrics

Metric	Description	Best For
cosine	Cosine similarity	Text embeddings (recommended)
euclidean	Euclidean distance	Spatial data
dotProduct	Inner Product	Recommendation systems

Advanced Usage

Access Underlying Client

client = store.get_client()
# Use MongoDB client for advanced operations
stats = await client[store.db_name].command("collStats", store.collection_name)

Document Metadata

• content: Text content (TextBlock)
• doc_id: Unique document identifier
• chunk_id: Chunk position (0-indexed)
• total_chunks: Total chunks in document

Vector Search Index

MongoDBStore automatically creates vector search indexes with the following configuration:

{
    "fields": [
        {
            "type": "vector",
            "path": "vector",
            "similarity": "cosine",  # or euclidean, dotProduct
            "numDimensions": 768
        }
    ]
}

Connection Examples

MongoDB Atlas

store = MongoDBStore(
    host="<YOUR_MONGO_ATLAS_CONNECTION_STRING>",
    db_name="production_db",
    collection_name="documents",
    dimensions=1536,
    distance="cosine",
)

Local MongoDB

Without Authentication

store = MongoDBStore(
    host="mongodb://localhost:27017?directConnection=true",
    db_name="local_db",
    collection_name="test_collection",
    dimensions=768,
    distance="cosine",
)

With Authentication

store = MongoDBStore(
    host="mongodb://user:pass@localhost:27017/?directConnection=true",
    db_name="test_db",
    collection_name="test_collection",
    dimensions=768,
    distance="cosine",
)

References

• MongoDB Vector Search Documentation
• MongoDB Atlas Documentation
• AgentScope RAG Tutorial