Metadata Filter eval - wip

Author: danielebarbaro

README.md

@@ -400,11 +400,101 @@ $filter = MetadataFilter::contains('tags', 'php');  // matches ['tags' => ['php'
 
 Pass filters to any search method. Multiple filters are ANDed together by default.
 
+```php
+use PHPVector\MetadataFilter;
+
+// Vector search with filters
+$results = $db->vectorSearch(
+    vector: $queryVector,
+    k: 10,
+    filters: [
+        MetadataFilter::eq('lang', 'en'),
+        MetadataFilter::gt('year', 2020),
+    ],
+);
+
+// Text search with filters
+$results = $db->textSearch(
+    query: 'machine learning',
+    k: 10,
+    filters: [
+        MetadataFilter::in('category', ['tech', 'science']),
+    ],
+);
+
+// Hybrid search with filters
+$results = $db->hybridSearch(
+    vector: $queryVector,
+    text: 'machine learning',
+    k: 10,
+    filters: [
+        MetadataFilter::eq('status', 'published'),
+    ],
+);
+```
 
 ### OR groups (nested arrays)
 
 Wrap filters in a nested array to create OR groups. Filters at the top level are ANDed; filters inside a nested array are ORed.
 
+```php
+// (category = 'tech' OR category = 'science') AND status = 'published'
+$results = $db->vectorSearch(
+    vector: $queryVector,
+    k: 10,
+    filters: [
+        [
+            MetadataFilter::eq('category', 'tech'),
+            MetadataFilter::eq('category', 'science'),
+        ],  // OR group
+        MetadataFilter::eq('status', 'published'),  // ANDed with the OR group
+    ],
+);
+```
+
+### Over-fetching for filtered queries
+
+When filters are applied, the search may need to examine more candidates than `k` to find enough matching documents. By default, the search fetches `k * 5` candidates, then filters. You can tune this:
+
+```php
+// Fetch 10× candidates before filtering (useful when filters are very selective)
+$results = $db->vectorSearch(
+    vector: $queryVector,
+    k: 10,
+    filters: [MetadataFilter::eq('rare_tag', 'value')],
+    overFetch: 10,
+);
+```
+
+> **Note:** Filtered queries may return fewer than `k` results if not enough documents match.
+
+### Updating metadata
+
+Update metadata on existing documents without re-indexing vectors or text:
+
+```php
+// Add or update metadata keys
+$db->patchMetadata(id: 1, patch: [
+    'status' => 'archived',
+    'updated_at' => '2026-03-24',
+]);
+
+// Remove metadata keys by setting to null
+$db->patchMetadata(id: 1, patch: [
+    'deprecated_field' => null,  // key will be removed
+]);
+
+// patchMetadata returns false if document not found
+if (!$db->patchMetadata(id: 999, patch: ['key' => 'value'])) {
+    echo "Document not found\n";
+}
+```
+
+The `patchMetadata()` method:
+- Merges patch into existing metadata (existing keys preserved unless overwritten)
+- Does NOT touch HNSW or BM25 indexes (fast, metadata-only operation)
+- Persists immediately when database has a path configured
+
 ### Metadata-only search
 
 Query documents by metadata alone, without a vector or text query:
@@ -415,6 +505,25 @@ $results = $db->metadataSearch(
     filters: [MetadataFilter::eq('status', 'published')],
 );
 
+// With limit
+$results = $db->metadataSearch(
+    filters: [MetadataFilter::gt('year', 2020)],
+    limit: 100,
+);
+
+// With sorting by metadata key
+$results = $db->metadataSearch(
+    filters: [MetadataFilter::eq('status', 'published')],
+    sortBy: 'created_at',
+    sortDirection: 'desc',  // 'asc' or 'desc'
+);
+
+// Empty filters returns all documents
+$allDocs = $db->metadataSearch(filters: [], limit: 50);
+```
+
+> **Note:** Documents missing the `sortBy` key are placed at the end of results. All results have `score = 1.0` (no ranking).
+
 ### Strict type comparison
 
 Metadata filtering uses **strict type comparison** (PHP `===`). This means:

src/HNSW/Config.php

@@ -68,6 +68,14 @@ final class Config
      */
     public readonly bool $keepPrunedConnections;
 
+    /**
+     * Over-fetch multiplier when metadata filtering is active.
+     * Fetch overFetchMultiplier × k candidates, then filter to k.
+     * Higher value → better result completeness when many candidates are filtered out.
+     * Default: 5.
+     */
+    public readonly int $overFetchMultiplier;
+
     public function __construct(
         int $M = 16,
         ?int $M0 = null,
@@ -78,13 +86,17 @@ public function __construct(
         bool $useHeuristic = true,
         bool $extendCandidates = false,
         bool $keepPrunedConnections = true,
+        int $overFetchMultiplier = 5,
     ) {
         if ($M < 2) {
             throw new \InvalidArgumentException('M must be at least 2.');
         }
         if ($efConstruction < $M) {
             throw new \InvalidArgumentException('efConstruction must be ≥ M.');
         }
+        if ($overFetchMultiplier < 1) {
+            throw new \InvalidArgumentException('overFetchMultiplier must be at least 1.');
+        }
 
         $this->M = $M;
         $this->M0 = $M0 ?? ($M * 2);
@@ -94,5 +106,6 @@ public function __construct(
         $this->useHeuristic = $useHeuristic;
         $this->extendCandidates = $extendCandidates;
         $this->keepPrunedConnections = $keepPrunedConnections;
+        $this->overFetchMultiplier = $overFetchMultiplier;
     }
 }