bleve: a Go search library that indexes structs, JSON, geo points and vectors

What bleve solves, and who ends up using it

Most Go services that need search reach for a separate process: a search server, a sidecar, a managed service. That adds a network hop, a second deployment, and a second set of failure modes. bleve takes the opposite position. It is a library you import into a Go program, and it writes an index to a directory you choose. The README describes it as "A modern indexing + search library in GO", and the repository layout matches that description: index.go, mapping.go, search.go and query.go sit at the top level, with subdirectories for analysis, geo, numeric and fusion.

The intended user is a Go developer who already has the data in memory or on local disk. The README's first example indexes a plain struct with Id, From and Body fields, which tells you the audience is not a search team tuning relevance across a cluster. It is an application developer who wants filtered, scored, paginated results inside the same binary. The supported field types run wider than full text: text, number, datetime, boolean, geopoint, geoshape, IP and vector. That combination is what makes bleve interesting for local search over mixed records, such as a product catalog with prices and coordinates, or a log store with timestamps and host addresses.

One caveat is worth stating early. The name bleve is shared with a firefighting term, and Google's related searches for it return mostly results about boiling liquid expanding vapour explosions. If you search for this project by name alone, expect to filter out a lot of hazmat material.

The scorch index, mappings and the query path

The mechanism visible in the repository is a mapping plus a segment-based index. bleve.NewIndexMapping() builds a default mapping, and bleve.New(path, mapping) creates the index on disk. From then on, Index(id, document) writes a document and Search(request) reads. The default index implementation is scorch, which the README links to its own README under index/scorch. The go.mod file lists scorch_segment_api and a series of zapx segment format modules from v11 through v17, which shows that segment formats are versioned and that older formats remain as dependencies.

Queries are values, not strings sent to a server. The README lists term, phrase, match, match_phrase, prefix, regexp, wildcard and fuzzy queries, plus term, numeric and date ranges, boolean field queries, and compound conjuncts, disjuncts and must/should/must_not queries. There is a query string syntax for callers who prefer text. Scoring is configurable: the README points to tf-idf and bm25 models in docs/scoring.md.

The interesting part is the vector path. bleve supports approximate k-nearest neighbors through vector search, and the repository has search_knn.go, search_no_knn.go, mapping_vector.go and rescorer_knn_test.go, which suggests the KNN search path is compiled conditionally. go.mod lists github.com/blevesearch/go-faiss, so the vector implementation depends on FAISS bindings. The README also describes hybrid search combining exact and semantic results, with RRF (Reciprocal Rank Fusion) and RSF (Relative Score Fusion) documented in docs/score_fusion.md. If you plan to run vector search, that FAISS dependency is the first thing to check on your target platform, because cgo bindings change what a build requires.

Installing the bleve CLI and running a first query

The library is imported as github.com/blevesearch/bleve/v2, and the module requires Go 1.25.0 according to go.mod. For a first look, the README gives a CLI install command:

go install github.com/blevesearch/bleve/v2/cmd/bleve@latest

That puts a bleve binary in your Go bin directory. Running bleve --help prints the command list the README reproduces, including bulk, check, count, create, dictionary, dump, fields, index, mapping, query and registry. The registry command is the one to run early, because it "lists the bleve components compiled into this executable" and tells you which analyzers and index types you actually have.

The README documents the create, bulk, count and query commands. Creating an index and adding documents uses the same binary, and bulk loads from newline delimited JSON files, which is the quickest way to get real data in without writing Go:

bleve create example.bleve
bleve bulk example.bleve example.ndjson
bleve count example.bleve
bleve query example.bleve "bleve"

The count command should print the number of documents you fed in; if it prints zero, the bulk step did not parse your file and the README's bulk description (newline delimited JSON) is the place to look. The query command runs a query string against the index, and dump shows the stored contents if you want to confirm what was indexed.

From Go, the README's two examples are the whole first-use story. Indexing a struct:

message := struct {
    Id   string
    From string
    Body string
}{
    Id:   "example",
    From: "[email protected]",
    Body: "bleve indexing is easy",
}

mapping := bleve.NewIndexMapping()
index, err := bleve.New("example.bleve", mapping)
if err != nil {
    panic(err)
}
index.Index(message.Id, message)

And querying it back:

index, _ := bleve.Open("example.bleve")
query := bleve.NewQueryStringQuery("bleve")
searchRequest := bleve.NewSearchRequest(query)
searchResult, _ := index.Search(searchRequest)

The second snippet ignores both errors, which is fine in a README and wrong in production. index.Search returns a result and an error; handle the error, because a closed or corrupted index surfaces there.

Where bleve is the wrong tool

bleve is a library with a local index, and that single fact rules it out for some jobs. There is no server mode in the README, no replication, no sharding, no cluster coordination. If you need several machines to serve one corpus with failover, bleve does not give you that, and bolting it on yourself means solving distributed consistency problems the project never set out to solve.

The index is also local to a process. Multiple processes writing the same directory is not something the README addresses, and the CLI commands (create, bulk, index, query) all operate on a path, which implies single-writer assumptions. A web service with several replicas each holding its own copy will drift unless you rebuild or synchronize the index yourself.

Memory and disk are the other boundary. An in-process index competes with your application for the same resources, and the README does not publish sizing guidance. For a corpus that fits comfortably on one machine this is a feature; for one that does not, it is a wall. Vector search adds a second constraint: the FAISS dependency in go.mod means cgo and a native library, which complicates static builds and cross-compilation in a way that pure Go dependencies do not. The repository even splits KNN search into search_knn.go and search_no_knn.go, which is consistent with the feature being optional at build time.

Finally, relevance tuning is your job. bleve exposes tf-idf and bm25 and lets you configure analyzers, but it does not ship a relevance team. If your requirement is "results at least as good as the search engine we already run", moving to a library means owning that work.

bleve compared with running a separate search service

The real alternative for most teams is a standalone search server, typically Elasticsearch or OpenSearch, or a hosted search API. The difference is architectural, not cosmetic. A search server is a process you deploy, scale and monitor separately; it speaks HTTP or a client protocol; it handles sharding and replication for you; and it carries a JVM or a managed runtime plus its own operational surface. bleve inverts every one of those points. It has no network protocol in the README, no cluster features, and no separate process. You get a Go package and a directory.

That inversion is the whole trade. With a search server you pay in deployment complexity and gain horizontal scale and a mature ecosystem of plugins and tooling. With bleve you pay in scale ceiling and gain a single binary, no network hop between your data and the index, and no second system to keep alive. For a desktop application, a CLI tool, an embedded analytics feature or a service whose corpus is measured in gigabytes rather than terabytes, the bleve side of that trade is usually the better one. For a multi-tenant search product with strict uptime targets, it is not.

A narrower comparison is with other Go search libraries. bleve's distinguishing feature set, based on the README, is breadth: text, numeric, datetime, boolean, geopoint, geoshape, IP and vector fields in one mapping, with hybrid exact plus semantic search and RRF/RSF fusion documented in docs/score_fusion.md. A library that only does inverted text search will not cover geo distance queries or KNN in the same index. That breadth is the reason to pick bleve over something smaller, and the reason its dependency list is long.

Maintenance, releases and what Apache-2.0 means here

The repository is not archived, and the last push was on 2026-09-21. Releases are frequent rather than annual: v2.6.1 on 2026-08-24, v2.6.0 on 2026-04-30, and v2.5.7 on 2025-12-16. The module path carries a v2 major version, so upgrades within v2 should follow Go module semantics, but the index format is a separate concern. The go.mod file still depends on zapx segment modules v11 through v17, which means indexes written by older bleve versions remain readable through those format packages. That is reassuring for upgrade cost, but it also means the binary carries code for many segment formats.

Upgrade cost in practice comes from two places. First, the mapping: if you change analyzers or field types, existing indexed documents keep the old analysis until reindexed, and the README does not describe an in-place remap command. Expect to rebuild the index from source data when mappings change. Second, the CLI and library are versioned together, so a bleve binary built at one version and a library at another can disagree about index compatibility. Pinning both is the safe habit.

The licence is Apache License Version 2.0, stated in the README and present as LICENSE at the repository root. Apache-2.0 is permissive: it allows commercial and closed-source use, and it includes an express grant of patent rights from contributors. It also requires that you keep the licence and notice files and state significant changes when you redistribute. The go.mod dependency list matters here too, because bleve pulls in many modules, each with its own licence; go-faiss in particular is a binding to a native library, and native libraries sometimes carry terms that differ from the Go wrapper. This is not legal advice, and the practical step is to run your own licence scan over the full dependency graph rather than assuming the top-level Apache-2.0 covers everything.

Editorial conclusion

Adopt bleve when your search corpus fits on the same machine as your Go service and you want the index to live in the process, with text, numeric, geo, IP and vector fields under one mapping. Do not adopt it as a cluster: the README describes a library and a CLI, and nothing in it covers replication, sharding or a network API, so a multi-node search tier is out of scope. Before committing, verify three things against your own data: that the language you need appears in the analyzer list, that the scorch index format suits your write pattern, and that you can live with the Apache-2.0 attribution requirements in the LICENSE file. Then run bleve create and bleve query on a sample of your real documents, because the mapping you choose is the decision that is hardest to change later.

Frequently asked questions

Official sources

1. blevesearch/bleve on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases