Add an assertion on missing search index when a $search or $vectorSearch pipeline returns an empty result

Author: GromNaN

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

@@ -11,9 +11,11 @@
 use Doctrine\ODM\MongoDB\Iterator\Iterator;
 use Doctrine\ODM\MongoDB\Iterator\UnrewindableIterator;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
+use Doctrine\ODM\MongoDB\SchemaException;
 use MongoDB\Collection;
 use MongoDB\Driver\CursorInterface;
 
+use function array_key_first;
 use function array_merge;
 
 /** @phpstan-import-type PipelineExpression from Builder */
@@ -64,6 +66,48 @@ private function prepareIterator(CursorInterface $cursor): Iterator
             $cursor = new HydratingIterator($cursor, $this->dm->getUnitOfWork(), $this->classMetadata);
         }
 
-        return $this->rewindable ? new CachingIterator($cursor) : new UnrewindableIterator($cursor);
+        $iterator = $this->rewindable ? new CachingIterator($cursor) : new UnrewindableIterator($cursor);
+
+        $this->assertSearchIndexExistsWhenAggregationResultsIsEmpty($iterator);
+
+        return $iterator;
+    }
+
+    /**
+     * If the server implements a server-side error for missing search indexes,
+     * this assertion can be removed.
+     *
+     * @see https://jira.mongodb.org/browse/SERVER-110974
+     *
+     * @param Iterator<object> $iterator
+     */
+    private function assertSearchIndexExistsWhenAggregationResultsIsEmpty(Iterator $iterator): void
+    {
+        if ($iterator->current() !== false) {
+            return; // Results not empty
+        }
+
+        if (! $this->dm->getConfiguration()->assertSearchIndexExistsWhenAggregationResultsIsEmpty()) {
+            return; // Feature disabled
+        }
+
+        // Search stages must be the first stage in the pipeline
+        $indexName = match (array_key_first($this->pipeline[0])) {
+            '$search' => $this->pipeline[0]['$search']->index ?? null,
+            '$searchMeta' => $this->pipeline[0]['$searchMeta']->index ?? null,
+            '$vectorSearch' => $this->pipeline[0]['$vectorSearch']->index ?? null,
+            default => null,
+        };
+
+        if ($indexName === null) {
+            return; // Not a search aggregation or index not specified
+        }
+
+        $index = $this->collection->listSearchIndexes(['filter' => ['name' => $indexName]])->current();
+        if ($index) {
+            return; // Index exists
+        }
+
+        throw SchemaException::searchIndexNotFound($this->collection->getNamespace(), $indexName);
     }
 }

lib/Doctrine/ODM/MongoDB/Configuration.php

@@ -808,6 +808,23 @@ private function getAutoEncryptionOptions(): array
             ...$this->attributes['autoEncryption'] ?? [],
         ];
     }
+
+    /**
+     * Pipelines using a search index that does not exist or is not queryable
+     * will return zero documents. By enabling this feature, an additional query
+     * is made when the pipeline doesn't return any results to check if the
+     * search index exists and is queryable. If the index does not exist or is
+     * not queryable, an exception is thrown. This feature is enabled by default.
+     */
+    public function setAssertSearchIndexExistsWhenAggregationResultsIsEmpty(bool $enabled): void
+    {
+        $this->attributes['assertSearchIndexExistsWhenAggregationResultsIsEmpty'] = $enabled;
+    }
+
+    public function assertSearchIndexExistsWhenAggregationResultsIsEmpty(): bool
+    {
+        return $this->attributes['assertSearchIndexExistsWhenAggregationResultsIsEmpty'] ?? true;
+    }
 }
 
 interface_exists(MappingDriver::class);

lib/Doctrine/ODM/MongoDB/SchemaException.php

@@ -23,4 +23,10 @@ public static function missingSearchIndex(string $documentClass, array $missingI
     {
         return new self(sprintf('The document class "%s" is missing the following search index(es): "%s"', $documentClass, implode('", "', $missingIndexes)));
     }
+
+    /** @internal */
+    public static function searchIndexNotFound(string $namespace, string $indexName): self
+    {
+        return new self(sprintf('The search index "%s" of the collection "%s" is not found.', $indexName, $namespace));
+    }
 }

tests/Doctrine/ODM/MongoDB/Tests/Functional/AtlasSearchTest.php

@@ -4,6 +4,7 @@
 
 namespace Doctrine\ODM\MongoDB\Tests\Functional;
 
+use Doctrine\ODM\MongoDB\SchemaException;
 use Doctrine\ODM\MongoDB\Tests\BaseTestCase;
 use Documents\CmsArticle;
 use Documents\CmsUser;
@@ -54,6 +55,7 @@ public function testAtlasSearch(): void
         $schemaManager->waitForSearchIndexes([CmsArticle::class, CmsUser::class]);
 
         $results = $this->dm->createAggregationBuilder(CmsArticle::class)
+            ->rewindable(false)
             ->search()
                 ->index('search_articles')
                 ->autocomplete()
@@ -116,4 +118,35 @@ public function testAtlasSearch(): void
 
         $this->assertNotEmpty($results, 'Count search should return results');
     }
+
+    public function testIndexNotCreated(): void
+    {
+        $aggregation = $this->dm->createAggregationBuilder(CmsArticle::class)
+            ->search()
+                ->index('search_articles')
+                ->text()
+                ->query('Atlas Search')
+                ->path('text')
+            ->getAggregation();
+
+        $this->expectException(SchemaException::class);
+        $this->expectExceptionMessageMatches('#^The search index "search_articles" of the collection "[^."]+\.CmsArticle" is not found\.$#');
+
+        $aggregation->execute();
+    }
+
+    public function testIndexNotCreatedWithoutException(): void
+    {
+        $this->dm->getConfiguration()->setAssertSearchIndexExistsWhenAggregationResultsIsEmpty(false);
+
+        $results = $this->dm->createAggregationBuilder(CmsArticle::class)
+            ->search()
+                ->index('search_articles')
+                ->text()
+                ->query('Atlas Search')
+                ->path('text')
+            ->getAggregation()->execute();
+
+        $this->assertCount(0, $results->toArray());
+    }
 }