Connectoren und Reindexierung

Zwei Vorgänge halten einen Index aktuell: Connectoren bringen Dokumente von außen herein, Reindexierung baut die Collection neu, wenn sich die Schema und nicht der Inhalt ändert.

ConnectorenCopy Anchor Link

Ein Connector ist eine gespeicherte Quelle plus ein Feld-Mapping. Konfiguriert wird er in der Konsole (Search → Connectors); die öffentliche API bietet dafür keinen Schreibendpunkt. Vier Typen existieren:

KonfigurationCopy Anchor Link

ZeitplanCopy Anchor Link

Ein Connector hat ein Feld schedule mit hourly, daily, weekly oder manual. Der Scheduler führt fällige Connectoren aus (nextRunAt), ein Lock pro Connector verhindert parallele Läufe. manual heißt: nur über die Konsole oder POST /admin/jobs/run?job=connectors.

source_typeCopy Anchor Link

Jedes importierte Dokument bekommt source_type gleich dem Connectortyp — sitemap, url, json oder csv, nicht connector. Damit lässt sich ein misslungener Lauf gezielt zurücknehmen:

curl -sS -X DELETE "$AAC_API/indexes/documentation/documents" \
  -H "Authorization: Bearer $AAC_KEY" \
  -G --data-urlencode "filter_by=source_type:=sitemap"

Beim Sitemap-Connector werden pro Lauf höchstens so viele Seiten geladen, wie maxDocuments erlaubt (Standard 500). Seiten mit weniger als 40 Zeichen Text werden übersprungen — meist Navigations- oder Fehlerseiten. Ein Sitemap-Index (eine Sitemap, die auf weitere Sitemaps zeigt) wird eine Ebene tief verfolgt, maximal fünf Kind-Sitemaps.

SchutzmechanismenCopy Anchor Link

• SSRF-Schutz. Connector-URLs werden vor dem Abruf aufgelöst; Loopback, link-local, private und Metadaten-Bereiche werden abgelehnt, auch IPv6-Formen mit einer solchen eingebetteten IPv4-Adresse, und die Verbindung geht genau an die geprüfte Adresse (kein DNS-Rebinding). Jede Weiterleitung wird erneut geprüft; Zugangsdaten (Authorization, Cookies, die geheimen Header des Connectors) werden nach einer Weiterleitung zu einem anderen Origin nicht mitgesendet. SEARCH_ALLOW_PRIVATE_URLS=true hebt die Adressprüfung für die lokale Entwicklung auf; in Produktion wird es ignoriert.
• Zugangsdaten hängen am Endpunkt. Gespeicherte Geheimnisse erscheinen als *** und bleiben verschlüsselt. Wer URL, Domain oder Host eines Connectors ändert, muss die Geheimnisse neu eingeben (CREDENTIALS_REQUIRED), damit ein gespeichertes Passwort nie an einen neuen Host geht. Ein eingefügter verschlüsselter Wert enc:… wird abgelehnt (INVALID_SECRET_VALUE).
• Prüfsummen. Der Inhalt jedes Dokuments wird als SHA-256 gehasht und mit dem gespeicherten Hash verglichen, sodass ein nächtlicher Lauf nur Geändertes neu schreibt — der Unterschied zwischen 40.000 Schreibvorgängen und 40.
• Fehler pro Dokument. Ein Dokument, das die Engine ablehnt, landet in der Dead-Letter-Ablage, statt den Lauf abzubrechen.
• Grenzen. maxDocuments begrenzt den Lauf, das 5-MB-Limit den Speicher.

Dead LettersCopy Anchor Link

Abgelehnte Dokumente werden mit Quell-Payload und Fehlermeldung der Engine gespeichert. Nach dem Korrigieren von Mapping oder Schema lassen sie sich in der Konsole erneut einspielen; die Queue ist auch im Admin-Cockpit über alle Mandanten sichtbar. Eine wachsende Queue ist das früheste Signal, dass eine Quelle ihre Form geändert hat — noch bevor die Null-Ergebnis-Rate steigt.

Jobs ausführenCopy Anchor Link

Der Scheduler führt Connectoren, den Analytics-Rollup, Retention und Snapshots aus. Um einen Zyklus sofort laufen zu lassen — aus CI oder aus einem externen Worker in einer Umgebung ohne internen Timer. Das ist ein Aufruf für den Plattformbetreiber: neben dem API-Schlüssel braucht er den Header x-platform-admin-token mit dem Wert von SEARCH_PLATFORM_ADMIN_TOKEN (sonst 403):

curl -sS -X POST "$AAC_API/admin/jobs/run?job=connectors" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "x-platform-admin-token: $AAC_PLATFORM_ADMIN_TOKEN"

{
	"job": "connectors",
	"result": { "connectors": "ok" },
	"request_id": "req_5b7d9f1a3c5e7b9d1f3a5c7e"
}

job akzeptiert connectors, rollup, retention, snapshot, graph oder all. Alles andere ist 422 INVALID_QUERY mit der Meldung job must be connectors|rollup|retention|snapshot|graph|all. Der Lauf landet im Audit-Log.

