[Store] Add PostgresHybridStore with RRF following Supabase approach

[ahmed-bhs]

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

Problem

Choosing between vector search and full-text search forces a trade-off:

• Vector search: Best for semantic similarity but may rank exact term matches lower
• Full-text search: Best for lexical matching but misses semantic relationships

Users often need both in the same query: conceptual understanding + lexical precision.

Solution

Hybrid search combining both using Reciprocal Rank Fusion (RRF), following Supabase's approach.

RRF merges rankings from vector similarity and PostgreSQL Full-Text Search (ts_rank_cd).

Features

• Configurable ratio: 0.0 (FTS) to 1.0 (vector)
• RRF fusion: k=60 default (same as Supabase)
• Multilingual: Language-agnostic by default
• Optional filtering: defaultMaxScore to filter irrelevant results

Implementation

• PostgreSQL FTS (ts_rank_cd) + pgvector
• GIN index for FTS performance
• Generated tsvector column

Example

$store = new PostgresHybridStore(
    connection: $pdo,
    tableName: 'documents',
    semanticRatio: 0.5,  // 50% vector + 50% FTS
    rrfK: 60,
);

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

[Copilot]

Pull Request Overview

This PR introduces PostgresHybridStore, a new vector store implementation that combines semantic vector search (pgvector) with PostgreSQL Full-Text Search (FTS) using Reciprocal Rank Fusion (RRF), following Supabase's hybrid search approach.

Key changes:

• Implements configurable hybrid search with adjustable semantic ratio (0.0 for pure FTS, 1.0 for pure vector, 0.5 for balanced)
• Uses RRF algorithm with k=60 default to merge vector similarity and ts_rank_cd rankings
• Supports multilingual content through configurable PostgreSQL text search configurations

Reviewed Changes

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

File	Description
src/store/src/Bridge/Postgres/PostgresHybridStore.php	Core implementation of hybrid store with vector/FTS query building, RRF fusion logic, and table setup with tsvector generation
src/store/tests/Bridge/Postgres/PostgresHybridStoreTest.php	Comprehensive test coverage for constructor validation, setup, pure vector/FTS queries, hybrid RRF queries, and various configuration options

---

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

[Copilot]

Using str_replace to inject the FTS filter is fragile and could fail if the WHERE clause contains the substring 'WHERE ' in other contexts (e.g., in a string literal or subquery). Consider using a more robust approach such as parsing the clause structure or prepending the filter condition with proper AND logic.

Suggested change

	// Combine existing WHERE clause with FTS filter
	$whereClause = str_replace('WHERE ', "WHERE $ftsFilter AND ", $whereClause);
	// Combine existing WHERE clause with FTS filter using AND logic
	// Assumes $whereClause starts with 'WHERE '
	$whereClause = rtrim($whereClause);
	if (str_starts_with($whereClause, 'WHERE ')) {
	$whereClause .= " AND $ftsFilter";
	} else {
	// Unexpected format, prepend WHERE
	$whereClause = "WHERE $ftsFilter AND " . ltrim($whereClause);
	}

[chr-hertel]

this caught my eyes as well and i was wondering if the where building can be brought into one single place instead of spreading it over three methods - what do you think?

[ahmed-bhs]

Good catch! I've centralized the WHERE clause building logic into a dedicated addFilterToWhereClause() helper method. This removes the duplication across buildFtsOnlyQuery()
and buildHybridQuery(), and also makes the str_replace approach more robust by using str_starts_with() instead.

[Copilot]

Same issue as in buildFtsOnlyQuery: using str_replace to inject the FTS filter is fragile and could produce incorrect SQL if 'WHERE ' appears in unexpected contexts. Consider a more robust approach to combining WHERE conditions.

[chr-hertel]

In general this is a super cool feature - some copilot findings seem valid to me - please check.

On top, I was unsure if all sprintf need to be sprintf or some values can/should be a prepared parameter - that'd be great to double check as well please.

[chr-hertel]

let's just call it HybridStore instead

Suggested change

	final readonly class PostgresHybridStore implements ManagedStoreInterface, StoreInterface
	final readonly class HybridStore implements ManagedStoreInterface, StoreInterface

[ahmed-bhs]

@chr-hertel Thanks for reviewing. I've just renamed it.

[chr-hertel]

@ahmed-bhs could you please have a look at the pipeline failures - i think there's still some minor parts open