# Praxis Java Filter Query Authoring

> Praxis Java Filter Query Authoring

- Skill: `codexrodrigues/praxis-java-filter-query-authoring` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-java-filter-query-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-java-filter-query-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-java-filter-query-authoring

---


# 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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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](references/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.

