[Store] Add query abstraction with filter support #1570

wachterjohannes · 2026-02-08T20:03:41Z

Q	A
Bug fix?	no
New feature?	yes
Docs?	yes
Issues	Fix #1562
License	MIT

Description

This PR implements a query abstraction pattern for the Store component, enabling support for multiple query types (Vector, Text, Hybrid) with an integrated filter system. This addresses RFC #1562 and provides a flexible foundation for advanced retrieval use cases.

Summary of Changes

Query Abstraction

QueryInterface: Base interface for all query types with getType() and getFilter() methods
QueryType Enum: Defines Vector, Text, and Hybrid query types
Query Implementations:
- VectorQuery: Classic vector similarity search (supported by all stores)
- TextQuery: Full-text search or internal vectorization (ChromaDB, Postgres, Cache)
- HybridQuery: Combined vector + text search with configurable semanticRatio parameter (Postgres, ChromaDB, Cache)

Filter System

FilterInterface: Base interface for query filters with getType() and toArray() methods
EqualFilter: Equality filter for metadata filtering (e.g., filtering by locale, category, status)
Filters are integrated directly into query objects

Store Updates

Postgres Store - Extended to support all three query types:

Vector search using pgvector extension
Full-text search using PostgreSQL's native FTS
Hybrid search with weighted scoring combining vector similarity and text relevance
EqualFilter support via JSONB operators

ChromaDB Store - Extended to support all three query types:

Vector and text queries via ChromaDB's native API
Hybrid query implementation with result merging
EqualFilter support via ChromaDB's filtering syntax

Pinecone, Redis, Qdrant Stores - Vector only with filter support:

Vector similarity search
EqualFilter support via respective backend filter syntaxes

Cache Store - All query types with filter support:

In-memory implementations for all query types
EqualFilter support via metadata filtering

API Changes

StoreInterface: Updated with new query(QueryInterface $query, array $options = []) signature
Capability Signaling: New supports(string $queryClass): bool method to check store capabilities
Retriever: Updated to use query abstraction with automatic capability detection
Exception: New UnsupportedQueryTypeException thrown for unsupported query types

Breaking Changes

Store::query() Signature Change

Before:

$store->query($vector, ['limit' => 10]);

After:

use Symfony\AI\Store\Query\VectorQuery;

$store->query(new VectorQuery($vector), ['limit' => 10]);

All existing code needs to wrap Vector objects in VectorQuery constructor.

Usage Examples

Vector Query with Filter

use Symfony\AI\Store\Query\VectorQuery;
use Symfony\AI\Store\Query\Filter\EqualFilter;

// Search for documents in English locale
$query = new VectorQuery($vector, new EqualFilter('locale', 'en'));
$results = $store->query($query, ['limit' => 10]);

Text Query

use Symfony\AI\Store\Query\TextQuery;

// Full-text search (Postgres, ChromaDB, Cache)
$query = new TextQuery('space adventure', new EqualFilter('category', 'scifi'));
$results = $store->query($query, ['limit' => 5]);

Hybrid Query

use Symfony\AI\Store\Query\HybridQuery;

// Combine vector and text with 70% vector weight
$query = new HybridQuery(
    $vector,
    'space adventure',
    0.7,  // semanticRatio (vector weight)
    new EqualFilter('status', 'published')
);
$results = $store->query($query);

Capability Checking

// Check store support before using query type
if ($store->supports(HybridQuery::class)) {
    $query = new HybridQuery($vector, $text);
} else {
    $query = new VectorQuery($vector);
}

Implement query abstraction pattern to support multiple query types (Vector, Text, Hybrid) with integrated filter system. Key changes: - Add QueryInterface with VectorQuery, TextQuery, and HybridQuery implementations - Add FilterInterface with EqualFilter implementation - Update StoreInterface with new query() signature and supports() method - Implement filter support in all reference stores (Postgres, ChromaDB, Pinecone, Redis, Qdrant, Cache) - Extend Postgres to support Vector, Text, and Hybrid queries with PostgreSQL FTS - Update Retriever to use query abstraction with capability checking Breaking change: Store::query() now accepts QueryInterface instead of Vector. Migration: Wrap Vector in VectorQuery constructor.

wachterjohannes · 2026-02-08T20:24:34Z

src/store/src/Retriever.php

        $this->logger->debug('Document retrieval completed', ['retrieved_count' => $count]);
    }
+
+    private function createQuery(string $query, array $options): QueryInterface


