# troyzhxu/bean-searcher

🔥🔥🔥 A read-only ORM for complex queries in Java

Repository: https://github.com/troyzhxu/bean-searcher
Canonical: https://ross.abutalabs.com/products/bean-searcher
Homepage: https://bs.zhxu.cn/en/
Language: Java
License: Apache-2.0
License Family: permissive
Topics: java, spring-boot, graphql, search-framework, declarative-search, list-query, orm-framework, readonly-orm, dynamic-sql
Last push: 2026-08-12T03:34:38+00:00

## Health v2 (maintenance only)
Score: 97/100 (v2, computed 2026-09-03T02:20:16.233290+00:00)
- activity 97, release rhythm 95, longevity 100
- inputs: {"age_days": 3368, "days_push": 21, "days_rel": 38, "gap_med": 8.5, "n_releases_24m": 25}
- flags: none
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 1384, forks 148 (observed 2026-08-28T04:04:34.732237+00:00)

## What it is
Bean Searcher is a read-only ORM framework for Java focused on declarative complex list queries, where entities define search boundaries and request parameters drive filtering, sorting, pagination, and joins. It generates SQL automatically, integrates non-invasively with Spring Boot alongside MyBatis or JPA, and includes built-in protections like SQL injection prevention and deep-offset throttling.

## Use cases
- build multi-condition list query endpoints without if-else SQL stitching
- query across multiple tables with annotation-declared joins
- let frontend dynamically combine filters, sorting, and pagination without backend changes
- add searchable list APIs to existing Spring Boot apps alongside MyBatis or JPA
- implement paginated admin data tables with filtering and stats
- prevent SQL injection and deep pagination performance issues by default

## When to choose
- you need complex list/retrieval queries in Java with minimal boilerplate
- your frontend needs flexible, parameter-driven filtering and sorting
- you want a read-only query layer that coexists with your existing ORM

## When to avoid
- you need full CRUD with writes and transactional entity management
- you prefer hand-tuned SQL or heavy control over generated queries
- your project is not on the JVM/Java ecosystem

## Facets
- artifact type: framework
- maturity: active
- function: orm, database, search-engine, web-framework, api-framework
- domain: web-development, backend, databases, developer-tools
- platform: jvm, cross-platform
- tags: declarative-search, readonly-orm, dynamic-sql, list-queries, spring-boot-starter, pagination, multi-table-joins, search, spring-boot

## Member repositories
- troyzhxu/bean-searcher (main) score 97

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:04:34.732237+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-30T04:39:59.746863+00:00, confidence not recorded.
  - readme: https://github.com/troyzhxu/bean-searcher (fetched 2026-08-28T04:04:34.732237+00:00, sha 40b5a926fadd)
  - homepage: https://bs.zhxu.cn/en/ (fetched 2026-08-29T11:55:42.679414+00:00, sha 5f571c2a6dfa)
- Data as of 2026-08-30T08:39:29.467469+00:00.