Consolidate SQL for distance_function into one single source of truth

[ecairol]

Vector search exists in three independent implementations that have drifted apart:

Location	Visibility gate	Over-fetch	MySQL distance fn
REST::handle_query	yes (LEFT JOIN wp_posts)	no	COSINE_DISTANCE()
Query::maybe_vector_search	via WP_Query re-gate	limit * 3	COSINE_DISTANCE()
admin/views/embeddings.php	none	no	DISTANCE(..., 'COSINE')

Each carried its own native + PHP-fallback branches, its own SQL, and its own
thresholds.

This is done as a prerequisite for adding filtered search, ie: constraining results by post
type, taxonomy, author, date.

What changed

New WPVDB\Search service in includes/class-wpvdb-search.php:

WPVDB\Search::query( array(
    'text'               => 'query text',   // or 'vector' => [...]
    'model'              => 'text-embedding-3-small',
    'limit'              => 10,
    'over_fetch'         => 3,
    'distance_threshold' => 0.35,
    'respect_visibility' => true,
    'output'             => ARRAY_A,        // or OBJECT
    'explain'            => false,
) );
// => [ 'results' => [...], 'plan' => [...] ]  |  WP_Error

The Service owns the fallback values, the unified SQL, and the result, and all
three call sites now delegate to it. 

### Main Changes

1. All paths use Database::get_vector_distance_function(). The admin screen
and REST previously hardcoded their own distance SQL. This is the only helper
that does MariaDB version detection (VEC_DISTANCE_* vs VEC_DISTANCE), so
consolidating on it changes the admin screen's SQL on MySQL from
DISTANCE(..., 'COSINE') to COSINE_DISTANCE(...).
3. REST over-fetches candidates (QUERY_OVER_FETCH = 3). The visibility gate
runs in SQL with a bare LIMIT %d, so filtered-out rows could shrink the
response below the requested k. The WP_Query path already over-fetched by 3x
for the same reason; REST now matches.
4. wpvdb_similarity_threshold now applies on the PHP fallback too. It
previously only affected the native path, so the same query returned different
result sets depending on the database engine. Sites without native vector
support will see fewer results from vdb_vector_query where the old behavior
returned everything sorted by distance. This is the riskiest of the four —
easy to drop if you'd rather keep the old fallback semantics.

[Copilot]

Pull request overview

This pull request introduces a unified WPVDB\\Search service as the single source of truth for vector similarity search SQL and fallback behavior, and updates REST, WP_Query integration, and the embeddings admin screen to delegate to it. This reduces drift across call sites and centralizes distance-function selection via Database::get_vector_distance_function().

Changes:

• Added WPVDB\\Search::query() service to centralize native-vs-fallback search behavior, SQL construction, and result shape.
• Updated REST and WP_Query vector search paths to call the new service (including REST over-fetch and consistent thresholding in fallback where applicable).
• Updated embeddings admin screen semantic search to delegate to the service and request explain data.

Reviewed changes

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

Show a summary per file

File	Description
wpvdb.php	Loads the new Search service during plugin bootstrap.
includes/class-wpvdb-search.php	New unified search implementation (native SQL + PHP fallback) and filterable clauses.
includes/class-wpvdb-rest.php	Delegates REST query handling to Search::query() and adds over-fetch constant.
includes/class-wpvdb-query.php	Delegates WP_Query vector search to Search::query() and applies similarity threshold to fallback too.
admin/views/embeddings.php	Delegates admin semantic search to Search::query() with explain enabled.
tests/bootstrap.php	Extends the wpdb stub for posts table name and loads the Search class for tests.
tests/unit/SearchTest.php	Adds unit tests covering Search defaults, clause construction, filterability, and input validation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ecairol]

Fixed on 8cc1e45

[ecairol]

The repo already solves this globally. phpunit.xml:22 registers an extension:

<extension class="WPVDB_Filter_Reset_Hook" file="tests/filter-reset-hook.php" />

which implements BeforeTestHook and AfterTestHook and clears the registry around every test

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (2)

includes/class-wpvdb-search.php:158

• Search::query() treats any array passed in vector as a valid embedding without validation. Because this is a public service API (and the REST layer allows vector queries behind a capability gate), passing an empty vector, wrong dimension, or non-numeric/non-finite values can lead to SQL errors in the native path and inconsistent scoring in the PHP fallback. Normalize and validate the vector before proceeding, returning a 400 WP_Error when invalid.

		$embedding = $args['vector'];
		if ( ! is_array( $embedding ) ) {
			if ( '' === trim( (string) $args['text'] ) ) {
				return new \WP_Error(
					'wpvdb_search_no_input',
					__( 'A query text or a query vector is required.', 'wpvdb' ),
					array( 'status' => 400 )
				);
			}

			$started   = microtime( true );
			$embedding = self::resolve_embedding( $args );

			$plan['timings_ms']['embed'] = (int) round( ( microtime( true ) - $started ) * 1000 );

			if ( is_wp_error( $embedding ) ) {
				return $embedding;
			}
		}

includes/class-wpvdb-search.php:167

• $plan includes a candidates key but it is never populated, even though the code computes $fetch = $limit * $over_fetch. This makes the returned plan inconsistent and less useful for debugging/explain output.

		$fetch = $args['limit'] * $args['over_fetch'];