What is Riot?
Riot is an Apache-2.0 text indexing and search library for Go, maintained by vcaesar. You embed it in your own program: open a writer on a directory (or in memory), add documents made of typed fields, and query them through a reader. It sits in the Rerank, Search & Hybrid category of the Retrieval & Knowledge (RAG) tools and is open-source, written in Go and licensed Apache-2.0.
Overview
Riot is an Apache-2.0 text indexing and search library for Go, maintained by vcaesar. You embed it in your own program: open a writer on a directory (or in memory), add documents made of typed fields, and query them through a reader. It covers the lexical side of retrieval — BM25 scoring with pluggable similarity, term, phrase, match, prefix, regexp, wildcard and fuzzy queries, boolean combinations, range and geo queries, match highlighting and aggregations — and, in the same index, vector fields searched with exact KNN or approximate HNSW nearest-neighbour queries.
That combination is what makes it useful for retrieval-augmented generation in Go: embeddings and keyword text can live side by side, so one library serves both halves of a hybrid search. HNSW graphs use int8 quantization and persist with the on-disk segments, so a reopened index searches them without a rebuild; `WithVectorStorage` chooses whether vectors are memory-mapped from disk (the default) or loaded onto the heap. A `gse` sub-package wraps Riot with the gse tokenizer for Chinese and Japanese text, query strings and highlighting.
The README describes Riot as a fork of the Bluge engine that changed its BM25 idf to Lucene's formula, and publishes its own single-machine comparison against Bleve and Bluge on 100,000 synthetic documents, noting it is not a formal benchmark. For a distributed, Elasticsearch-style server built on Riot, the same author points to the separate zedsearch project.
What it does
- Field types for text, numeric, date, boolean, IP, geo point and vector data in one index
- Queries: term, phrase, match, match phrase, prefix, regexp, wildcard, fuzzy, conjunction / disjunction / boolean, numeric, date, term and IP ranges, geo bounding box / distance / polygon, and KNN / ANN
- BM25 similarity with pluggable scoring interfaces, plus search-result match highlighting
- HNSW approximate vector search with int8 quantization; graphs persist with segments and are memory-mapped from disk
- Aggregations: terms, numeric and date range buckets; min / max / count / sum / avg / weighted avg; HyperLogLog++ cardinality and T-Digest quantiles
- CJK search through the `gse` sub-package, with query strings and highlighting
Getting started
Riot is a Go module. The steps below are condensed from the README's runnable examples; full programs live in the repository's `test/readme_demo` and `examples` directories.
Add the module
go get -u github.com/vcaesar/riotIndex a document
Open a writer on an index directory and add a document with a text field. Use `riot.InMemoryOnlyConfig()` for an in-memory index.
config := riot.DefaultConfig("./riot_index")
writer, err := riot.OpenWriter(config)
if err != nil {
log.Fatalf("error opening writer: %v", err)
}
defer writer.Close()
doc := riot.NewDocument("example").
AddField(riot.NewTextField("name", "riot"))
err = writer.Update(doc.ID(), doc)Search it
Open a reader on the same directory (or call `writer.Reader()` in the same process) and run a match query; the README example prints `match: example`.
reader, err := riot.OpenReader(riot.DefaultConfig("./riot_index"))
query := riot.NewMatchQuery("riot").SetField("name")
request := riot.NewTopNSearch(10, query).WithStandardAggregations()
matches, err := reader.Search(context.Background(), request)Add vectors and query nearest neighbours
Store an embedding with `riot.NewVectorField`, then run a KNN query with a cosine metric; `SetANN` switches it to approximate HNSW search. `go run ./examples/knn` runs the full example, and `go run ./examples/ann_disk` shows a persisted vector index.
field, err := riot.NewVectorField("embedding", []float32{1, 0})
doc := riot.NewDocument("east").AddField(field)
query := riot.NewKNNQuery("embedding", []float32{1, 0}, 2).
SetMetric(riot.Cosine)
query.SetANN(riot.ANNParams{EfSearch: 100}) // approximate instead of exact
matches, err := reader.Search(context.Background(), riot.NewTopNSearch(2, query))Commands and code are distilled from the project's own documentation — always check the official repo for the latest.
When to use it
- Adding keyword and embedding search to a Go service or CLI without running a separate search server
- Building the retrieval layer of a Go RAG pipeline where BM25 and vector results come from one index
- Searching Chinese or Japanese documents with proper tokenization and highlighted snippets
- Faceted search and analytics over a local corpus with term, range and quantile aggregations
How Riot compares
Riot alongside other open-source rerank, search & hybrid tools AI/TLDR tracks, ranked by GitHub stars.
| Tool | Stars | What it does |
|---|---|---|
| Elasticsearch | ★ 78.7k | Distributed search and analytics engine with a built-in vector database for dense/sparse embeddings and hybrid keyword-plus-semantic retrieval. |
| Meilisearch Cloud | ★ 59.9k | Managed cloud for the Meilisearch engine, combining fast full-text search with hybrid, semantic, and multimodal vector search. |
| Typesense Cloud | ★ 27.2k | Managed hosting for the Typesense search engine, offering typo-tolerant keyword search plus vector and semantic search via a simple API. |
| Tantivy | ★ 16.5k | A fast full-text search engine library in Rust that provides BM25 keyword search for the lexical half of hybrid retrieval. |
| FlagEmbedding | ★ 12.3k | BAAI's retrieval toolkit that provides the BGE embedding and cross-encoder reranker models used widely in RAG pipelines. |
| Vespa | ★ 7.2k | A search and serving engine that natively combines vector, keyword (BM25), and structured search with built-in ranking for large-scale retrieval. |
| DigUp | ★ 6.5k | An on-device Mac app that searches photos, PDFs, recordings, videos and code by what is in them, combining EmbeddingGemma 2 vectors run on llama.cpp with a keyword index. |
| Riot | ★ 6.1k | An embeddable Go library for BM25 full-text search and HNSW vector search in one index |
