Skip to content

query_vector_hybrid.md

Latest commit

 

History

History
165 lines (134 loc) · 6.87 KB

query_vector_hybrid.md

File metadata and controls

165 lines (134 loc) · 6.87 KB

Vector Hybrid Search

Stand: 6. April 2026
Version: 1.0.0
Kategorie: Query

Datum: 19. Nov 2025 Status: EXPERIMENTAL (Windows/MSVC: einzelne Tests schlagen fehl; siehe Known Issues)

Hinweis (19. Nov 2025): Auf Windows (MSVC 19.44) liefern einige GTests für executeFilteredVectorSearch trotz erfolgreicher Pre‑Filter‑Whitelist aktuell 0 Ergebnisse. Details und Reproduktion: docs/KNOWN_ISSUES.md.

Ziel

Kombinierte Nutzung von ANN Vektorsuche (HNSW / Brute Force) mit attributbasiertem Pre- und Post-Filtering zur Reduktion der Kandidatenmenge und präziser Ergebnisanpassung.

Komponenten

  • Pre-Filtering: searchKnnPreFiltered() generiert Whitelist über SecondaryIndexManager für EQUALS / RANGE / IN / Vergleichsoperatoren.
  • Post-Filtering (Hybrid): QueryEngine::executeFilteredVectorSearch() wendet alle Operatoren (inkl. NOT_EQUALS, CONTAINS) auf geladene Entities nach Distanzsortierung an.

Unterstützte Operatoren

Operator Pre-Filter Post-Filter Beschreibung
EQUALS ✅ ✅ exakte Übereinstimmung
NOT_EQUALS ❌ (Scan nötig) ✅ Ausschluss von Wert
CONTAINS ❌ (Substring) ✅ Teilstring in Textfeld
GREATER_THAN ✅ (Range Scan) ✅ numerisch >
LESS_THAN ✅ ✅ numerisch <
GREATER_EQUAL ✅ ✅ numerisch >=
LESS_EQUAL ✅ ✅ numerisch <=
IN ✅ (Union von EQUALS) ✅ Wert in Menge
RANGE ✅ ✅ min <= x <= max

Ablauf

  1. Aufteilung der Filter: Pre-Filter geeignete Operatoren -> SecondaryIndex Scans.
  2. Whitelist Intersection (AND Semantik).
  3. ANN Suche (HNSW oder Fallback) mit Whitelist.
  4. Laden der Entities (RocksDB) und Anwendung aller Filter inkl. NOT_EQUALS / CONTAINS.
  5. Kürzung auf Top-k unter Beibehaltung Distanzsortierung.

Performance Hinweise

  • Selektive Filter zuerst verarbeiten um Whitelist früh zu schrumpfen.
  • max_filter_scan_size begrenzt Range-Scans; Überschreitung -> Fallback auf Post-Filtering.
  • NOT_EQUALS und CONTAINS immer Post-Filter (verhindert teure Vollscans vor ANN).
  • Bei sehr großer Whitelist > Schwelle: Standard KNN + Post-Filter (verhindert riesige HNSW calls).

Beispiele

FilteredVectorSearchQuery q;
q.table = "documents";
q.query_vector = embedding;
q.k = 15;
// Pre-Filter Kandidaten schrumpfen
q.filters.push_back({"category", FilteredVectorSearchQuery::AttributeFilter::Op::EQUALS, "tech"});
// Range Scan kombiniert
FilteredVectorSearchQuery::AttributeFilter scoreRange;
scoreRange.field = "score";
scoreRange.op = FilteredVectorSearchQuery::AttributeFilter::Op::RANGE;
scoreRange.value_min = "0.6";
scoreRange.value_max = "0.85";
q.filters.push_back(scoreRange);
// Post-Filter nur
FilteredVectorSearchQuery::AttributeFilter langContains;
langContains.field = "lang";
langContains.op = FilteredVectorSearchQuery::AttributeFilter::Op::CONTAINS;
langContains.value = "en"; // Teilstring (z.B. 'en-US')
q.filters.push_back(langContains);

auto [st, results] = engine.executeFilteredVectorSearch(q);

Erweiterungen (geplant)

  • Radius-Suche (epsilon Nachbarn unter Distanzschwelle) ✅ IMPLEMENTIERT
  • Score Fusion (Vector Distanz + Attributgewichtung)
  • Adaptive candidateMultiplier basierend auf selektiver Filterstatistik
  • Deterministische Tie-Breaks und Cutoffs (BM25 min_score, Vector max_distance) ✅

