Praxis Java Filter Query Authoring
Treat a filter as a public query contract that expresses a business question.
Do not treat it as a form-shaped request object, a reduced create DTO, or a
collection of controller-specific query parameters.
Start With Query Meaning
Inspect the resource operations, entity/view model, existing filter DTO, service,
repository, relevant database evidence, schema projection, UI consumer, and
focused tests. For a legacy screen, distinguish filters that affect result scope,
sort, option dependencies, authorization, or only local presentation.
Create a dedicated GenericFilterDTO. For every candidate criterion, record the
business question, target entity property, expected type/cardinality, predicate,
null/empty behavior, governing scope, permitted sort, and UI/option-source
consumer. Do not expose raw technical columns (version, internal hashes), but never produce a skeletal 2- to 4-field FilterDTO or limit filtering to mechanical 1:1 column mappings. Analyze the business domain and the entity relationship graph (@ManyToOne, @OneToMany, @Embedded) to implement:
- Unified Broad / Omnibox Search in a Single Field (
@Filterable(relations = {...})): In enterprise applications, users must be able to type a term in a single field (e.g. searchTerm / buscaAmpla / identificacaoOuFamiliar) to match across civil name, social name, surname, mother's/father's name, dependent/relative name, or document (@Filterable(operation = FilterOperation.LIKE, relations = {"fullName", "socialName", "motherName", "fatherName", "dependents.fullName", "taxId"})) without having to choose separate inputs for each semantic role;
- Multi-Operator Coverage on the Same Attribute: combine
LIKE + STARTS_WITH + EQUAL + IN on codes/names; BETWEEN (DATE_RANGE) + ON_DATE + IN_LAST_DAYS (recent events) + IN_NEXT_DAYS (expiring contracts/vacations/reviews radar) on dates; BETWEEN (PRICE_RANGE) + GREATER_OR_EQUAL + LESS_OR_EQUAL on amounts/quantities; IS_NULL / IS_NOT_NULL for data completeness/exception audits (e.g., missing bank account, missing manager, active/open-ended records); and SIZE_GT / SIZE_EQ / SIZE_LT on child collections;
- Cross-Entity Relational Filters: traverse 1 to 3 relationship levels (
relation = "department.costCenter.region", relation = "dependents.relationshipType", relation = "assignments.status"), plus @CustomFields when JSONB is present.
Before adding a field, operator, payload form, query endpoint, or sort rule,
classify it as ja-suportado-so-ux,
ja-suportado-mal-nomeado-ou-mal-materializado,
suportado-parcialmente, or lacuna-real-de-contrato. A new predicate or
public filter shape belongs in praxis-metadata-starter, not in a host-local
specification helper.
Author The Canonical Query Contract
- Use
@Filterable only on a dedicated filter DTO field that the backend
actually executes through the resource query path. Choose its
FilterOperation from the verified business question, never from a field
suffix or screen label.
- Use
relation for an entity relationship path or a readable DTO alias that
targets a different entity property. For example, statusIn must declare
relation = "status"; a relation identifier can target employee.id.
Do not rely on a DTO alias being guessed from a property name.
- Match payload shape to the selected operation: scalar for equality, text
search or relative-day count; list for
IN, NOT_IN, and ranges; explicit
boolean activation for null/boolean predicates. Keep a range's boundary
semantics and types documented in @Schema and UI metadata.
- Use the starter's
GenericSpecificationsBuilder through the canonical base
service. It maps annotated fields to predicates and remaps sortable aliases
using relation. Do not recreate Specifications in each controller unless
source evidence establishes a genuine unsupported query need.
- Use the registered filter payload normalizers for canonical range and
relative-period payload forms. Keep time zone, clock, closed/open bounds, and
invalid payload behavior covered by tests; do not normalize dates in a
browser-only helper or silently reinterpret a legacy value.
- Build pagination through the resource query controller and
PageableBuilder.
Preserve the resource default sort when the request omits sorting. Test each
public sort alias against the target property and relation. An option-source
request is a stricter contract: use its published sort key and
OptionSourceRequestValidator; never pass unvalidated sort to a provider.
- Connect relationship filters to their governed option source only when value,
display, dependency, filter and by-ids reload contracts all exist. A filter
DTO does not replace an option source descriptor.
- For row-level authorization on
POST /{resource}/filter, override
resolveResourceFilterAccessScope() in the resource service and return an
explicit ResourceFilterAccessScope.unrestricted(), .denied(), or
.restricted(specification) from authenticated server context. The base
service composes this boundary with the functional filter and reapplies it
when loading missing includeIds.
Read predicate-and-proof-matrix.md
when selecting operations, modeling aliases/ranges/relative periods, or choosing
the smallest proof.
Preserve Semantic And Security Boundaries
praxis-metadata-starter owns GenericFilterDTO, @Filterable, predicate
semantics, normalizers, base query services, pagination integration, filtered
schema projection, and x-ui query metadata.
- The host owns the verified domain meaning, repository/view eligibility,
authorization context, and resource-specific default sort. Do not publish
confidential, tenant-crossing, audit-only, or prohibited fields simply because
JPA can filter them.
- A
FilterDTO is a client-controlled functional query, never an authorization
boundary. includeIds may rehydrate an authorized selected value outside the
current functional filter, but it must never materialize a row outside the
server-resolved ResourceFilterAccessScope. Do not solve this by applying the
full functional filter to the selected-ID query or by hiding external rows in
Angular.
- The resource-filter scope also applies to
/options/filter, which reuses the
filtered resource query. It does not implicitly govern independent /by-ids,
/all, /filter/cursor, /locate, stats, or option-source by-ids paths;
audit and enforce each published surface through its canonical contract.
- For a governed bulk QUERY candidate, reuse the resource's canonical
GenericFilterDTO and predicate semantics when they exist. For a new
resource without that DTO, use one closed typed filter with a single
predicate interpretation for its selection; if it also exposes a resource
filter, keep those predicates aligned rather than adding a parallel dialect.
The Quickstart ReferenceCatalogItemProvider.Filter is a
candidate example, pending its own HTTP proof. Do not treat
ResourceFilterAccessScope, a public /filter/cursor keyset, or includeIds
hydration as authorization or population evidence for a bulk command. The
host must independently combine the strict functional filter with its current
grant, apply exclusions, order IDs numerically, and freeze the complete
authorized manifest in the same writable RR capture transaction after the
durable control/quota locks. In the MissionParticipant pilot, wire exclusions
use its Integer codec's full int32 range, including zero and negative values;
missing IDs are bounded no-ops, while that domain's FK filter IDs require
positive integers. Other resources follow their own identity codec. A public
page cursor never becomes a bulk selection or authorization token.
- A continuation cursor carries page state; it is never an authorization grant.
Protect sensitive claims for confidentiality and integrity, bind the token to
its purpose and historical resource/query scope, and compare its effective
scope with the grant recomputed from the current authenticated server context
on every page. Never rebuild authorization from cursor claims or accept a
bearer cursor by itself. Perform the normal scoped lookup and current
authorization before mapping an authenticated expired cursor to a status that
could reveal resource existence. Define TTL, key retention, and fleet-wide
rotation before enabling a public cursor; keep tokens and claims out of logs,
metrics, and traces. A cursor remains replayable during its validity unless a
separate durable single-use contract is explicitly implemented.
praxis-ui-angular materializes published filter metadata. It does not infer
a predicate from labels or construct an undocumented payload dialect.
Do not route primary user intent, filter selection, or target resolution through
keyword lists, regexes, aliases, or fuzzy matching. Resolve scope through the
resource, schema, governed catalog, filter contract, and option-source metadata;
text matching can only assist after that scope is established.
Prove Query Behavior
Prove more than a non-empty page. Cover the annotated predicate against known
fixtures, the alias/relation target, null/empty behavior, pagination/default sort,
one invalid or unsupported payload, and authorization/dependency constraints when
applicable. For ranges or relative periods, test normalization and boundary/time
semantics. For public filter-schema changes, prove /schemas/filtered and the
direct runtime consumer or state why it is unaffected.
When ResourceFilterAccessScope is involved, use a real JPA/service or HTTP
fixture with at least two scopes. Prove the normal page, an authorized
includeIds value outside the functional filter, an external ID, a mixed
authorized/external request, null or empty IDs, denied scope, explicit global
scope, and a read-only resource. Keep option-source tests green and validate the
downstream host against the exact published starter artifact.
For bulk QUERY adoption, additionally prove original-token rejection before
Jackson coercion, frozen filter/exclusions and numeric ordinal/ETag manifest,
grant before ordered bounded SQL, no filter rerun on confirmation, and safe
whole-manifest read denial after coverage loss. Inspect
MissionParticipantQueryFilter, MissionParticipantUniformQueryShapeTest,
MissionParticipantUniformQueryHttpPostgresTest and the Metadata
JdbcBulkUniformQueryPostgresTest; distinguish private candidate evidence
from public SDK availability. The host's 200-target capture is not proof of a
200-target confirmation or a higher execution budget.
Use focused starter tests for GenericSpecificationsBuilder, range/relative
normalizers, PageableBuilder, FilterRequestBodyAdvice, and affected resource
services/controllers. Add a quickstart or host integration proof when the change
is public or legacy-derived. Review HTTP examples and docs only when they expose
the changed contract.
Companion Skills
praxis-java-resource-authoring: resource identity, selected base service,
operation matrix, and end-to-end proof.
praxis-dto-annotations: semantic descriptions, UI controls, governance, and
filter DTO annotation quality.
praxis-metadata-resource-baseline: query controller/service behavior,
HATEOAS, stats, and export boundaries.
praxis-metadata-schema-contracts: filtered schema, operation references,
OpenAPI, ETag, and schema hash.
praxis-metadata-domain-option-sources and
praxis-resource-entity-lookup-backend: governed lookup and option-source
filtering/reload contracts.
Close with a predicate matrix, source evidence, query/authorization decision,
schema and HTTP proof, and any real platform gap. A filter is ready when a
consumer can ask the intended business question predictably, not when a request
parameter happens to reach a repository.
1---2name: praxis-java-filter-query-authoring3description: "Use when implementing, auditing, or migrating Praxis Java resource filters and queries: dedicated GenericFilterDTO contracts, @Filterable predicates and relations, ranges, relative periods, pageable sorting, server-side ResourceFilterAccessScope, includeIds hydration, filtered schemas, option-source dependencies, and focused HTTP proof in a Spring host or praxis-metadata-starter."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-java-filter-query-authoring6---78# Praxis Java Filter Query Authoring910Treat a filter as a public query contract that expresses a business question.11Do not treat it as a form-shaped request object, a reduced create DTO, or a12collection of controller-specific query parameters.1314## Start With Query Meaning1516Inspect the resource operations, entity/view model, existing filter DTO, service,17repository, relevant database evidence, schema projection, UI consumer, and18focused tests. For a legacy screen, distinguish filters that affect result scope,19sort, option dependencies, authorization, or only local presentation.2021Create a dedicated `GenericFilterDTO`. For every candidate criterion, record the22business question, target entity property, expected type/cardinality, predicate,23null/empty behavior, governing scope, permitted sort, and UI/option-source24consumer. Do not expose raw technical columns (`version`, internal hashes), but **never** produce a skeletal 2- to 4-field `FilterDTO` or limit filtering to mechanical 1:1 column mappings. Analyze the business domain and the entity relationship graph (`@ManyToOne`, `@OneToMany`, `@Embedded`) to implement:25- **Unified Broad / Omnibox Search in a Single Field (`@Filterable(relations = {...})`):** In enterprise applications, users must be able to type a term in a single field (e.g. `searchTerm` / `buscaAmpla` / `identificacaoOuFamiliar`) to match across civil name, social name, surname, mother's/father's name, dependent/relative name, or document (`@Filterable(operation = FilterOperation.LIKE, relations = {"fullName", "socialName", "motherName", "fatherName", "dependents.fullName", "taxId"})`) without having to choose separate inputs for each semantic role;26- **Multi-Operator Coverage on the Same Attribute:** combine `LIKE` + `STARTS_WITH` + `EQUAL` + `IN` on codes/names; `BETWEEN` (`DATE_RANGE`) + `ON_DATE` + `IN_LAST_DAYS` (recent events) + `IN_NEXT_DAYS` (expiring contracts/vacations/reviews radar) on dates; `BETWEEN` (`PRICE_RANGE`) + `GREATER_OR_EQUAL` + `LESS_OR_EQUAL` on amounts/quantities; `IS_NULL` / `IS_NOT_NULL` for data completeness/exception audits (e.g., missing bank account, missing manager, active/open-ended records); and `SIZE_GT` / `SIZE_EQ` / `SIZE_LT` on child collections;27- **Cross-Entity Relational Filters:** traverse 1 to 3 relationship levels (`relation = "department.costCenter.region"`, `relation = "dependents.relationshipType"`, `relation = "assignments.status"`), plus `@CustomFields` when JSONB is present.2829Before adding a field, operator, payload form, query endpoint, or sort rule,30classify it as `ja-suportado-so-ux`,31`ja-suportado-mal-nomeado-ou-mal-materializado`,32`suportado-parcialmente`, or `lacuna-real-de-contrato`. A new predicate or33public filter shape belongs in `praxis-metadata-starter`, not in a host-local34specification helper.3536## Author The Canonical Query Contract37381. Use `@Filterable` only on a dedicated filter DTO field that the backend39 actually executes through the resource query path. Choose its40 `FilterOperation` from the verified business question, never from a field41 suffix or screen label.422. Use `relation` for an entity relationship path or a readable DTO alias that43 targets a different entity property. For example, `statusIn` must declare44 `relation = "status"`; a relation identifier can target `employee.id`.45 Do not rely on a DTO alias being guessed from a property name.463. Match payload shape to the selected operation: scalar for equality, text47 search or relative-day count; list for `IN`, `NOT_IN`, and ranges; explicit48 boolean activation for null/boolean predicates. Keep a range's boundary49 semantics and types documented in `@Schema` and UI metadata.504. Use the starter's `GenericSpecificationsBuilder` through the canonical base51 service. It maps annotated fields to predicates and remaps sortable aliases52 using `relation`. Do not recreate Specifications in each controller unless53 source evidence establishes a genuine unsupported query need.545. Use the registered filter payload normalizers for canonical range and55 relative-period payload forms. Keep time zone, clock, closed/open bounds, and56 invalid payload behavior covered by tests; do not normalize dates in a57 browser-only helper or silently reinterpret a legacy value.586. Build pagination through the resource query controller and `PageableBuilder`.59 Preserve the resource default sort when the request omits sorting. Test each60 public sort alias against the target property and relation. An option-source61 request is a stricter contract: use its published sort key and62 `OptionSourceRequestValidator`; never pass unvalidated sort to a provider.637. Connect relationship filters to their governed option source only when value,64 display, dependency, filter and by-ids reload contracts all exist. A filter65 DTO does not replace an option source descriptor.668. For row-level authorization on `POST /{resource}/filter`, override67 `resolveResourceFilterAccessScope()` in the resource service and return an68 explicit `ResourceFilterAccessScope.unrestricted()`, `.denied()`, or69 `.restricted(specification)` from authenticated server context. The base70 service composes this boundary with the functional filter and reapplies it71 when loading missing `includeIds`.7273Read [predicate-and-proof-matrix.md](references/predicate-and-proof-matrix.md)74when selecting operations, modeling aliases/ranges/relative periods, or choosing75the smallest proof.7677## Preserve Semantic And Security Boundaries7879- `praxis-metadata-starter` owns `GenericFilterDTO`, `@Filterable`, predicate80 semantics, normalizers, base query services, pagination integration, filtered81 schema projection, and `x-ui` query metadata.82- The host owns the verified domain meaning, repository/view eligibility,83 authorization context, and resource-specific default sort. Do not publish84 confidential, tenant-crossing, audit-only, or prohibited fields simply because85 JPA can filter them.86- A `FilterDTO` is a client-controlled functional query, never an authorization87 boundary. `includeIds` may rehydrate an authorized selected value outside the88 current functional filter, but it must never materialize a row outside the89 server-resolved `ResourceFilterAccessScope`. Do not solve this by applying the90 full functional filter to the selected-ID query or by hiding external rows in91 Angular.92- The resource-filter scope also applies to `/options/filter`, which reuses the93 filtered resource query. It does not implicitly govern independent `/by-ids`,94 `/all`, `/filter/cursor`, `/locate`, stats, or option-source by-ids paths;95 audit and enforce each published surface through its canonical contract.96- For a governed bulk QUERY candidate, reuse the resource's canonical97 `GenericFilterDTO` and predicate semantics when they exist. For a new98 resource without that DTO, use one closed typed filter with a single99 predicate interpretation for its selection; if it also exposes a resource100 filter, keep those predicates aligned rather than adding a parallel dialect.101 The Quickstart `ReferenceCatalogItemProvider.Filter` is a102 candidate example, pending its own HTTP proof. Do not treat103 `ResourceFilterAccessScope`, a public `/filter/cursor` keyset, or `includeIds`104 hydration as authorization or population evidence for a bulk command. The105 host must independently combine the strict functional filter with its current106 grant, apply exclusions, order IDs numerically, and freeze the complete107 authorized manifest in the same writable RR capture transaction after the108 durable control/quota locks. In the MissionParticipant pilot, wire exclusions109 use its Integer codec's full int32 range, including zero and negative values;110 missing IDs are bounded no-ops, while that domain's FK filter IDs require111 positive integers. Other resources follow their own identity codec. A public112 page cursor never becomes a bulk selection or authorization token.113- A continuation cursor carries page state; it is never an authorization grant.114 Protect sensitive claims for confidentiality and integrity, bind the token to115 its purpose and historical resource/query scope, and compare its effective116 scope with the grant recomputed from the current authenticated server context117 on every page. Never rebuild authorization from cursor claims or accept a118 bearer cursor by itself. Perform the normal scoped lookup and current119 authorization before mapping an authenticated expired cursor to a status that120 could reveal resource existence. Define TTL, key retention, and fleet-wide121 rotation before enabling a public cursor; keep tokens and claims out of logs,122 metrics, and traces. A cursor remains replayable during its validity unless a123 separate durable single-use contract is explicitly implemented.124- `praxis-ui-angular` materializes published filter metadata. It does not infer125 a predicate from labels or construct an undocumented payload dialect.126127Do not route primary user intent, filter selection, or target resolution through128keyword lists, regexes, aliases, or fuzzy matching. Resolve scope through the129resource, schema, governed catalog, filter contract, and option-source metadata;130text matching can only assist after that scope is established.131132## Prove Query Behavior133134Prove more than a non-empty page. Cover the annotated predicate against known135fixtures, the alias/relation target, null/empty behavior, pagination/default sort,136one invalid or unsupported payload, and authorization/dependency constraints when137applicable. For ranges or relative periods, test normalization and boundary/time138semantics. For public filter-schema changes, prove `/schemas/filtered` and the139direct runtime consumer or state why it is unaffected.140141When `ResourceFilterAccessScope` is involved, use a real JPA/service or HTTP142fixture with at least two scopes. Prove the normal page, an authorized143`includeIds` value outside the functional filter, an external ID, a mixed144authorized/external request, null or empty IDs, denied scope, explicit global145scope, and a read-only resource. Keep option-source tests green and validate the146downstream host against the exact published starter artifact.147148For bulk QUERY adoption, additionally prove original-token rejection before149Jackson coercion, frozen filter/exclusions and numeric ordinal/ETag manifest,150grant before ordered bounded SQL, no filter rerun on confirmation, and safe151whole-manifest read denial after coverage loss. Inspect152`MissionParticipantQueryFilter`, `MissionParticipantUniformQueryShapeTest`,153`MissionParticipantUniformQueryHttpPostgresTest` and the Metadata154`JdbcBulkUniformQueryPostgresTest`; distinguish private candidate evidence155from public SDK availability. The host's 200-target capture is not proof of a156200-target confirmation or a higher execution budget.157158Use focused starter tests for `GenericSpecificationsBuilder`, range/relative159normalizers, `PageableBuilder`, `FilterRequestBodyAdvice`, and affected resource160services/controllers. Add a quickstart or host integration proof when the change161is public or legacy-derived. Review HTTP examples and docs only when they expose162the changed contract.163164## Companion Skills165166- `praxis-java-resource-authoring`: resource identity, selected base service,167 operation matrix, and end-to-end proof.168- `praxis-dto-annotations`: semantic descriptions, UI controls, governance, and169 filter DTO annotation quality.170- `praxis-metadata-resource-baseline`: query controller/service behavior,171 HATEOAS, stats, and export boundaries.172- `praxis-metadata-schema-contracts`: filtered schema, operation references,173 OpenAPI, ETag, and schema hash.174- `praxis-metadata-domain-option-sources` and175 `praxis-resource-entity-lookup-backend`: governed lookup and option-source176 filtering/reload contracts.177178Close with a predicate matrix, source evidence, query/authorization decision,179schema and HTTP proof, and any real platform gap. A filter is ready when a180consumer can ask the intended business question predictably, not when a request181parameter happens to reach a repository.