bboss-elasticsearch: a high level Java REST client for Elasticsearch

A mybatis-style client for a search engine

bboss-elasticsearch is a high level Java REST client for Elasticsearch, and the README describes how it works in one line: it operates and accesses elasticsearch in a way similar to mybatis.

That analogy is the product. The official Elasticsearch Java client is a thin, low level wrapper over the REST API, which is the right choice when you want control and the wrong choice when you want to map documents to objects and write queries in a familiar shape. bboss takes the mybatis route: a mapping layer between your Java objects and index documents, with a DSL that reads closer to a persistence framework than to a raw HTTP client.

The scope is broad enough to be worth reading twice. The README lists multi-cluster and multi-datasource support, automatic index management, several pagination mechanisms, straightforward CRUD, scripts, SQL, JDBC, highlighting, weighting, aggregation, IP and GEO location handling, and parent-child nesting. That is a feature list closer to a full data access framework than to a client library.

The audience is a Chinese-speaking Java team, mostly, since the README is written in Chinese and the surrounding community links point at Gitee and QQ and WeChat groups. The English README is a summary rather than the primary document, and the full documentation lives at esdoc.bbossgroups.com. If your team reads English documentation only, the friction here is real but manageable, because the code and the API are ordinary Java.

The project is Apache 2.0 licensed, the primary language is Java, the homepage is bbossgroups.com, and the last push was on 2026-09-15.

One codebase across Elasticsearch, Easysearch and OpenSearch

The compatibility table is the most useful part of the README, because it is unusually honest about the shape of the support matrix.

The stated environmental requirements are JDK 1.8 or newer, and Elasticsearch 1.X, 2.X, 5.X, 6.X, 7.x, 8.x and 9.x and later. Easysearch 1.x and 2.x are supported, OpenSearch 1.x and 2.x are supported, and the Spring Boot line is 1.x, 2.x, 3.x and later.

The table then maps each Elasticsearch major version to a bboss row, and in every row the bboss column reads all, meaning the same bboss version works with every supported backend generation. So one dependency set covers Elasticsearch 1.x through 9.x, and separately Easysearch 1.x and 2.x, and OpenSearch 1.x and 2.x.

That is an unusual commitment. Search engines change their APIs between major versions, and supporting nine generations of Elasticsearch means the client has to deal with the differences in mapping types, search syntax and client transport. The cost of that breadth is a codebase that is considerably larger than a thin client, and the benefit is that a team upgrading a cluster from 6.x to 8.x does not have to rewrite its data access layer.

Note the gap in the table. There is a row for Elasticsearch 3.x, then the next listed is 5.x. Elasticsearch 4.x was never released, so the omission is not a gap in coverage but a reflection of the upstream release history.

The homepage is bbossgroups.com, and the framework is part of a family of bboss projects, with a separate one for data collection and streaming batch processing linked from the README.

Four Spring Boot starters, one per generation

The repository layout explains how the framework is packaged, and the Spring Boot story is the clearest part of it.

There are separate directories for the core REST client, bboss-elasticsearch-rest, and for the entity mapping layer, bboss-elasticsearch-rest-entity. There is a bc module, bboss-elasticsearch-rest-bc, and a booter module, bboss-elasticsearch-rest-booter, for the Spring integration that is not tied to a specific Boot version.

On top of that sit three starters: bboss-elasticsearch-spring-boot-starter for Spring Boot 1.x and 2.x, bboss-elasticsearch-spring-boot3-starter and bboss-elasticsearch-spring-boot4-starter. The distinction matters more than it sounds. Spring Boot 1.x and 2.x use javax packages, while Boot 3.x moved to jakarta, so a single starter cannot serve both without shading or reflection tricks. Separate starters per Boot major version is the honest way to handle that split, and the presence of a Boot 4 starter says the project is tracking the current Spring Boot line rather than sitting on the previous one.

