Skip to content

fulltext_api.md

Latest commit

 

History

History
239 lines (183 loc) · 7.51 KB

fulltext_api.md

File metadata and controls

239 lines (183 loc) · 7.51 KB

Fulltext Search API

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

Status: ✅ Implementiert (v1) – BM25 Ranking mit HTTP Endpoint

Übersicht

Die Fulltext-Suche in Themis nutzt BM25 (Okapi BM25) für relevanzbasiertes Ranking. Der Index wird automatisch bei Entity-Operationen (PUT/DELETE) gepflegt.

Index-Erstellung

POST /index/create
{
  "table": "articles",
  "column": "content",
  "type": "fulltext",
  "config": {
    "stemming_enabled": true,
    "language": "de",  // en | de | none
    "stopwords_enabled": true,
    "stopwords": ["z.b."]  // optional, zusätzliche Stopwords (lowercase)
    ,"normalize_umlauts": true  // de: ä->a, ö->o, ü->u, ß->ss
  }
}

Fulltext-Suche mit BM25 Scores

POST /search/fulltext
{
  "table": "articles",
  "column": "content",
  "query": "machine learning optimization",
  "limit": 100
}

Response:

{
  "count": 42,
  "table": "articles",
  "column": "content",
  "query": "machine learning optimization",
  "results": [
    {"pk": "art_123", "score": 8.42},
    {"pk": "art_456", "score": 7.91},
    {"pk": "art_789", "score": 6.15}
  ]
}

BM25-Parameter

  • k1 = 1.2: Term saturation (höhere Werte erhöhen Gewicht wiederholter Terms)
  • b = 0.75: Document length normalization (0 = keine Normalisierung, 1 = volle Normalisierung)
  • IDF-Formel: log((N - df + 0.5) / (df + 0.5) + 1.0) (stabilisiert)

N und avgdl werden aus dem Kandidaten-Universum (Vereinigung aller Token-Sets) berechnet (v1 Approximation).

Tokenisierung

  • Whitespace-basiert: Tokens werden bei Leerzeichen/Satzzeichen getrennt

  • Lowercase: Alle Tokens in Kleinbuchstaben konvertiert

  • Optionales Stemming (pro Index konfigurierbar):

    • Aktivieren via POST /index/create mit type: "fulltext" und config.stemming_enabled=true
    • Unterstützte Sprachen: en (Porter-Subset), de (vereinfachtes Suffix-Stemming)
    • Query-Tokenisierung nutzt immer dieselbe Konfiguration wie der Index

  • Optionales Stopword-Filtering (pro Index konfigurierbar):

    • Aktivieren via config.stopwords_enabled=true
    • Standard-Listen für en und de; bei language: "none" wird nur die Custom-Liste angewendet
    • Eigene Stopwords via config.stopwords: ["foo", "bar"]
    • Stopwords werden vor dem Stemming entfernt

  • Optionale Normalisierung (DE):

    • Aktivieren via config.normalize_umlauts=true
    • Ersetzt ä→a, ö→o, ü→u, ß→ss vor Tokenisierung/Stemming
    • Beispiel: "läuft" → "lauft" (erleichtert Suchanfragen ohne Sonderzeichen)

Query-Semantik

  • AND-Logik: Alle Query-Tokens müssen im Dokument vorkommen (Schnittmenge)
  • Scoring: Dokumente mit höherer Termfrequenz und besserer Übereinstimmung erhalten höhere Scores
  • Sortierung: Ergebnisse absteigend nach BM25-Score sortiert

Phrasensuche ("…")

  • Quoted Phrases im Query werden als exakte Phrasen interpretiert, z. B.:
    • "deep learning" optimization
  • Kandidatenbildung erfolgt weiterhin über Tokens außerhalb der Anführungszeichen (AND-Logik).
  • Danach werden Kandidaten per Post-Filter behalten, wenn alle Phrasen im Originalfeldtext als Substring vorkommen.
    • Case-insensitive Vergleich
    • Optional mit normalize_umlauts=true: ä→a, ö→o, ü→u, ß→ss
  • Phrasen sind von Stemming/Stopwords nicht betroffen (Vergleich gegen den Feld-String, nicht gegen Tokens).

Einschränkungen (v1):

  • Keine Positionslisten im Index – die Phrasenprüfung ist ein nachgelagerter Substring-Check und daher langsamer bei sehr großen Kandidatenmengen.
  • Keine Wortgrenzen-/Satzzeichen-Logik; die Suche prüft eine einfache Teilzeichenkette nach Normalisierung/Lowercasing.

Index-Struktur

Der Fulltext-Index speichert:

  • Presence: ftidx:table:column:token:PK → "" (Inverted Index)
  • Term Frequency: fttf:table:column:token:PK → TF-Count
  • Doc Length: ftdlen:table:column:PK → Total Tokens in Doc

Backward Compatibility

Die alte API scanFulltext() (C++ intern) liefert weiterhin nur PKs ohne Scores. Für Score-basierte Suche scanFulltextWithScores() verwenden.

Performance

  • Kandidaten-basiert: BM25 wird nur für Kandidaten (Token-Schnittmenge) berechnet
  • O(|tokens| × |candidates|): Skaliert mit Query-Komplexität und Kandidatenmenge
  • Limit-Parameter: Nutze limit für Top-k Retrieval (default: 1000)

Roadmap

  • ✅ BM25 v1 mit HTTP API
  • ✅ Hybrid Search: Text + Vector Fusion (RRF/Weighted)
  • ✅ Analyzer: Stemming (EN/DE) pro Index konfigurierbar
  • ✅ Umlaut-/ß-Normalisierung (DE) optional pro Index
  • ✅ Phrase Search: "exact match" Queries (v1, ohne Positionsindex)
  • ✅ AQL Integration v1.3: FILTER FULLTEXT(...) AND <predicates>, SORT BM25(doc) DESC, RETURN {doc, score: BM25(doc)}
  • 🔲 Highlighting: Matched Terms in Response markieren

Beispiel-Workflow

# 1. Index erstellen
POST /index/create {"table": "docs", "column": "text", "type": "fulltext"}

# 2. Dokumente einfügen
PUT /entities/docs/doc1 {"text": "Machine learning and deep neural networks"}
PUT /entities/docs/doc2 {"text": "Deep learning for computer vision"}
PUT /entities/docs/doc3 {"text": "Neural network optimization techniques"}

# 3. Suche mit Relevanz
POST /search/fulltext {
  "table": "docs",
  "column": "text", 
  "query": "deep learning neural",
  "limit": 10
}

# Ergebnis: doc2 > doc1 > doc3 (nach BM25 Score sortiert)

AQL-Integration (v1.3)

Status: ✅ Implementiert (03.11.2025)

Fulltext-Suche kann auch über die AQL-Query-Language verwendet werden:

Syntax

FOR doc IN table
  FILTER FULLTEXT(doc.column, "query" [, limit])
  // optional weitere Prädikate per AND
  // z. B. AND doc.year >= 2023
  RETURN doc

Beispiele

Einfache Suche:

FOR article IN articles
  FILTER FULLTEXT(article.content, "machine learning")
  LIMIT 10
  RETURN {title: article.title, abstract: article.abstract}

Phrasensuche:

FOR paper IN research_papers
  FILTER FULLTEXT(paper.abstract, '"neural networks"')
  LIMIT 20
  RETURN paper

Mit benutzerdefiniertem Limit:

FOR doc IN documents
  FILTER FULLTEXT(doc.body, "AI optimization", 50)
  RETURN doc.title

Sortierung nach Relevanz (BM25 in AQL):

FOR doc IN articles
  FILTER FULLTEXT(doc.content, "machine learning")
  SORT BM25(doc) DESC
  LIMIT 10
  RETURN {title: doc.title, score: BM25(doc)}

HTTP API-Aufruf:

POST /query/aql
{
  "query": "FOR doc IN articles FILTER FULLTEXT(doc.content, \"machine learning\") LIMIT 10 RETURN doc"
}

Funktionsdetails

  • Argumente:

    • field: Spaltenname (muss Fulltext-Index haben)
    • query: Suchquery (Multi-Term mit AND-Logik, oder "phrase" für exakte Phrasen)
    • limit: Optional, default 1000 (max. Kandidaten für BM25-Ranking)

  • Ranking: Automatisch nach BM25-Score sortiert (höchster zuerst)

  • Index-Requirement: Fulltext-Index muss via POST /index/create erstellt sein

  • Features: Nutzt Index-Konfiguration (Stemming, Stopwords, Normalisierung)

Hinweise (v1.3)

  • FULLTEXT kann mit AND kombiniert werden. OR-Kombinationen werden über DNF-Übersetzung unterstützt (ein FULLTEXT pro Disjunkt).
  • BM25-Scores sind in AQL über BM25(doc) zugreifbar; sie werden bereitgestellt, wenn die Query den FULLTEXT-Ausführungspfad nutzt. Die End-to-End-Verdrahtung im AQL-Handler stellt dies sicher.

Siehe auch

  • AQL-Syntax: docs/aql_syntax.md - Vollständige AQL-Dokumentation
  • Index-Erstellung: Abschnitt "Index-Erstellung" oben
  • Performance: Abschnitt "Roadmap" unten für geplante Optimierungen