Data Authority Limitations

Known constraints and edge cases of the Data Authority query system. Companion to Data Authority Module Pattern and Query DSL.

Last verified against common-module on 2026-03-26.

Current Limitations

Query Schema Validation

Filter keys are validated at execution time, not at construction time. If a client sends a filter referencing a non-existent column, the error is raised when the FilterExposedVisitor attempts to resolve the locator against the table schema. Clients receive an ArgumentValidation error with the message "Column with name '<name>' not found in table '<table>'".

Impact: Malformed queries are not rejected early; debugging requires inspecting the full error response.

Full-Text Search

The filter system supports structured comparisons (EQ, NE, GT, GE, LT, LE, IN, NOT_IN, IS_NULL, IS_NOT_NULL) and RegEx for pattern matching. There is no built-in support for:

• Full-text search across multiple fields
• Fuzzy matching or typo tolerance
• Relevance scoring or ranking
• Stemming or synonym expansion

Workaround: Use RegEx filters for basic pattern matching on individual fields.

Field Projections

All REST endpoints return complete EntityRecord<EP, EM> objects. There is no mechanism for clients to request a subset of fields. This means:

• Payloads are always full-size, regardless of what the client needs
• List views that display only a few columns still transfer entire entity records
• No fields parameter is available on query endpoints

Aggregation API Exposure

The persistence layer (Universe) supports aggregation operations (COUNT, SUM, AVERAGE, MIN, MAX with GROUP BY), and these are tested. However, aggregation is not exposed through the REST API. The DataAuthorityEndpoint has no aggregation endpoint, and the Query data class does not include an aggregation field.

Workaround: Aggregations can only be performed server-side within the service layer, not requested by API consumers.

Sorting on Calculated Fields

Sorting supports direct table columns and nested component property paths (via ExposedLocatorTranslator). It does not support:

• Sorting by computed expressions (e.g., price * quantity)
• Sorting by derived fields not stored in the database
• Collection quantifiers in sort keys (e.g., lines[any].status)

Resolved Limitations

These items were limitations in earlier versions but have since been addressed:

Page Tokens (Resolved)

Page tokens are now full Query state objects: GZIP-compressed, Base64-encoded JSON serializations of the complete Query (filter + sort + pagination). They are properly decoded with error handling for malformed or tampered tokens. No longer placeholder implementations.

OR and NOT Filters (Resolved)

The Filter sealed interface supports Filter.Or (composite clauses) and Filter.Not (transform) operators. Both are translated to SQL via FilterExposedVisitor.visitComposite() and visitTransform(). Clients can express arbitrary boolean logic in filter trees.

Potential Enhancements

These are documented directions for future work, not committed roadmap items:

Enhancement	Benefit	Complexity
Upfront query schema validation	Fail-fast on malformed queries before execution	Low
Expose aggregation via REST	Client-side analytics without full data transfer	Medium
Field projections	Reduced payload size for list views	Medium
Full-text search integration	Natural language queries across fields	High (requires search engine)
Calculated sort expressions	Sort by derived values	Medium
Async query execution for exports	Handle very large result sets without timeouts	High