# Queryable

> Queryable is a Maven plugin that generates Hibernate filters and JAX-RS controller code for Quarkus applications using Hibernate Panache.

Current supported examples:
- Queryable: 3.0.12
- Quarkus: 3.39.5
- Java: 21

## Primary documentation

- [Getting Started](https://queryable.dev/docs/getting-started.html): Create and configure a Quarkus project with Queryable from scratch.
- [Documentation](https://queryable.dev/docs/): Installation, source generation, configuration, and annotation reference.
- [QEEX reference](https://queryable.dev/docs/#qeex): Optional REST error catalogs, generation commands, configuration and current limitations.
- [QEEX example](https://queryable.dev/docs/getting-started.html#qeex): Customer error catalog, CDI injection, endpoint and expected HTTP 404 response.
- [Agent guide](https://queryable.dev/AGENTS.md): Deterministic commands, repository layout, validation, and behavioral constraints in AGENTS.md format.
- [Agent guide source](https://github.com/n-essio/queryable/blob/main/AGENTS.md): Version-controlled source of the agent guide.
- [API rules](https://github.com/n-essio/queryable/blob/main/API.MD): Generated query parameter rules and examples.
- [Source repository](https://github.com/n-essio/queryable): Plugin implementation and templates.

## Essential commands

Initialize Queryable in a consuming project:

    ./mvnw queryable:install

Process every eligible model class:

    ./mvnw queryable:source

Process selected model classes by simple name:

    ./mvnw queryable:source -Dclasses=Customer,Order

Exclude selected model classes:

    ./mvnw queryable:source -DexcludeClasses=Customer,Order

The classes options accept comma-separated simple class names. Whitespace and duplicates are ignored. Explicitly excluded classes are not parsed or regenerated. excludeClasses takes precedence over classes and @QInclude; @QExclude remains authoritative.

Since 3.0.10, REST V3 entity imports use the package declared in the entity source, including model subpackages and custom model packages. Rerun queryable:source after upgrading to repair legacy entity imports in existing services; REST resource packages and application constant imports remain unchanged.

## Model subpackages (since 3.0.12)

For V3 queryable:source and V4 queryable:sourcev4, enable useModelSubPackage in the
plugin configuration or pass -DuseModelSubPackage=true. Default false keeps REST
services flat. True mirrors the entire entity directory relative to the configured
model root beneath the REST root, with arbitrary names and multiple levels.
Example: xxx.model.finance.monthly.Report -> xxx.service.rs.finance.monthly.ReportServiceRs.
Custom sourceModelDirectory and sourceRestDirectory are supported. Root entities,
HTTP URLs, entity packages and application constants remain unchanged.
Switching the option relocates existing services in either direction, preserving
manual methods, QExclude and V3 preserved-filter hooks. Two existing copies cause an
error. Update consuming-code imports and package-local dependencies yourself.
Duplicate simple entity names remain unsupported.
Guide: https://queryable.dev/docs/#model-subpackages

## Manual V3 filters (since 3.0.11)

Use @QPreserveFilters({"Entity.filter.name"}) on the entity to retain existing
@FilterDef/@Filter pairs by exact literal name, including custom parameters and SQL.
Use @QPreservedFilter("Entity.filter.name") on a concrete non-static void method
declared in the REST service taking PanacheQuery<Entity>. Generated getSearch calls
hooks after automatic filters, in declaration order; manual methods are not rewritten.
Move existing inline custom blocks to hooks before regenerating. Without a hook,
definitions remain but are not automatically activated (warning). Invalid names,
missing definitions, duplicate bindings and invalid signatures fail generation.
Plural list names and individual temporal bounds are supported. @QExclude on
getSearch still preserves the whole method. V4 and pre-query HQL hooks are not supported.
Guide: https://queryable.dev/docs/#preserve-filters

## Optional QEEX

After queryable:install, install exception support:

    ./mvnw queryable:qeexinstall

Warning: this deletes and replaces {groupId}.api.service.RsResponseService. Preserve customizations first.

Define an interface annotated with the generated QeexExceptionBundle and QeexMessage annotations, using explicit stable IDs and HTTP statuses, then generate its CDI implementation:

    ./mvnw queryable:qeexsource

Keep src/main/resources/application.properties present and configure qeex.project, qeex.default.id, qeex.default.code, qeex.default.message and qeex.default.language. Edit the interface, not the generated implementation.

Throw QeexWebException out of the endpoint to preserve its HTTP status; RsResponseService error helpers return HTTP 500. Generated methods do not apply per-message overrides or automatic translations. The mutable application-scoped language filter is not request-isolated, and the exception mapper does not escape JSON message values. The catch-all mapper leaves the error ID at 0. See the QEEX reference before production use.

## Authoritative locations

- Maven goal: src/main/java/it/ness/queryable/plugin/v3/SourceV3Mojo.java
- Source selection: src/main/java/it/ness/queryable/util/ModelFilesV3.java
- Annotation definitions: src/main/java/it/ness/queryable/annotations/
- Generated templates: src/main/resources/templates/