A RESTful search and storage engine in one binary. Send it JSON or MessagePack documents over HTTP, then search them with full text, geospatial, and range queries. It runs on one machine.
📖 Official site: kronuz.github.io/Xapiand
docker run -p 8880:8880 --rm ghcr.io/kronuz/xapiand:latest # Linux amd64 / arm64
brew install Kronuz/tap/xapiand && xapiand # macOSEach release also ships RPM and DEB packages; see Installation, or build from source below.
curl -X PUT 'localhost:8880/twitter/tweet/1?commit' -H 'Content-Type: application/json' \
-d '{"user": "Kronuz", "postDate": "2016-11-15T13:12:00", "message": "Trying out Xapiand"}'
curl localhost:8880/twitter/tweet/1 # get it back
curl -X SEARCH 'localhost:8880/twitter/tweet/?q=user:Kronuz' # search for itThe index is created on first write. Writes become searchable at the next commit,
about a second later; ?commit waits for it. The
Quick-start continues with
searches, aggregations, and geo queries.
A single C++20 binary that gives you, out of the box:
- A RESTful HTTP API over a schemaless document store (JSON or MessagePack in, JSON/MessagePack out).
- Full-text search on the strata engine.
- Geospatial indexing and queries via a Hierarchical Triangular Mesh (HTM): points, circles, polygons, and collections become numeric range queries on the sphere.
- Range and numeric queries through order-preserving ("sortable") value encoding.
- Aggregations in the Elasticsearch style (buckets + metrics), computed per shard and merged across shards.
- Durable storage: a Haystack-inspired append-only volume format with an optional write-ahead log.
The design goal throughout is to keep the moving pieces few and the defaults sane: one binary does something useful immediately.
A note on scope. This release runs on a single node: the cluster (discovery, replication and distributed search) returns with the next phase of the plan. CMake pulls the extracted
Kronuz/*libraries and the upstream ones withFetchContent. See ARCHITECTURE.md for the full map.
- ARCHITECTURE.md — a deep tour of the subsystems (storage, search, geospatial, logging, the utility layer), the self-contained components worth reusing, and a catalog of bugs and risks found while reading the code.
- AGENTS.md — orientation for anyone (human or AI) working in this codebase: where things live, the conventions, the load-bearing invariants, and the traps.
- testing.md — the test layers, from unit tests to the docs-as-E2E suite and soak runs.
- scheduler.md and extraction.md — the (now completed) plans that split the scheduler stack and the rest of the utility code into the standalone Kronuz libraries.
Requires a C++20 compiler, CMake 3.16 or newer, and OpenSSL 3 (unless -DTLS=OFF).
Dependencies are fetched automatically at configure time via CMake FetchContent (see
below).
mkdir build && cd build
cmake ..
makeNotable CMake options (all default on unless noted):
| Option | Default | What it does |
|---|---|---|
TLS |
ON | HTTPS for the REST API; needs OpenSSL 3. |
DATABASE_WAL |
ON | Per-shard write-ahead log. |
DATA_STORAGE |
ON | Haystack-style document storage volumes. |
TRACEBACKS |
OFF (ON in Debug) | Pretty backtraces + cross-thread stack dumps. |
ASSERTS |
OFF (ON in Debug) | Internal assertions. |
TRACKED_MEM |
OFF | Allocator that attributes memory to call sites. |
BUILD_TESTS / BUILD_BENCHMARKS |
OFF | Build the test / benchmark suites. |
Xapiand runs entirely on the standalone-Asio
reactor runtime (there is no libev), and is
assembled from about sixty standalone Kronuz/* libraries plus a few third-party ones,
all wired in by CMake FetchContent at configure time. The runtime topology, the
dependency layering diagram, and the full dependency tree live in
ARCHITECTURE.md; see
Runtime architecture and
Dependencies.
The load-bearing pieces: reactor (the Asio server runtime), http (HTTP transport),
strata (the search engine), storage (append-only blob store), io / fs / system (POSIX I/O, filesystem, resource introspection),
plus the extracted cuuid condensed-UUID value type, the msgpack keystone
(msgpack-c + COW MsgPack + xchange + patcher), a foundation of strings /
repr / logger / traceback / compressors, and the search-domain libraries.
Issues and pull requests are welcome; see the contributing guide and AGENTS.md. The documentation examples double as the end-to-end test suite (testing.md).
MIT — Copyright © 2026 Germán Méndez Bravo (Kronuz) and © 2015–2020 Dubalu LLC.
Note that src/sortable_serialise.* carries Xapian's license (GPL) until the
value encoding is replaced; see ARCHITECTURE.md
before reusing code from this tree.