MongoDB Bridge

Installation

1

$ composer require symfony/ai-mongo-db-store

This package requires the ext-mongodb PHP extension.

Atlas Search Index Setup

The MongoDB Atlas store requires a Vector Search index on your collection. You can create it programmatically using the setup() method (see Setup below), or manually through the Atlas UI or the Atlas Administration API.

The default index definition looks like this:

1
2
3
4
5
6
7
8
9
10

{
    "fields": [
        {
            "numDimensions": 1536,
            "path": "vector",
            "similarity": "euclidean",
            "type": "vector"
        }
    ]
}

Adjust numDimensions to match your embedding model's output size, path to match your vectorFieldName, and similarity to the distance metric of your choice.

Configuration

1
2
3
4
5
6
7
8
9
10
11
12

use MongoDB\Client;
use Symfony\AI\Store\Bridge\MongoDb\Store;

$store = new Store(
    client: new Client('mongodb+srv://user:pass@cluster.mongodb.net'),
    databaseName: 'my_database',
    collectionName: 'documents',
    indexName: 'vector_index',
    vectorFieldName: 'vector',        // default: 'vector'
    bulkWrite: false,                 // default: false
    embeddingsDimension: 1536,        // default: 1536
);

1
2
3
4
5
6
7
8
9
10
11
12

# config/packages/ai.yaml
ai:
    store:
        mongodb:
            my_mongodb_store:
                database: 'my_database'
                collection: 'documents'       # optional, defaults to store name
                index_name: 'vector_index'
                vector_field: 'vector'        # optional, default: vector
                bulk_write: false             # optional, default: false
                setup_options:
                    fields: []                # optional extra index fields

1
2
3
4
5

# config/services.yaml
services:
    MongoDB\Client:
        arguments:
            - '%env(MONGODB_URL)%'

1
2

# .env.local
MONGODB_URL=mongodb+srv://user:pass@cluster.mongodb.net

Usage

1

$store->setup();

1
2
3
4
5
6
7
8

$store->setup([
    'fields' => [
        [
            'path' => 'title',
            'type' => 'string',
        ],
    ],
]);

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\AI\Platform\Vector\Vector;
use Symfony\AI\Store\Document\Metadata;
use Symfony\AI\Store\Document\VectorDocument;
use Symfony\Component\Uid\Uuid;

$document = new VectorDocument(
    id: Uuid::v4(),
    vector: new Vector([0.1, 0.2, 0.3, /* ... */]),
    metadata: new Metadata(['title' => 'My Document', 'category' => 'example']),
);

$store->add($document);

1

$store->add([$document1, $document2]);

1
2
3
4
5
6
7
8

use Symfony\AI\Store\Query\VectorQuery;

$results = $store->query(new VectorQuery($queryVector));

foreach ($results as $document) {
    echo $document->getId() . ' (score: ' . $document->getScore() . ")\n";
    echo json_encode($document->getMetadata()->getArrayCopy()) . "\n";
}

1
2
3
4
5
6

$results = $store->query(new VectorQuery($queryVector), [
    'limit' => 10,
    'numCandidates' => 500,
    'filter' => ['category' => 'example'],
    'minScore' => 0.8,
]);

1
2
3
4

$store->remove($document->getId());

// Or remove multiple documents at once:
$store->remove([$id1, $id2, $id3]);

1

$store->drop();

Bulk Write Mode

By default, each add() or remove() call issues one database operation per document. Enable bulk write mode to batch all operations into a single round-trip, which reduces latency when inserting or deleting large numbers of documents:

1
2
3
4
5
6
7
8
9
10

$store = new Store(
    $client,
    'my_database',
    'documents',
    'vector_index',
    bulkWrite: true,
);

// All documents are sent in a single bulkWrite call:
$store->add([$document1, $document2, $document3]);

In the bundle configuration:

1
2
3
4
5
6
7

ai:
    store:
        mongodb:
            my_mongodb_store:
                database: 'my_database'
                index_name: 'vector_index'
                bulk_write: true

Similarity Metrics

The similarity metric is set on the Atlas Search index, not in the PHP code. Choose the metric that matches how your embedding model was trained:

• euclidean — Euclidean (L2) distance; good general-purpose default
• cosine — Cosine similarity; recommended for most text embeddings
• dotProduct — Dot product; use when vectors are already normalized

Change the similarity field in the Atlas Search index definition to switch metrics. Refer to the Atlas Vector Search field types documentation for details.

Local Development

For local development and testing you can use the mongodb-atlas-local Docker image, which provides Atlas Vector Search support without a cloud cluster:

1
2
3
4
5
6
7
8

# compose.yaml
services:
    mongodb:
        image: mongodb/mongodb-atlas-local:8.0
        environment:
            MONGODB_INITDB_DATABASE: my_database
        ports:
            - '27017:27017'

Then connect with:

1

MONGODB_URL=mongodb://localhost:27017

Limitations

• Requires MongoDB Atlas or the local Atlas emulator — standard MongoDB does not support Atlas Vector Search
• The Atlas Search index must be in the READY state before queries return results; index builds are asynchronous and may take a moment after setup()
• The filter query option requires the filtered fields to be declared in the Atlas Search index definition
• Vector dimensions must be consistent across all documents in the same index