Radius Search (Epsilon Neighbors)

API: executeRadiusVectorSearch(RadiusVectorSearchQuery)

Verwendung: Alle Vektoren innerhalb Distanzschwelle finden (statt Top-k).

Parameter:

  • epsilon: Maximale Distanz (threshold)
  • max_results: Optional Obergrenze (0 = unbegrenzt)
  • filters: Attributfilter wie bei Filtered Search

Beispiel:

RadiusVectorSearchQuery rq;
rq.table = "products";
rq.query_vector = userPreferenceEmbedding;
rq.epsilon = 0.3f;  // Nur sehr ähnliche Produkte
rq.max_results = 50; // Max 50 Ergebnisse

// Filter: nur verfügbare Produkte
FilteredVectorSearchQuery::AttributeFilter availFilter;
availFilter.field = "in_stock";
availFilter.op = FilteredVectorSearchQuery::AttributeFilter::Op::EQUALS;
availFilter.value = "true";
rq.filters.push_back(availFilter);

auto [st, results] = engine.executeRadiusVectorSearch(rq);
// Alle Produkte mit Distanz <= 0.3 und in_stock=true

Performance:

  • HNSW: Fetch large k, filter by epsilon (keine native radius support)
  • Brute-Force: Direkter Distanzcheck während Scan
  • Pre-Filter reduziert Suchraum deutlich bei selektiven Attributen

Anwendungsfälle:

  • Clustering (alle Nachbarn in Radius)
  • Deduplizierung (Duplikate unter Schwelle)
  • Anomalie-Detektion (isolierte Punkte mit wenigen epsilon-Nachbarn)

Fehlende Teile

  • Radius Search API
  • Distanz-Re-Ranking mit Attributgewichten
  • Erweiterte Metriken (DOT kombiniert mit Normierung)

Tests

  • Vorhandene test_filtered_vector_search.cpp deckt EQUALS / RANGE / IN / Kombi ab.
  • Zusätzliche Tests für NOT_EQUALS & CONTAINS werden nach Test-Suite Reparatur ergänzt.
  • Fusion-Tests: RRF vs. Weighted mit Tie-Break (pk) und Cutoffs (min_text_score, max_vector_distance); deterministische Reihenfolge bei Gleichstand.

HTTP API Notizen (Hybrid & Fusion)

Dieser Abschnitt fasst die wichtigsten HTTP-Parameter und das Zusammenwirken von Pre- und Post-Filtering zusammen. Details und Beispiele siehe docs/apis/hybrid_search_api.md.

  • Hybrid /search/hybrid (Content + optional Graph-Expansion)

    • filters: Objekt- oder Array-Form
      • Objekt: { "field": "value" } → EQUALS (Whitelist-Prefilter)
      • Array: [ {"field":"dataset","op":"IN","values":["train","test"]}, {"field":"score","op":"RANGE","min":0.5,"max":1.0} ]
        • Unterstützt in Hybrid derzeit: EQUALS|EQ, IN, RANGE (über Schema-Mapping field_map auf Content-JSON-Pfade)
    • tie_break (pk|none) + tie_break_epsilon: deterministische Sortierung bei quasi gleichen Scores
    • Pre-Filter reduziert Vektor-Kandidaten via Whitelist; Post-Filter (Entity-Load) für komplexe Operatoren bleibt im Core erhalten.

  • Fusion /search/fusion (Text + Vektor)

    • Modi: rrf (Rangfusion) und weighted (gewichtete Normalisierung)
    • Alias: alpha entspricht weight_text (Gewicht der Textkomponente)
    • Cutoffs: min_text_score filtert BM25 vor Fusion; max_vector_distance filtert Vektortreffer vor Fusion
    • filters: Whitelist-Prefilter für Vektor, Post-Filter für Text (Attribute werden auf Entities geprüft)
    • Tie-Break: tie_break + tie_break_epsilon für stabile Reihenfolge bei gleichen Fusionsscores

Minimalbeispiel (Hybrid mit IN/RANGE und deterministischem Tie-Break):

{
	"query": "any",
	"k": 10,
	"expand": { "hops": 0 },
	"filters": [
		{"field": "dataset", "op": "IN", "values": ["train", "test"]},
		{"field": "score",   "op": "RANGE", "min": 0.5, "max": 1.0}
	],
	"tie_break": "pk",
	"tie_break_epsilon": 1e-12
}

Wartung

Siehe Roadmap Wartungsaufgabe "Test Suite Reparatur" für Anpassung legacy Tests nach Hybrid-Erweiterung.