PHPORM-382 Add $vectorSearch stage to the aggregation builder #2822

GromNaN · 2025-09-08T18:58:47Z

Q	A
Type	feature
BC Break	no
Fixed issues	PHPORM-382

Summary

Add the $vectorSearch stage builder.

$dm->getRepository(Face::class)
   ->createAggregationBuilder()
   ->hydrate(VectorSearchResult::class)
   ->vectorSearch()
       ->index('descriptions')
       ->path('descriptionEmbeddings')
       ->filter(
           $builder->matchExpr()
               ->field('id')
               ->notEqual($face->id)
       )
       ->numCandidates($limit * 20)
       ->queryVector($face->descriptionEmbeddings)
       ->limit($limit)
   ->project()
       ->field('_id')->expression(0)
       ->field('face')->expression('$$ROOT')
       ->field('score')->meta('vectorSearchScore');

Copilot

Pull Request Overview

This PR adds support for the MongoDB $vectorSearch aggregation stage to the Doctrine ODM aggregation builder. This enables vector similarity search functionality for MongoDB Atlas Vector Search.

Implements a new VectorSearch stage class with fluent API methods for all supported options
Adds comprehensive test coverage for all stage methods and option combinations
Supports all vector search parameters: exact matching, filtering, indexing, limits, candidates, path, and query vectors

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
lib/Doctrine/ODM/MongoDB/Aggregation/Stage/VectorSearch.php	Main implementation of the VectorSearch stage with fluent API methods
tests/Doctrine/ODM/MongoDB/Tests/Aggregation/Stage/VectorSearchTest.php	Comprehensive test suite covering all VectorSearch functionality

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/VectorSearch.php

GromNaN · 2025-09-08T19:34:32Z

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/VectorSearch.php

+        if ($this->exact !== null) {
+            $params['exact'] = $this->exact;
+        }
+
+        if ($this->filter !== null) {
+            $params['filter'] = $this->filter->getQuery();
+        }
+
+        if ($this->index !== null) {
+            $params['index'] = $this->index;
+        }
+
+        if ($this->limit !== null) {
+            $params['limit'] = $this->limit;
+        }
+
+        if ($this->numCandidates !== null) {
+            $params['numCandidates'] = $this->numCandidates;
+        }
+
+        if ($this->path !== null) {
+            $params['path'] = $this->path;
+        }
+
+        if ($this->queryVector !== null) {
+            $params['queryVector'] = $this->queryVector;
+        }


index, limit, path and queryVector are required. The server will return an error if they are not used.
Looking at the other stages, it seems that we don't check this before.

Makes sense to me. Maybe it's nice to document this as a standard in some sort of development decision documentation in the repo, as I think we've had conversations about this before.

GromNaN · 2025-09-08T19:39:07Z

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/VectorSearch.php

+        if ($this->path !== null) {
+            $params['path'] = $this->path;
+        }


The path should be mapped to the field name using the class metadata.

Is this a TODO item? If so, is there another ticket to track this?

This seems related to #2820 (comment) from the PR that introduced a VectorSearchIndex mapping.

Not added to the Stage class as this stage must be first

jmikola · 2025-09-10T20:38:46Z

lib/Doctrine/ODM/MongoDB/Aggregation/Builder.php

+     *
+     * @see https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/#mongodb-pipeline-pipe.-vectorSearch
+     */
+    public function vectorSearch(): Stage\VectorSearch


IIUC, this PR does not add a Stage::vectorSearch() method for the same reason that you deprecated Stage::search() in #2823, correct?

jmikola · 2025-09-10T20:39:58Z

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/VectorSearch.php

+        if ($this->path !== null) {
+            $params['path'] = $this->path;
+        }


Is this a TODO item? If so, is there another ticket to track this?

This seems related to #2820 (comment) from the PR that introduced a VectorSearchIndex mapping.

GromNaN added this to the 2.13.0 milestone Sep 8, 2025

GromNaN requested a review from Copilot September 8, 2025 18:58

GromNaN added the Feature label Sep 8, 2025

This comment was marked as resolved.

Sign in to view

GromNaN requested review from Copilot, jmikola, alcaeus and paulinevos September 8, 2025 18:59

Copilot AI reviewed Sep 8, 2025

View reviewed changes

lib/Doctrine/ODM/MongoDB/Aggregation/Stage/VectorSearch.php Outdated Show resolved Hide resolved

GromNaN force-pushed the PHPORM-382 branch from ae6c6e6 to 195fa76 Compare September 8, 2025 19:08

PHPORM-382 Add $vectorSearch stage to the aggregation builder

ed408e5

GromNaN force-pushed the PHPORM-382 branch from 195fa76 to ed408e5 Compare September 8, 2025 19:26

doctrine deleted a comment from Copilot AI Sep 8, 2025

GromNaN commented Sep 8, 2025

View reviewed changes

GromNaN added 2 commits September 8, 2025 21:50

Add reference documentation

157bea3

Add Aggregation\Builder::vectorSearch entry point

743f3e7

Not added to the Stage class as this stage must be first

paulinevos approved these changes Sep 9, 2025

View reviewed changes

Support Binary vector

06a77a7

GromNaN merged commit ace0396 into doctrine:2.13.x Sep 10, 2025
22 checks passed

GromNaN deleted the PHPORM-382 branch September 10, 2025 10:45

jmikola reviewed Sep 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

PHPORM-382 Add $vectorSearch stage to the aggregation builder #2822

PHPORM-382 Add $vectorSearch stage to the aggregation builder #2822

GromNaN commented Sep 8, 2025 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

GromNaN Sep 8, 2025

Uh oh!

paulinevos Sep 9, 2025

Uh oh!

GromNaN Sep 8, 2025

Uh oh!

jmikola Sep 10, 2025

Uh oh!

Uh oh!

jmikola Sep 10, 2025

Uh oh!

jmikola Sep 10, 2025

Uh oh!

Uh oh!

Uh oh!

PHPORM-382 Add $vectorSearch stage to the aggregation builder #2822

PHPORM-382 Add $vectorSearch stage to the aggregation builder #2822

Conversation

GromNaN commented Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

This comment was marked as resolved.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

GromNaN Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

paulinevos Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

GromNaN Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

jmikola Sep 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jmikola Sep 10, 2025

Choose a reason for hiding this comment

Uh oh!

jmikola Sep 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GromNaN commented Sep 8, 2025 •

edited

Loading