Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

docs(#805): publish the compatibility boundary on Migrate from ES

xerj-org7b08347b32cf
diff --git a/docs/recipes/migrate-from-elasticsearch.md b/docs/recipes/migrate-from-elasticsearch.md
index 179a135ab..bbd09236c 100644
--- a/docs/recipes/migrate-from-elasticsearch.md
+++ b/docs/recipes/migrate-from-elasticsearch.md
@@ -15,7 +15,7 @@ This recipe proves it by running the standard ES request shapes — verbatim —
- **Same wire, same client.** The official `elasticsearch-py`, `@elastic/elasticsearch`, or a raw `curl` all work because XERJ implements the ES REST API surface. XERJ even reports itself as version `8.13.0` at `GET /`, so version-sniffing clients connect cleanly.
- **Faster on the same workload.** On an identical corpus and machine, XERJ beats a real Elasticsearch 8.13 on both ingest and reads — e.g. bulk ingest ~1.5–1.7× and `match` queries ~2.5× lower p50 latency (see [Benchmarks](#benchmarks)).
-- **Honest scope.** XERJ is *wire-compatible*, not a byte-for-byte fork. As of the last full run it passes **1,325 / 1,326** executed cases of the 1,329-case ES REST conformance suite (3 skipped, 1 known fail). Response *shapes* match; some internal details (exact BM25 float scores, segment-merge timing) are XERJ's own. See [Limitations](#limitations-be-honest).
+- **Honest scope.** XERJ is *wire-compatible*, not a byte-for-byte fork. The ES REST YAML conformance suite runs on every commit and is gated at zero failures; a full run at main on 2026-09-20 passes **1,371 / 1,374** cases (3 skipped) on a curated 202-file subset whose `catch:` error expectations are unasserted — the pass total grows as cases are added, so gate on failures, not on the count. Response *shapes* match; some internal details (exact BM25 float scores, segment-merge timing) are XERJ's own. The full boundary — what is tested, what is deliberately not implemented, the semantic differences — is on one page: [what we test against](https://xerj.org/docs/migration-from-es#what-we-test-against). See [Limitations](#limitations-be-honest).
## The working solution
@@ -162,9 +162,9 @@ green open products 0ddfa388-df97-4b4b-9c9d-b9782b1b493a 1 0 6 0 10901b 10901b
Two honest deltas from Elasticsearch here:
- **`?v` does not emit a column-header row.** XERJ returns the data rows only, even with `?v`. The column *order* is ES's, so anything parsing by position keeps working; anything that keys off the header line does not.
-- **No per-index `_cat` path.** XERJ serves the whole-cluster `GET /_cat/indices` (which, like ES's own `.security`/`.kibana` dot-indices, also lists XERJ's internal `.xerj_*` system indices). The per-index form `GET /_cat/indices/products` returns **404** in this build, so filter client-side instead — e.g. `curl -s "$ES/_cat/indices?v" | grep ' products '`.
+- **The per-index `_cat` path works** — `GET /_cat/indices/products` returns just that index's row, and an unknown index name is a `404`. The whole-cluster form lists XERJ's internal `.xerj_*` system indices alongside yours, like ES's own `.security`/`.kibana` dot-indices.
-(The `uuid` column is a fresh per-response value in this build — treat it as illustrative, not stable.)
+(The `uuid` column is stable across repeated calls in this build — verified identical over consecutive requests — but treat it as opaque rather than a contract.)
## Reproduce it yourself
@@ -201,7 +201,7 @@ Almost nothing:
## Limitations (be honest)
-- **Wire-compatible, not byte-identical.** XERJ passes **1,325 / 1,326** executed cases of the 1,329-case ES REST conformance suite (3 skipped, 1 known fail), last full run. Response *structure* matches ES; validate the specific endpoints and query types your app depends on against your own data before cutting over. Per-suite conformance and caveats are tracked in `demo/playbooks/ES_COMPATIBILITY.md`.
+- **Wire-compatible, not byte-identical.** The ES REST YAML conformance suite runs on every commit and is gated at zero failures — a full run at main on 2026-09-20 passes **1,371 / 1,374** cases (3 skipped) on a curated 202-file subset whose `catch:` error expectations are unasserted. Response *structure* matches ES; validate the specific endpoints and query types your app depends on against your own data before cutting over. The boundary in one page — tested versions, implemented and refused APIs, semantic differences: [`docs/migration-from-es` — what we test against](https://xerj.org/docs/migration-from-es#what-we-test-against).
- **Relevance scores are XERJ's own BM25.** Ranking order matches ES intent, but exact `_score` float values differ, and can even shift slightly for the *same* query as background segment merges change collection statistics — the same class of internal difference you'd see comparing two ES minor versions. If you assert on exact scores in tests, relax those assertions.
- **A few query/agg types differ or aren't implemented.** XERJ covers the common set (`match`, `term`, `terms`, `range`, `bool`, `match_phrase`, `multi_match`, `terms`/`stats`/`date_histogram`/... aggs). Some ES features are partial or unsupported (e.g. vector-suite conformance is low). Check the compatibility report for your specific needs.
diff --git a/landing/docs/api-es-compat.html b/landing/docs/api-es-compat.html
index 48ba62874..3104c22ee 100644
--- a/landing/docs/api-es-compat.html
+++ b/landing/docs/api-es-compat.html
@@ -215,7 +215,7 @@
<h1>ES-compatible API</h1>
- <p>Port <code class="inline">9200</code>. The compat layer exists so you can point an existing Elasticsearch client at XERJ and keep shipping. It handles the most-used operations. Unsupported calls return a structured <code class="inline">not_supported_yet</code> error rather than a 500.</p>
+ <p>Port <code class="inline">9200</code>. The compat layer exists so you can point an existing Elasticsearch client at XERJ and keep shipping. It handles the most-used operations. Unsupported calls return a structured <code class="inline">not_supported_yet</code> error rather than a 500. What the compatibility promise is tested against — ES version, conformance suite, clients — and the known semantic differences below it are stated in one place: <a href="/docs/migration-from-es#what-we-test-against">the compatibility boundary</a> on Migrate from ES.</p>
<div class="api">
<div class="head">METHOD</div>
diff --git a/landing/docs/migration-from-es.html b/landing/docs/migration-from-es.html
index f19c18046..99a7b6f8c 100644
--- a/landing/docs/migration-from-es.html
+++ b/landing/docs/migration-from-es.html
@@ -217,6 +217,14 @@
<p>XERJ runs a second API listener on <code class="inline">9200</code> that speaks the Elasticsearch wire format. The fast path to trying XERJ is to point your existing ES client at it and let the compat layer take the calls. It isn't 100% coverage; this page says exactly what is and isn't there.</p>
+ <h2 id="what-we-test-against">What we test against</h2>
+ <ul>
+ <li><strong>The wire target is Elasticsearch 8.13 REST.</strong> The compat listener advertises <code class="inline">8.13.0</code> at <code class="inline">GET /</code> and sends <code class="inline">X-Elastic-Product: Elasticsearch</code> on its responses — the two handshake gates Kibana and the official clients check before they will talk to a node. Suite cases gated on 8.14+ version predicates are not run; nothing above 8.13 is claimed.</li>
+ <li><strong>The ES REST API YAML conformance suite, on every commit, gated at zero failures.</strong> A full run on 2026-09-20 passes <!-- snapshot:2026-09-20 -->1,371 / 1,374 cases (3 skipped; the count grows as cases are added — the invariant the gate enforces is 0 failed, not a pass total). The suite is a curated 202-file subset of Elasticsearch's public <code class="inline">rest-api-spec</code> YAML tests, extended with XERJ-authored cases for the AI-native surface. Two limits stated plainly: the runner does not verify error behaviour (<code class="inline">catch:</code> expectations are unasserted), and it speaks raw HTTP — no ES client library is exercised in CI.</li>
+ <li><strong>A live Elasticsearch 8.13.4, head to head.</strong> The published benchmarks drive one keep-alive HTTP client, the same corpus and the same machine against both engines, and publish every cell including the losses — <a href="/compare/xerj-vs-elasticsearch-local">the matrix is public</a>.</li>
+ <li><strong>Clients, honestly.</strong> There is no Kibana end-to-end test and no client version matrix in this repo. What is verified is the wire itself: the YAML suite above, plus curl-shaped request recipes that run end to end. Verify the specific behaviour your client depends on against your own node before you cut over.</li>
+ </ul>
+
<h2>What works day one</h2>
<ul>
<li><strong>Index CRUD:</strong> <code class="inline">PUT /:index</code>, <code class="inline">DELETE /:index</code>, <code class="inline">GET /:index</code>, <code class="inline">PUT /:index/_mapping</code>, <code class="inline">GET /:index/_mapping</code>.</li>
@@ -228,7 +236,7 @@
<li><strong>Delete by query:</strong> <code class="inline">POST /:index/_delete_by_query</code>.</li>
</ul>
- <h2>What needs rewriting</h2>
+ <h2 id="what-needs-rewriting">What needs rewriting</h2>
<ul>
<li><strong>Whole-index scroll reads.</strong> <!-- generated:scroll-snapshot-cap -->10,000<!-- /generated:scroll-snapshot-cap --> documents is the ceiling on a <code class="inline">_search?scroll=</code> snapshot: XERJ materialises the snapshot up front, so a query whose exact total is larger is refused with a <code class="inline">400</code> rather than paged and silently truncated. Anything that scrolls an entire index — <code class="inline">helpers.scan()</code>, exports, reindex scripts — moves to <code class="inline">search_after</code> on a unique sort key, which is unbounded. Mind that <code class="inline">_id</code> sorts lexicographically; take each cursor from the previous page's last <code class="inline">sort</code> value rather than computing it. Details, and the one route that applies the ceiling per index instead, on the <a href="/docs/api-es-compat#scroll-cap">ES-compat API</a> page.</li>
<li><strong>Scripted fields / scripted metrics.</strong> Painless is not implemented. Use <code class="inline">function_score</code> for the cases it covers.</li>
@@ -239,6 +247,15 @@
<li><strong>ILM (Index Lifecycle Management).</strong> Retention is controlled per-index via <code class="inline">[logs] retention_days</code>.</li>
</ul>
+ <h2 id="known-semantic-differences">Known semantic differences</h2>
+ <p>What follows are differences on APIs that <em>are</em> implemented: the call succeeds and returns the ES response shape, but the bytes are XERJ's own. They bite when a client asserts on details rather than shapes.</p>
+ <ul>
+ <li><strong>Scroll is a bounded snapshot, not a segment-walking cursor.</strong> The headline difference, because it can silently change results for tooling that paginates a live index: <code class="inline">_search?scroll=</code> materialises the whole snapshot up front, and a request whose exact total exceeds the window is refused with a <code class="inline">400</code> rather than paged past it. The ceiling, the per-index alias quirk, and the unbounded <code class="inline">search_after</code> replacement are in <a href="#what-needs-rewriting">What needs rewriting</a> above and on <a href="/docs/api-es-compat#scroll-cap">ES-compat API</a>.</li>
+ <li><strong>BM25 scores are XERJ's own.</strong> Ranking order matches the query's intent, but exact <code class="inline">_score</code> floats differ from ES and can shift for the same query as background merges move collection statistics — the same class of internal difference as between two ES minor versions. Relax tests that assert on exact score values.</li>
+ <li><strong>The default <code class="inline">_search</code> source is compact.</strong> With <code class="inline">_source</code> omitted, ordinary source fields come back but engine-generated <code class="inline">&lt;field&gt;_vector</code> and <code class="inline">&lt;field&gt;_vector_chunks</code> companions do not. Explicit <code class="inline">_source: true</code> returns them.</li>
+ <li><strong><code class="inline">_cat</code> headers.</strong> <code class="inline">_cat/indices?v</code> emits data rows only — no column-header row — though the column order is ES's, so positional parsing keeps working and header-line parsing does not. The per-index form <code class="inline">_cat/indices/:index</code> returns that index's row; an unknown index name is the <code class="inline">404</code>.</li>
+ </ul>
+
<h2>What's different (for the better)</h2>
<ul>
<li><strong>No heap tuning.</strong> No <code class="inline">-Xmx</code>, no GC pauses, no page-fault storms.</li>