Der Job connectors führt neben den fälligen Connectoren auch expireDocuments() aus — Dokumente mit abgelaufenem expires_at verschwinden also im selben Zyklus. rollup liefert Zähler für Logs, Events und Dead Letters, retention die aufgeräumten Zeilen, snapshot den Status der Engine-Sicherung.

ReindexierungCopy Anchor Link

Suchdienst kann ein Feld nicht löschen oder seinen Typ ändern, und manche Einstellungen werden nur beim Anlegen akzeptiert. Solche Änderungen brauchen einen Neuaufbau. POST /indexes/{slug}/reindex erledigt das ohne Ausfall:

1. Eine Shadow-Collection <alias>_v<n+1> wird mit aktuellem Schema und aktuellen Einstellungen angelegt.
2. Dokumente werden aus der lebenden Collection in die Shadow-Collection gestreamt.
3. Synonyme und Curations werden auf die Shadow-Collection erneut angewendet.
4. Der Alias wird atomar umgeschrieben.
5. Die alte Collection bleibt als Rollback-Collection des Jobs erhalten (der Scheduler löscht sie nach SEARCH_ROLLBACK_RETENTION_DAYS, Standard 7 Tage); eine Zeile in SearchSchemaMigration hält fest, was passiert ist.

Weil die Suche über den Alias läuft, gibt es kein Fenster, in dem eine Anfrage eine halb gefüllte Collection sieht: Bis zum Umschreiben bedient die alte Collection. Laufende Anfragen laufen dort zu Ende.

curl -sS -X POST "$AAC_API/indexes/documentation/reindex" \
  -H "Authorization: Bearer $AAC_KEY"

{
	"index": "documentation",
	"job_id": "job_01HZYC4M",
	"status": "queued",
	"status_url": "/api/v1/jobs/job_01HZYC4M",
	"request_id": "req_2f4a6c8e0b2d4f6a8c0e2b4d"
}

Die Antwort ist 202 Accepted: Der Neuaufbau läuft als Hintergrund-Job. Fragen Sie GET /jobs/{jobId} ab (siehe Jobs) — dort stehen phase, progress und nach completed result.documents und result.duration_ms. Ein zweiter Reindex desselben Index, solange einer aktiv ist, liefert 409 JOB_CONFLICT.

Voraussetzungen und GrenzenCopy Anchor Link

• Scope settings:write.
• Die Tariffunktion reindex: Free hat sie nicht (zwei Läufe im Katalog, aber ohne Funktion nicht nutzbar), Pro 50 und Enterprise 500 Läufe pro Periode. Ist das Kontingent erschöpft, kommt 429 QUOTA_EXCEEDED mit details.metric: "reindex".
• Der Lauf ist ein Scheduler-Job, nie Teil des HTTP-Requests. Stirbt der Worker, wird der Job nach Ablauf der Lease erneut übernommen. ?sync=true blockiert bis zum Ende und ist nur für Testsuiten gedacht.
• Dokumente kommen aus der lebenden Engine-Collection, nicht aus Postgres — alles, was außerhalb der Plattform indiziert wurde, bleibt erhalten.

Wann ein Reindex die Antwort istCopy Anchor Link

Die letzte Gruppe ist die teure: Ein Modellwechsel schreibt jedes Dokument neu und ist der einzige Fall, in dem ein Reindex Minuten statt Sekunden dauert.

Ergebnis prüfenCopy Anchor Link

curl -sS "$AAC_API/indexes/documentation/stats" \
  -H "Authorization: Bearer $AAC_KEY"

Vergleichen Sie documents mit dem Stand vor dem Reindex und beobachten Sie queries_24h sowie avg_latency_24h_ms auf eine Regression. Ein Feld-für-Feld-Vergleich steht in der Schema-Ansicht der Konsole, die die Felder der lebenden Collection so zeigt, wie die Engine sie meldet.

Sicherung vorherCopy Anchor Link

Ein Reindex ist umkehrbar, solange die alte Collection existiert — nach Schritt 5 nicht mehr. Vor einem Schema-Umbau lohnt ein Snapshot:

curl -sS -X POST "$AAC_API/admin/snapshot" \
  -H "Authorization: Bearer $AAC_KEY"

{
	"ok": true,
	"snapshot_path": "/data/search/snapshots/snapshot-20261023-1041",
	"request_id": "req_1c3e5b7a9f1c3e5b7d9a1c3e"
}

Schlägt der Snapshot fehl, kommt 502 SNAPSHOT_FAILED mit der Meldung der Engine. GET /admin/snapshots listet vorhandene Sicherungen mit Größe und Zeitstempel, DELETE /admin/snapshots?name=… entfernt eine — nur Namen, die auf .snapshot, .tar oder .gz enden, sonst 422 INVALID_SNAPSHOT_NAME.

Unabhängig von der Engine bleibt ein Export lesbar:

curl -sS "$AAC_API/indexes/documentation/documents/export" \
  -H "Authorization: Bearer $AAC_KEY" \
  -o documentation-backup.ndjson