This is the most important part of this PR - it selects the right type of query

wachterjohannes · 2026-02-08T20:25:37Z

src/store/src/Query/QueryInterface.php

+{
+    public function getType(): QueryType;
+
+   public function getFilter(): ?FilterInterface;


not sure how the filter should look like and how we could validate them in the store. @chr-hertel for equal its easy but for more complex filters it could be hard to implement that in the stores

let's go incremental and skip the filter part for the first PR - we can slice that, right?

wachterjohannes · 2026-02-08T20:26:58Z

for all who take a look at this PR this is a POC as a discussion base

chr-hertel

Thanks @wachterjohannes for jumping on that - much appreciated 🙏

I left some comments to also slim down the diff here a bit.

chr-hertel · 2026-02-09T18:12:17Z

src/store/src/Query/TextQuery.php

+    public function getType(): QueryType
+    {
+        return QueryType::Text;
+    }


we only use that at exceptions right now? let's drop it then or do i miss something?

chr-hertel · 2026-02-09T18:20:39Z

src/store/src/Retriever.php

+        if ($this->store->supports(HybridQuery::class)) {
+            $this->logger->debug('Store supports hybrid queries, using HybridQuery with semantic ratio', ['semanticRatio' => $options['semanticRatio'] ?? 0.5]);
+
+            return new HybridQuery($this->vectorizer->vectorize($query), $query, $options['semanticRatio'] ?? 0.5);


is the assumption fair to use $query for both parts?

chr-hertel · 2026-02-09T18:23:05Z

src/store/src/Query/QueryType.php

+ *
+ * @author Johannes Wachter <johannes@sulu.io>
+ */
+enum QueryType: string


not sure we need that, do we?

chr-hertel · 2026-02-09T18:23:40Z

src/store/src/Query/QueryInterface.php

+{
+    public function getType(): QueryType;
+
+   public function getFilter(): ?FilterInterface;


let's go incremental and skip the filter part for the first PR - we can slice that, right?

chr-hertel · 2026-02-09T18:24:19Z

src/store/src/Query/HybridQuery.php

+        private readonly ?FilterInterface $filter = null,
+    ) {
+        if ($semanticRatio < 0.0 || $semanticRatio > 1.0) {
+            throw new \InvalidArgumentException(\sprintf('Semantic ratio must be between 0.0 and 1.0, got %.2f', $semanticRatio));


use Symfony\AI\Store\Exception\InvalidArgumentException instead of native one

wachterjohannes requested review from OskarStark and chr-hertel as code owners February 8, 2026 20:03

carsonbot added Feature New feature Store Issues & PRs about the AI Store component Status: Needs Review labels Feb 8, 2026

wachterjohannes force-pushed the feature/query-abstraction-with-filters branch from cc6d736 to ccd1d40 Compare February 8, 2026 20:22

wachterjohannes force-pushed the feature/query-abstraction-with-filters branch from ccd1d40 to ae3ba15 Compare February 8, 2026 20:23

wachterjohannes commented Feb 8, 2026

View reviewed changes

wachterjohannes mentioned this pull request Feb 8, 2026

[Store] Open Store::query(Vector) method for different query types #1562

Open

chr-hertel requested changes Feb 9, 2026

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Needs Review labels Feb 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Store] Add query abstraction with filter support #1570

[Store] Add query abstraction with filter support #1570

Uh oh!

wachterjohannes commented Feb 8, 2026

Uh oh!

wachterjohannes Feb 8, 2026

Uh oh!

wachterjohannes Feb 8, 2026

Uh oh!

chr-hertel Feb 9, 2026

Uh oh!

wachterjohannes commented Feb 8, 2026

Uh oh!

chr-hertel left a comment

Uh oh!

chr-hertel Feb 9, 2026

Uh oh!

chr-hertel Feb 9, 2026

Uh oh!

chr-hertel Feb 9, 2026

Uh oh!

chr-hertel Feb 9, 2026

Uh oh!

chr-hertel Feb 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

[Store] Add query abstraction with filter support #1570

Are you sure you want to change the base?

[Store] Add query abstraction with filter support #1570

Uh oh!

Conversation

wachterjohannes commented Feb 8, 2026

Description

Summary of Changes

Query Abstraction

Filter System

Store Updates

API Changes

Breaking Changes

Store::query() Signature Change

Usage Examples

Vector Query with Filter

Text Query

Hybrid Query

Capability Checking

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wachterjohannes commented Feb 8, 2026

Uh oh!

chr-hertel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants