Such-API

Dieses Dokument beschreibt die v2-Such-API von Fess. Informationen zum gemeinsamen Antwort-Envelope, zum Fehlermodell und zu CSRF finden Sie unter API-Übersicht.

Die Basis-URL lautet http://<Server Name>/api/v2/ (Beispiel für eine lokale Umgebung: http://localhost:8080/api/v2).

Dokumente suchen

Anfrage

HTTP-Methode GET
Endpunkt /api/v2/search

Sucht nach Dokumenten, die der Abfrage entsprechen, und gibt die Ergebnisse im gemeinsamen Envelope zurück. Alle Feldnamen im Payload verwenden snake_case.

Der Parameter q unterstützt dieselbe Suchsyntax wie das reguläre Suchformular (z. B. AND-/OR-/NOT-Suche, Feldsuche, Wildcard-Suche, unscharfe Suche). Details zur Suchsyntax finden Sie unter Fess Benutzerhandbuch.

Anfrageparameter

Anfrageparameter
q Suchbegriff (URL-kodiert). Die maximale Länge wird durch api.param.max.length (Standardwert 1000) begrenzt. Bei Überschreitung wird ein invalid_request-Fehler (HTTP 400) zurückgegeben. Diese Begrenzung ist unabhängig von den Limits der Suchmaschine.
start Startposition (0-basiert; integer, >=0, Standardwert 0).
offset Offset von start (integer, >=0, Standardwert 0).
num Seitengröße (integer, >=1, Standardwert 10). <= 0 ergibt invalid_request. Werte über dem konfigurierten Maximum werden stillschweigend begrenzt. Ob eine Begrenzung stattfand, lässt sich durch Vergleich von num im Request und page_size im Response feststellen.
sort Sortierung (z. B. score).
lang Suchsprache. Kann mehrfach angegeben werden (Array). Beispiel: en.
ex_q Zusätzlicher Abfrageausdruck. Kann mehrfach angegeben werden.
sdh Ähnlichkeits-Dokument-Hash (similar-document hash).
fields.label Filtert nach Label-Name. Kann mehrfach angegeben werden. Dies ist der häufigste Anwendungsfall der allgemeinen fields.<name>-Familie; beliebige fields.<name>-Abfrageparameter schränken die Ergebnisse auf Dokumente ein, deren Feld <name> mit dem angegebenen Wert übereinstimmt.
as.* Erweiterte Suchbedingungen. Beliebige as.<name>-Parameter (z. B. as.q, as.filetype) werden an den erweiterten Suchbedingungsgenerator übergeben. Pro Name können mehrere Werte angegeben werden.
track_total_hits Wird an die Suchmaschine weitergeleitet und steuert die genaue Trefferanzahl (z. B. true oder ein ganzzahliger Schwellenwert). Beeinflusst, ob record_count_relation EQUAL_TO oder GREATER_THAN_OR_EQUAL_TO ist. false wird nicht akzeptiert und führt zu invalid_request.
facet.field Facettenfeld. Kann mehrfach angegeben werden (Array).
facet.query Facettenabfrage. Kann mehrfach angegeben werden (Array).
facet.size Maximale Anzahl zurückgegebener Facettenbegriffe (integer, >=1). Wird der Parameter zusammen mit facet.field oder facet.query angegeben, führen ein Wert von 0 oder weniger sowie ein Wert, der keine ganze Zahl ist, zu invalid_request (HTTP 400). Werte über query.facet.fields.size.max (Standard 1000) werden stillschweigend begrenzt.
facet.minDocCount Minimale Dokumentanzahl für einen Facettenbegriff (integer). Wird der Parameter zusammen mit facet.field oder facet.query angegeben, führt ein Wert, der keine ganze Zahl ist, zu invalid_request.
facet.sort Sortierung der Facetten.
facet.missing Behandlung von Facetten für Dokumente ohne Wert.
geo.location.point Mittelpunkt der Geokoordinate (z. B. 35.0,139.0).
geo.location.distance Entfernung vom Mittelpunkt (z. B. 10km).

Tabelle: Anfrageparameter

Antwort

Bei Erfolg (200) werden die folgenden Felder direkt unter response im gemeinsamen Envelope zurückgegeben.

{
  "response": {
    "status": 0,
    "q": "Fess",
    "query_id": "f8b1c2d3e4a5",
    "exec_time": 0.012,
    "query_time": 8,
    "page_size": 20,
    "page_number": 1,
    "record_count": 42,
    "record_count_relation": "EQUAL_TO",
    "page_count": 3,
    "highlight_params": "&hq=Fess",
    "next_page": true,
    "prev_page": false,
    "start_record_number": 1,
    "end_record_number": 20,
    "page_numbers": ["1", "2", "3"],
    "partial": false,
    "timed_out": false,
    "shard_failed": false,
    "search_query": "title:Fess OR content:Fess",
    "requested_time": 1717142400000,
    "related_query": ["enterprise search"],
    "related_contents": [],
    "data": [
      {
        "doc_id": "a1b2c3d4e5f6",
        "url": "https://example.com/",
        "title": "Example",
        "content_description": "An example document about Fess.",
        "score": 1.2345
      }
    ],
    "facet_field": [
      {
        "name": "label",
        "result": [
          { "value": "news", "count": 12 }
        ]
      }
    ],
    "facet_query": [
      { "value": "filetype:html", "count": 30 }
    ],
    "permission_state": "RESOLVED"
  }
}

Die einzelnen Felder sind wie folgt beschrieben:

Antwortfelder
q Suchbegriff (nullable).
query_id Bezeichner der Abfrage.
exec_time Ausführungszeit (double, Sekunden).
query_time Abfragezeit der Suchmaschine (int64, Millisekunden).
page_size Seitengröße.
page_number Aktuelle Seitennummer.
record_count Anzahl der Treffer (int64). Exakt gezählt wird nur bis query.track.total.hits (Standard: 10000); gibt es mehr Treffer, entspricht dieser Wert dieser Obergrenze und record_count_relation ist GREATER_THAN_OR_EQUAL_TO. Die Obergrenze lässt sich je Anfrage mit track_total_hits ändern.
record_count_relation Bei EQUAL_TO ist die Anzahl exakt; bei GREATER_THAN_OR_EQUAL_TO ist nur eine Untergrenze bekannt.
page_count Gesamtanzahl der Seiten.
highlight_params Abfrageparameter-Zeichenkette für die Hervorhebung.
next_page Gibt an, ob eine nächste Seite vorhanden ist (bool).
prev_page Gibt an, ob eine vorherige Seite vorhanden ist (bool).
start_record_number Startdatensatznummer dieser Seite.
end_record_number Enddatensatznummer dieser Seite.
page_numbers Array der im Pager angezeigten Seitennummern (Zeichenketten).
partial Gibt an, ob das Ergebnis unvollständig sein kann (bool). Immer true, wenn timed_out oder shard_failed den Wert true hat; kann aber auch true sein, wenn keines von beiden zutrifft, zum Beispiel wenn die Suche nicht ausgeführt werden konnte.
timed_out Gibt an, ob das Such-Timeout (query.timeout) abgelaufen ist und die Suchmaschine das Sammeln von Treffern abgebrochen hat (bool).
shard_failed Gibt an, ob bei einem oder mehreren Shards ein Fehler aufgetreten ist (bool).
search_query Tatsächlich ausgeführte Suchabfrage.
requested_time Zeitpunkt der Anfrage (int64, Epoch-Millisekunden).
related_query Array verwandter Abfragen (Zeichenketten).
related_contents Array verwandter Inhalte (Zeichenketten).
data Array der Suchergebnisse. Ein Element pro Dokument. Nur Felder, die von QueryFieldConfig#isApiResponseField erlaubt werden, sind enthalten; null-Werte und leere Schlüssel werden ausgeschlossen.
facet_field Array, das nur vorhanden ist, wenn Facettenfelder angefordert wurden. Jedes Element hat die Struktur {name, result:[{value, count}]}.
facet_query Array, das nur vorhanden ist, wenn Facettenabfragen angefordert wurden. Jedes Element hat die Struktur {value, count}.
permission_state Ob die Gruppen- und Rollenberechtigungen des suchenden Benutzers aufgelöst sind (RESOLVED, PENDING oder FAILED). PENDING (wird noch aufgelöst) und FAILED (fehlgeschlagen oder nur teilweise aufgelöst) bedeuten, dass der Benutzer weniger Berechtigungen hat, als er haben sollte, sodass in den Ergebnissen Dokumente fehlen können, die er sehen dürfte. Ein Gast ist RESOLVED.

Tabelle: Antwortfelder

Bemerkung

Leitet ein Plugin die Suche um, statt sie auszuführen (zum Beispiel ein Bang im Stil von DuckDuckGo wie !g), enthält die Erfolgsantwort nur q und redirect_url. Der Client soll zu redirect_url navigieren.

Fehlerantwort

Details zum Fehlermodell finden Sie unter API-Übersicht. Folgende HTTP-Statuscodes können von diesem Endpunkt zurückgegeben werden:

Fehlerantwort
Statuscode Beschreibung
400 Bad Request Wenn die Anfrage ungültig ist (zum Beispiel eine ungültige Abfrage, num von 0 oder weniger, ein ungültiger facet.*-Parameter oder track_total_hits=false).
401 Unauthorized Wenn eine Authentifizierung erforderlich ist (Anmeldepflicht aktiviert und anonymer Aufrufer, oder die Anfrage enthält ein nicht registriertes oder abgelaufenes Zugriffstoken).
405 Method Not Allowed Wenn die HTTP-Methode nicht erlaubt ist.
500 Internal Server Error Wenn ein interner Serverfehler auftritt.
503 Service Unavailable Wenn die Suchmaschine die Suche wegen fehlender Kapazität abgelehnt hat (sie hat 429 oder 503 geantwortet). error.code ist service_unavailable, und ein Retry-After-Header nennt die Wartezeit in Sekunden (5). Die Abfrage selbst ist in Ordnung; versuchen Sie es nach kurzer Wartezeit erneut.

Tabelle: Fehlerantwort

Alle Dokumente abrufen (Scroll-Suche / NDJSON)

Anfrage

HTTP-Methode GET
Endpunkt /api/v2/documents/all

Überträgt alle zur Abfrage passenden Dokumente als NDJSON (application/x-ndjson). Jede Zeile ist ein {"data":{...}}-Objekt, das die von QueryFieldConfig#isApiResponseField erlaubten Felder enthält. Anders als bei GET /search ist der Suchscore score nicht enthalten.

Wenn der Stream während der Übertragung fehlschlägt, wird als letzte Zeile folgendes ausgegeben und geflusht:

{"error":{"code":"internal_error","message":"stream error"}}

Daher müssen Clients den ersten Schlüssel der letzten Zeile prüfen, um zwischen normalem Abschluss (data) und einem Serverfehler (error) zu unterscheiden.

Die Abfrage wird mit denselben Parametern wie GET /search erstellt (q, sort, num, lang, ex_q, sdh, fields.*, as.*, track_total_hits, facet.*, geo.*). Die Scroll-Suche ist standardmäßig deaktiviert (api.search.scroll=false). Solange sie deaktiviert ist, gibt der Endpunkt invalid_request (400) zurück. Zum Aktivieren setzen Sie in fess_config.properties api.search.scroll=true (siehe Massen-Abruf von Suchergebnissen).

Anfrageparameter

Folgende Parameter sind in der Spezifikation explizit aufgeführt:

Anfrageparameter
q Suchbegriff.
sort Sortierung.
num Größe einer Seite (Scroll-Batch) (integer, >=1). <= 0 ergibt invalid_request.
lang Suchsprache. Kann mehrfach angegeben werden (Array).
ex_q Zusätzlicher Abfrageausdruck. Kann mehrfach angegeben werden (Array).
fields.label Filtert nach Label-Name. Kann mehrfach angegeben werden (Array). Teil der allgemeinen fields.<name>-Familie (siehe GET /search).
sdh Ähnlichkeits-Dokument-Hash (similar-document hash).

Tabelle: Anfrageparameter

Antwort

Bei Erfolg (200) ist der Content-Type application/x-ndjson, und die Ausgabe erfolgt zeilenweise, ein Dokument pro Zeile:

{"data":{"url":"https://example.com/","title":"Example"}}
{"data":{"url":"https://example.org/","title":"Example Org"}}

Fehlerantwort

Details zum Fehlermodell finden Sie unter API-Übersicht. Folgende HTTP-Statuscodes können von diesem Endpunkt zurückgegeben werden:

Fehlerantwort
Statuscode Beschreibung
400 Bad Request Ungültige Abfrage, num <= 0 oder Scroll-Suche durch api.search.scroll=false deaktiviert.
401 Unauthorized Wenn eine Authentifizierung erforderlich ist (Anmeldepflicht aktiviert und anonymer Aufrufer, oder die Anfrage enthält ein nicht registriertes oder abgelaufenes Zugriffstoken).
405 Method Not Allowed Wenn die HTTP-Methode nicht erlaubt ist.
500 Internal Server Error Wenn ein interner Serverfehler auftritt.

Tabelle: Fehlerantwort

Siehe auch