The build is Gradle, with build.gradle, settings.gradle and gradle.properties at the root, and there is a bboss.gpg file for signing. The repository also carries a docs/ directory, a README_zh_CN.md alongside the English README, and a.gitattributes file.

The other side of the packaging is the example set, which is scattered across GitHub and Gitee. There is a Java project example, a Spring Boot 1.x, 2.x and 3.x example, a Spring Boot 3.x web service example, and the eshelloword starters in both the Boot 2 and Boot 3 flavours. The documentation site points to a quick start, a build-from-source guide, a development introduction, and two case-sharing write-ups for Spring Boot integration and for quickly wiring up the Elasticsearch REST API into a common project.

What the framework gives you beyond a REST wrapper

The feature list is where the difference between this and a plain client shows up, and it is worth separating the categories rather than reading it as a list.

The persistence-shaped features are the core: straightforward CRUD, entity mapping, several pagination mechanisms, and automatic index management, which means the framework will create and maintain the index rather than leaving you to write the mapping and settings by hand. The README calls this automatic index management, and for teams that have been through an index mapping migration this is usually the feature that decides the question.

The query surface is the second group. There is a script API, a SQL layer, a JDBC entry point, highlighting for search results, weighting to influence scoring, and aggregation support. The SQL and JDBC pieces let people who came from a relational background stay in familiar syntax, at the cost of a translation layer between their query and what the engine actually executes.

The third group is the domain-specific one: IP handling and GEO location, and parent-child nested documents, which is the model Elasticsearch uses for things like a question and its answers. Those are the features that come from the framework having been built for real applications rather than for demonstration.

Multi-cluster and multi-datasource support is the fourth, and for a platform team running more than one search cluster that is often the deciding feature.

What the README does not offer is a performance comparison against the official client, nor a statement about how the framework behaves against a cluster under heavy indexing load. The claim of being a high performance client is in the repository description, and the technical documentation site is where you would look for numbers.

Documentation, community and the licensing position

The support and community channels are worth noting because they are all Chinese-platform based, and that shapes who can realistically get help.

The README lists a set of QQ groups for exchange, with several group numbers, along with a WeChat group, and an exchange community promoted through images linking to Douyin and a video account. The primary documentation is at esdoc.bbossgroups.com, with the quick start, the build guide, the development introduction and the API case studies all hosted there. The project homepage is bbossgroups.com.

There is also a support and sponsorship section that asks users to star the project and share it, to donate through a crowdfunding platform, or to buy the author a coffee by scanning a payment code. The README states the donations go towards the bboss community, the annual QQ group fee, and the website's cloud server rental.

The licence is the cleanest part. The BBoss Framework is released under version 2.0 of the Apache License, with a LICENSE file in the repository, and the README links the Apache 2.0 text. There is also a Star History chart at the bottom of the readme, which is a nice signal of an active project timeline.

The release history is regular: v7.3.9 in July 2025, v7.3.3 in February 2025 and v7.3.1 in January 2025. The version numbers do not track the Elasticsearch versions, which is consistent with the compatibility table, where one bboss release serves many engine generations. The absence of GitHub releases in the release list does not mean no artifacts are published, since the framework is consumed as a Maven or Gradle dependency, but it does mean the version history is the place to look rather than a release feed.

Editorial conclusion

Adopt bboss-elasticsearch if you are writing Java against Elasticsearch or Easysearch and want a mybatis-style client with a broad feature set, managed indices and multi-cluster support rather than the official low level client. Do not adopt it if you want the smallest possible dependency surface, since the framework covers a very wide range of functionality, and do not expect an English-first documentation experience. Verify first that your Elasticsearch, Easysearch or OpenSearch version falls in the compatibility table, that the Spring Boot starter matching your Boot major version is the one you add, and that the build from source path documented at esdoc.bbossgroups.com still applies to the version you are pinning.

Frequently asked questions

Official sources

1. bbossgroups/bboss-elasticsearch on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases