Diagnosing Query Behavior After Enabling Clarity in a Hibernate/Spring Application

Editorial note: This draft is flagged for human review. The supplied research brief describes a feature called "Clarity" — a naming and filter layer over Hibernate Criteria queries with Spring integration — but that feature is not part of standard Hibernate or Spring documentation this editor can confirm. The diagnostics below use only well-established Hibernate, Spring, and JDBC behavior, so the procedure is safe to follow even if the Clarity-specific claims in your source material turn out to be inaccurate. Verify the exact feature name and configuration keys against your dependency's actual documentation before applying fixes.

The recognizable condition

You enabled a query-clarity or query-logging feature (per the brief: standardized Criteria naming, a pluggable filter chain, and human-readable SQL output) and now one or more of these symptoms appears:

• Generated SQL differs from what the Criteria code implies — extra predicates, missing joins, or reordered filters.
• A query that was fast became slow, or the database reports a different execution plan for the same statement.
• Legacy code paths that bypass the new layer behave differently from paths that use it.
• Transactions appear to commit or roll back at unexpected boundaries after filters were added.

Cause and diagnostic table

Symptom	Likely cause	How to confirm
Extra or missing predicates in SQL	A filter in the chain applies implicitly to every query	Enable SQL logging and diff the statement against the Criteria definition
Slower query after enablement	Plan change from altered predicate order or added joins	Compare EXPLAIN output before/after
Inconsistent results across code paths	Legacy paths bypass the filter chain	Grep for direct Session.createQuery/raw SQL usage
Unexpected commit/rollback	Filter applied outside the transactional method, or a new transaction started inside a filter	Check @Transactional placement and Spring transaction logs

Ordered checks

1. Capture the actual SQL

Do not trust any "human-readable SQL" the feature claims to emit — capture what Hibernate really sends. In application.properties (Spring Boot):

spring.jpa.show-sql=false
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

show-sql writes to stdout and is fine for quick local checks; the logger categories route through your logging framework and include bound parameter values at TRACE, which is what you need to compare predicates. Run this in a staging environment — TRACE bind logging can expose sensitive parameter values, so do not enable it in production.

2. Diff the statement against expectations

For one affected query, write down the predicates your code expresses, then compare with the logged statement. Any predicate you did not write came from the filter chain or an interceptor. Disable filters one at a time (however your configuration exposes that) until the unexpected predicate disappears — that identifies the responsible filter.

3. Compare execution plans

Take the logged SQL, including real parameter values, and run it through your database's plan tool — EXPLAIN (PostgreSQL, MySQL) or EXPLAIN PLAN FOR (Oracle) — in a SQL client connected to a database with production-like data volume. Do this for the statement as generated before the feature was enabled (from version control or a feature flag) and after. A plan that switched from an index scan to a sequential scan, or changed join order, confirms a plan shift rather than a data-volume coincidence.

4. Verify transaction boundaries

Enable Spring transaction logging:

logging.level.org.springframework.transaction.interceptor=TRACE
logging.level.org.springframework.orm.jpa.JpaTransactionManager=DEBUG

Then exercise the affected operation and confirm you see exactly one "Creating new transaction" and one matching commit or rollback per logical unit of work. A filter that opens its own session or repository call with REQUIRES_NEW propagation will show up as a nested transaction — that is the classic cause of partial commits.

5. Audit bypass paths

Search the codebase for query construction that does not go through the new layer: entityManager.createNativeQuery, createQuery with hand-written JPQL, and JdbcTemplate usage. Each of these will ignore Criteria-level filters by design. Decide per call site whether the filter's semantics (e.g., tenant scoping, soft-delete exclusion) must be replicated manually.

Fixes tied to findings

• Unexpected predicate from a filter: reorder or narrow the filter so it applies only to the intended entity types; if the chain supports opt-out annotations, apply one to the affected query rather than disabling the filter globally.
• Plan regression: if the filter added a predicate on an unindexed column, add the index or rewrite the filter to use an indexed path. Re-run EXPLAIN to confirm the plan returns to an index scan.
• Nested transaction in a filter: move the filter's data access into the caller's transaction (default REQUIRED propagation) or make the filter read-only against already-loaded state.
• Bypass paths: migrate high-risk call sites (anything with security or tenancy implications) to the filtered path; document the rest as intentional exceptions.

How to verify the fix

Run the existing Hibernate query/integration test suite with the feature enabled and compare generated SQL against the recorded baseline from step 1. Then re-run the EXPLAIN comparison on the two or three most important queries. Both the SQL text and the plans should match your expectations; a green test suite alone does not catch plan regressions, because tests usually run against small datasets where any plan is fast.

Escalation criteria

Escalate to the library's maintainers or your platform team when: the generated SQL cannot be explained by any documented filter; plan regressions persist after indexing; or transaction logs show the feature starting transactions you cannot attribute to any configuration. Before escalating, capture the logged SQL, the plan output, the dependency version, and a minimal reproducer — and confirm the feature's exact name and version, since the terminology in the original brief could not be verified against standard Hibernate/Spring documentation.