[Store] remove minScore argument from VectorStoreInterface::query

DZunke · DZunke · commit 27000746c915 · 2025-07-30T20:25:31.000+02:00
diff --git a/src/store/doc/index.rst b/src/store/doc/index.rst
@@ -85,7 +85,7 @@ This leads to a store implementing two methods::
             // Implementation to add a document to the store
         }
 
-        public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+        public function query(Vector $vector, array $options = []): array
         {
             // Implementation to query the store for documents
             return [];
diff --git a/src/store/src/Bridge/Azure/SearchStore.php b/src/store/src/Bridge/Azure/SearchStore.php
@@ -44,7 +44,7 @@ public function add(VectorDocument ...$documents): void
         ]);
     }
 
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
         $result = $this->request('search', [
             'vectorQueries' => [$this->buildVectorQuery($vector)],
diff --git a/src/store/src/Bridge/ChromaDb/Store.php b/src/store/src/Bridge/ChromaDb/Store.php
@@ -48,7 +48,7 @@ public function add(VectorDocument ...$documents): void
         $collection->add($ids, $vectors, $metadata);
     }
 
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
         $collection = $this->client->getOrCreateCollection($this->collectionName);
         $queryResponse = $collection->query(
diff --git a/src/store/src/Bridge/MariaDb/Store.php b/src/store/src/Bridge/MariaDb/Store.php
@@ -100,10 +100,13 @@ public function add(VectorDocument ...$documents): void
     /**
      * @param array{
      *     limit?: positive-int,
+     *     maxScore?: float|null,
      * } $options
      */
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
+        $maxScore = $options['maxScore'] ?? null;
+
         $statement = $this->connection->prepare(
             \sprintf(
                 <<<'SQL'
@@ -115,15 +118,15 @@ public function query(Vector $vector, array $options = [], ?float $minScore = nu
                     SQL,
                 $this->vectorFieldName,
                 $this->tableName,
-                null !== $minScore ? \sprintf('WHERE VEC_DISTANCE_EUCLIDEAN(%1$s, VEC_FromText(:embedding)) >= :minScore', $this->vectorFieldName) : '',
+                null !== $maxScore ? \sprintf('WHERE VEC_DISTANCE_EUCLIDEAN(%1$s, VEC_FromText(:embedding)) <= :maxScore', $this->vectorFieldName) : '',
                 $options['limit'] ?? 5,
             ),
         );
 
         $params = ['embedding' => json_encode($vector->getData())];
 
-        if (null !== $minScore) {
-            $params['minScore'] = $minScore;
+        if (null !== $maxScore) {
+            $params['maxScore'] = $maxScore;
         }
 
         $documents = [];
diff --git a/src/store/src/Bridge/Meilisearch/Store.php b/src/store/src/Bridge/Meilisearch/Store.php
@@ -48,7 +48,7 @@ public function add(VectorDocument ...$documents): void
         );
     }
 
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
         $result = $this->request('POST', \sprintf('indexes/%s/search', $this->indexName), [
             'vector' => $vector->getData(),
diff --git a/src/store/src/Bridge/MongoDb/Store.php b/src/store/src/Bridge/MongoDb/Store.php
@@ -103,11 +103,18 @@ public function add(VectorDocument ...$documents): void
      * @param array{
      *     limit?: positive-int,
      *     numCandidates?: positive-int,
-     *     filter?: array<mixed>
+     *     filter?: array<mixed>,
+     *     minScore?: float,
      * } $options
      */
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
+        $minScore = null;
+        if (\array_key_exists('minScore', $options)) {
+            $minScore = $options['minScore'];
+            unset($options['minScore']);
+        }
+
         $pipeline = [
             [
                 '$vectorSearch' => array_merge([
diff --git a/src/store/src/Bridge/Neo4j/Store.php b/src/store/src/Bridge/Neo4j/Store.php
@@ -55,7 +55,7 @@ public function add(VectorDocument ...$documents): void
         }
     }
 
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
         $response = $this->request('POST', \sprintf('db/%s/query/v2', $this->databaseName), [
             'statement' => \sprintf('CALL db.index.vector.queryNodes("%s", 5, $vectors) YIELD node, score RETURN node, score', $this->vectorIndexName),
diff --git a/src/store/src/Bridge/Pinecone/Store.php b/src/store/src/Bridge/Pinecone/Store.php
@@ -57,7 +57,7 @@ public function add(VectorDocument ...$documents): void
         $this->getVectors()->upsert($vectors, $this->namespace);
     }
 
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
         $result = $this->getVectors()->query(
             vector: $vector->getData(),
diff --git a/src/store/src/Bridge/Postgres/Store.php b/src/store/src/Bridge/Postgres/Store.php
@@ -87,12 +87,13 @@ public function add(VectorDocument ...$documents): void
 
     /**
      * @param array<string, mixed> $options
-     * @param float|null           $minScore Minimum score to filter results (optional)
      *
      * @return VectorDocument[]
      */
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
+        $maxScore = $options['maxScore'] ?? null;
+
         $sql = \sprintf(<<<SQL
             SELECT id, %s AS embedding, metadata, (%s %s :embedding) AS score
             FROM %s
@@ -104,16 +105,16 @@ public function query(Vector $vector, array $options = [], ?float $minScore = nu
             $this->vectorFieldName,
             $this->distance->getComparisonSign(),
             $this->tableName,
-            null !== $minScore ? "WHERE ({$this->vectorFieldName} {$this->distance->getComparisonSign()} :embedding) >= :minScore" : '',
+            null !== $maxScore ? "WHERE ({$this->vectorFieldName} {$this->distance->getComparisonSign()} :embedding) <= :maxScore" : '',
             $options['limit'] ?? 5,
         );
         $statement = $this->connection->prepare($sql);
 
         $params = [
             'embedding' => $this->toPgvector($vector),
         ];
-        if (null !== $minScore) {
-            $params['minScore'] = $minScore;
+        if (null !== $maxScore) {
+            $params['maxScore'] = $maxScore;
         }
 
         $statement->execute($params);
diff --git a/src/store/src/Bridge/Qdrant/Store.php b/src/store/src/Bridge/Qdrant/Store.php
@@ -49,7 +49,7 @@ public function add(VectorDocument ...$documents): void
      *     offset?: positive-int
      * } $options
      */
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
         $payload = [
             'vector' => $vector->getData(),
diff --git a/src/store/src/Bridge/SurrealDb/Store.php b/src/store/src/Bridge/SurrealDb/Store.php
@@ -51,7 +51,7 @@ public function add(VectorDocument ...$documents): void
         }
     }
 
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
         $vectors = json_encode($vector->getData());
 
diff --git a/src/store/src/InMemoryStore.php b/src/store/src/InMemoryStore.php
@@ -46,7 +46,7 @@ public function add(VectorDocument ...$documents): void
      *     maxItems?: positive-int
      * } $options If maxItems is provided, only the top N results will be returned
      */
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array
+    public function query(Vector $vector, array $options = []): array
     {
         $strategy = match ($this->distance) {
             self::COSINE_DISTANCE => $this->cosineDistance(...),
diff --git a/src/store/src/VectorStoreInterface.php b/src/store/src/VectorStoreInterface.php
@@ -24,5 +24,5 @@ interface VectorStoreInterface extends StoreInterface
      *
      * @return VectorDocument[]
      */
-    public function query(Vector $vector, array $options = [], ?float $minScore = null): array;
+    public function query(Vector $vector, array $options = []): array;
 }
diff --git a/src/store/tests/Bridge/MariaDb/StoreTest.php b/src/store/tests/Bridge/MariaDb/StoreTest.php
@@ -21,18 +21,18 @@
 #[CoversClass(Store::class)]
 final class StoreTest extends TestCase
 {
-    public function testQueryWithMinScore()
+    public function testQueryWithMaxScore()
     {
         $pdo = $this->createMock(\PDO::class);
         $statement = $this->createMock(\PDOStatement::class);
 
         $store = new Store($pdo, 'embeddings_table', 'embedding_index', 'embedding');
 
-        // Expected SQL query with minScore
+        // Expected SQL query with max score
         $expectedQuery = <<<'SQL'
             SELECT id, VEC_ToText(embedding) embedding, metadata, VEC_DISTANCE_EUCLIDEAN(embedding, VEC_FromText(:embedding)) AS score
             FROM embeddings_table
-            WHERE VEC_DISTANCE_EUCLIDEAN(embedding, VEC_FromText(:embedding)) >= :minScore
+            WHERE VEC_DISTANCE_EUCLIDEAN(embedding, VEC_FromText(:embedding)) <= :maxScore
             ORDER BY score ASC
             LIMIT 5
             SQL;
@@ -44,13 +44,13 @@ public function testQueryWithMinScore()
 
         $uuid = Uuid::v4();
         $vectorData = [0.1, 0.2, 0.3];
-        $minScore = 0.8;
+        $maxScore = 0.8;
 
         $statement->expects($this->once())
             ->method('execute')
             ->with([
                 'embedding' => json_encode($vectorData),
-                'minScore' => $minScore,
+                'maxScore' => $maxScore,
             ]);
 
         $statement->expects($this->once())
@@ -65,22 +65,22 @@ public function testQueryWithMinScore()
                 ],
             ]);
 
-        $results = $store->query(new Vector($vectorData), [], $minScore);
+        $results = $store->query(new Vector($vectorData), ['maxScore' => $maxScore]);
 
         $this->assertCount(1, $results);
         $this->assertInstanceOf(VectorDocument::class, $results[0]);
         $this->assertSame(0.85, $results[0]->score);
         $this->assertSame(['title' => 'Test Document'], $results[0]->metadata->getArrayCopy());
     }
 
-    public function testQueryWithoutMinScore()
+    public function testQueryWithoutMaxScore()
     {
         $pdo = $this->createMock(\PDO::class);
         $statement = $this->createMock(\PDOStatement::class);
 
         $store = new Store($pdo, 'embeddings_table', 'embedding_index', 'embedding');
 
-        // Expected SQL query without minScore
+        // Expected SQL query without maxScore
         $expectedQuery = <<<'SQL'
             SELECT id, VEC_ToText(embedding) embedding, metadata, VEC_DISTANCE_EUCLIDEAN(embedding, VEC_FromText(:embedding)) AS score
             FROM embeddings_table
diff --git a/src/store/tests/Bridge/MongoDb/StoreTest.php b/src/store/tests/Bridge/MongoDb/StoreTest.php
@@ -274,7 +274,7 @@ public function testQueryWithMinScore()
             'test-index',
         );
 
-        $documents = $store->query(new Vector([0.1, 0.2, 0.3]), [], 0.8);
+        $documents = $store->query(new Vector([0.1, 0.2, 0.3]), ['minScore' => 0.8]);
 
         $this->assertCount(0, $documents);
     }
diff --git a/src/store/tests/Bridge/Postgres/StoreTest.php b/src/store/tests/Bridge/Postgres/StoreTest.php
@@ -106,7 +106,7 @@ public function testAddMultipleDocuments()
         $store->add($document1, $document2);
     }
 
-    public function testQueryWithoutMinScore()
+    public function testQueryWithoutMaxScore()
     {
         $pdo = $this->createMock(\PDO::class);
         $statement = $this->createMock(\PDOStatement::class);
@@ -153,7 +153,7 @@ public function testQueryWithoutMinScore()
         $this->assertSame(['title' => 'Test Document'], $results[0]->metadata->getArrayCopy());
     }
 
-    public function testQueryChangedDistanceMethodWithoutMinScore()
+    public function testQueryChangedDistanceMethodWithoutMaxScore()
     {
         $pdo = $this->createMock(\PDO::class);
         $statement = $this->createMock(\PDOStatement::class);
@@ -200,7 +200,7 @@ public function testQueryChangedDistanceMethodWithoutMinScore()
         $this->assertSame(['title' => 'Test Document'], $results[0]->metadata->getArrayCopy());
     }
 
-    public function testQueryWithMinScore()
+    public function testQueryWithMaxScore()
     {
         $pdo = $this->createMock(\PDO::class);
         $statement = $this->createMock(\PDOStatement::class);
@@ -209,7 +209,7 @@ public function testQueryWithMinScore()
 
         $expectedSql = 'SELECT id, embedding AS embedding, metadata, (embedding <-> :embedding) AS score
              FROM embeddings_table
-             WHERE (embedding <-> :embedding) >= :minScore
+             WHERE (embedding <-> :embedding) <= :maxScore
              ORDER BY score ASC
              LIMIT 5';
 
@@ -224,20 +224,20 @@ public function testQueryWithMinScore()
             ->method('execute')
             ->with([
                 'embedding' => '[0.1,0.2,0.3]',
-                'minScore' => 0.8,
+                'maxScore' => 0.8,
             ]);
 
         $statement->expects($this->once())
             ->method('fetchAll')
             ->with(\PDO::FETCH_ASSOC)
             ->willReturn([]);
 
-        $results = $store->query(new Vector([0.1, 0.2, 0.3]), [], 0.8);
+        $results = $store->query(new Vector([0.1, 0.2, 0.3]), ['maxScore' => 0.8]);
 
         $this->assertCount(0, $results);
     }
 
-    public function testQueryWithMinScoreAndDifferentDistance()
+    public function testQueryWithMaxScoreAndDifferentDistance()
     {
         $pdo = $this->createMock(\PDO::class);
         $statement = $this->createMock(\PDOStatement::class);
@@ -246,7 +246,7 @@ public function testQueryWithMinScoreAndDifferentDistance()
 
         $expectedSql = 'SELECT id, embedding AS embedding, metadata, (embedding <=> :embedding) AS score
              FROM embeddings_table
-             WHERE (embedding <=> :embedding) >= :minScore
+             WHERE (embedding <=> :embedding) <= :maxScore
              ORDER BY score ASC
              LIMIT 5';
 
@@ -261,15 +261,15 @@ public function testQueryWithMinScoreAndDifferentDistance()
             ->method('execute')
             ->with([
                 'embedding' => '[0.1,0.2,0.3]',
-                'minScore' => 0.8,
+                'maxScore' => 0.8,
             ]);
 
         $statement->expects($this->once())
             ->method('fetchAll')
             ->with(\PDO::FETCH_ASSOC)
             ->willReturn([]);
 
-        $results = $store->query(new Vector([0.1, 0.2, 0.3]), [], 0.8);
+        $results = $store->query(new Vector([0.1, 0.2, 0.3]), ['maxScore' => 0.8]);
 
         $this->assertCount(0, $results);
     }

Original file line number	Diff line number	Diff line change
`@@ -85,7 +85,7 @@ This leads to a store implementing two methods::`
`85`	`85`	`// Implementation to add a document to the store`
`86`	`86`	`}`
`87`	`87`
`88`		`- public function query(Vector $vector, array $options = [], ?float $minScore = null): array`
	`88`	`+ public function query(Vector $vector, array $options = []): array`
`89`	`89`	`{`
`90`	`90`	`// Implementation to query the store for documents`
`91`	`91`	`return [];`
Original file line number	Diff line number	Diff line change
`@@ -44,7 +44,7 @@ public function add(VectorDocument ...$documents): void`
`44`	`44`	`]);`
`45`	`45`	`}`
`46`	`46`
`47`		`- public function query(Vector $vector, array $options = [], ?float $minScore = null): array`
	`47`	`+ public function query(Vector $vector, array $options = []): array`
`48`	`48`	`{`
`49`	`49`	`$result = $this->request('search', [`
`50`	`50`	`'vectorQueries' => [$this->buildVectorQuery($vector)],`
Original file line number	Diff line number	Diff line change
`@@ -48,7 +48,7 @@ public function add(VectorDocument ...$documents): void`
`48`	`48`	`$collection->add($ids, $vectors, $metadata);`
`49`	`49`	`}`
`50`	`50`
`51`		`- public function query(Vector $vector, array $options = [], ?float $minScore = null): array`
	`51`	`+ public function query(Vector $vector, array $options = []): array`
`52`	`52`	`{`
`53`	`53`	`$collection = $this->client->getOrCreateCollection($this->collectionName);`
`54`	`54`	`$queryResponse = $collection->query(`
Original file line number	Diff line number	Diff line change
`@@ -55,7 +55,7 @@ public function add(VectorDocument ...$documents): void`
`55`	`55`	`}`
`56`	`56`	`}`
`57`	`57`
`58`		`- public function query(Vector $vector, array $options = [], ?float $minScore = null): array`
	`58`	`+ public function query(Vector $vector, array $options = []): array`
`59`	`59`	`{`
`60`	`60`	`$response = $this->request('POST', \sprintf('db/%s/query/v2', $this->databaseName), [`
`61`	`61`	`'statement' => \sprintf('CALL db.index.vector.queryNodes("%s", 5, $vectors) YIELD node, score RETURN node, score', $this->vectorIndexName),`
Original file line number	Diff line number	Diff line change
`@@ -57,7 +57,7 @@ public function add(VectorDocument ...$documents): void`
`57`	`57`	`$this->getVectors()->upsert($vectors, $this->namespace);`
`58`	`58`	`}`
`59`	`59`
`60`		`- public function query(Vector $vector, array $options = [], ?float $minScore = null): array`
	`60`	`+ public function query(Vector $vector, array $options = []): array`
`61`	`61`	`{`
`62`	`62`	`$result = $this->getVectors()->query(`
`63`	`63`	`vector: $vector->getData(),`
Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ public function add(VectorDocument ...$documents): void`
`49`	`49`	`* offset?: positive-int`
`50`	`50`	`* } $options`
`51`	`51`	`*/`
`52`		`- public function query(Vector $vector, array $options = [], ?float $minScore = null): array`
	`52`	`+ public function query(Vector $vector, array $options = []): array`
`53`	`53`	`{`
`54`	`54`	`$payload = [`
`55`	`55`	`'vector' => $vector->getData(),`