feat(data-fabric): add havingFilter to entity record queries [DS-9078] by aayushuipath · Pull Request #647 · UiPath/uipath-typescript

aayushuipath · 2026-08-06T07:15:15Z

What

Adds havingFilter to EntityQueryRecordsOptions: a post-aggregation filter (SQL HAVING) over grouped aggregate results. Conditions reference declared aggregate aliases ({ aggregateAlias, operator, value }), combined with AND/OR.

How

New types: EntityHavingFilter, EntityHavingCondition, EntityHavingOperator (wire-shape 1:1 with the Data Service contract from CommonEntityPlatform#5832)
queryRecordsById: client-side ValidationError when havingFilter is supplied without aggregates + groupBy (mirrors the join validations)
havingFilter added to excludeFromPrefix - without this the pagination helper OData-prefixes the key to $havingFilter and it silently never reaches the server
Works on both the ID-based route and the name-based multi-entity (joins) route

Server contract notes

Aggregates-only: conditions must reference declared aggregate aliases; row-level conditions stay in filterGroup
Native (LDO) entities only; federated entities and FQS-routed queries return 400
Tenant must have the enable-having-on-query feature flag (rolling out ring-by-ring, alpha first)

Tests

3 new unit tests (verbatim forwarding + excludeFromPrefix, missing-aggregates rejection, missing-groupBy rejection). Full suite: 2153 passed, lint and build clean.

Consumer-rollout ticket: DS-9078. The uip CLI's df records query pass-through depends on this change + a version bump (its body keys are gated by this SDK's excludeFromPrefix allowlist).

🤖 Generated with Claude Code

claude · 2026-08-06T07:19:12Z

Review findings

Inline comment posted

src/models/data-fabric/entities.types.ts:241 — EntityHavingOperator should be an enum (see inline). Also drop the duplicate "<>" operator.

`entities.models.ts` JSDoc not updated (file not in diff)

Both queryRecordsById (line 432) and queryRecords (line 923) have @param options that enumerate the accepted keys — but havingFilter is missing from both. CLAUDE.md: "When a new option or feature is added to one method, update related methods' @example blocks too."

queryRecordsById @param (line 432):

@param options - Query options including filterGroup, selectedFields, sortOptions, aggregates, groupBy, joins, and pagination

→ append , havingFilter to the list.

queryRecords @param (line 923): Same fix.

Both methods also need a new @example block demonstrating havingFilter — e.g.:

// Post-aggregation filter: only groups with count > 5
await entities.queryRecordsById(<id>, {
  selectedFields: ["region"],
  groupBy: ["region"],
  aggregates: [{ function: EntityAggregateFunction.Count, field: "Id", alias: "cnt" }],
  havingFilter: {
    logicalOperator: LogicalOperator.And,
    aggregateFilters: [{ aggregateAlias: "cnt", operator: EntityHavingOperator.GreaterThan, value: "5" }],
  },
});

aayushuipath · 2026-08-07T05:23:27Z

Addressed both findings in 814bad9: EntityHavingOperator is now an enum (QueryFilterOperator pattern, '<>' dropped), and both queryRecordsById/queryRecords JSDoc @param lists mention havingFilter with a HAVING example added to each (including EntityHavingOperator in the example imports).

claude · 2026-08-07T05:28:56Z

Review findings

Inline comment posted

src/services/data-fabric/entities.ts:312 — Missing integration test for havingFilter. CLAUDE.md requires updating the integration test when a new parameter is added to an existing method. See inline for a suggested test structure that probes feature-flag availability in beforeAll and throws loudly if the flag is not enabled, rather than leaving the parameter silently untested in CI.

claude · 2026-08-07T05:37:08Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

claude · 2026-08-07T05:45:28Z

Review finding — tests/integration/shared/data-fabric/entities.integration.test.ts:847-858: the havingFilter integration test gates on DATA_FABRIC_TEST_JOIN_FIELD_NAME, a config variable whose purpose is cross-entity join tests. Environments that have enable-having-on-query enabled but no join config will fail with a misleading error instead of exercising the feature. Id is always present on every DF entity and produces correct assertions without any config coupling — see inline suggestion.

Post-aggregation filter (SQL HAVING) on grouped aggregate results: conditions reference declared aggregate aliases (aggregates-only server contract, DS-9077/DS-9078). Requires aggregates + groupBy - enforced client-side with an actionable ValidationError. havingFilter is registered in excludeFromPrefix so the key reaches the wire un-prefixed; without this the pagination helper would send it as $havingFilter and the server would never see it. Server-side: native (LDO) entities only, gated by the enable-having-on-query feature flag (400 otherwise). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ingFilter Review follow-ups: enum matching the QueryFilterOperator convention (drop the redundant <> - the server normalizes !=), tests on enum members, and havingFilter added to both query methods @param lists with HAVING examples. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Data-independent HAVING assertions on the fixture entity: a satisfiable threshold (cnt >= 1) must return every group and an unsatisfiable one must return none - a backend that ignores havingFilter returns every group there, which is the failing signal. Requires the enable-having-on-query tenant flag; without it the server 400s naming the flag, failing loud as requested. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

claude · 2026-08-07T05:59:09Z

Review findings

New inline comments posted this run

src/models/data-fabric/entities.types.ts:273–274 — (LDO) is an unexplained acronym in the EntityHavingFilter JSDoc. CLAUDE.md requires spelling out the full form or dropping it. Suggestion: remove the parenthetical and keep the plain-English native entities only.

tests/integration/shared/data-fabric/entities.integration.test.ts:870 — Record<string, any> violates CLAUDE.md's no-any rule. Record<string, unknown> works here since Vitest's expect() accepts unknown.

Group by Id (always present) instead of the join fixture field, drop the unexplained LDO acronym from the JSDoc, and use unknown over any in the integration assertion. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

claude · 2026-08-07T09:07:01Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

Sonar S5906: toHaveLength reports the actual array contents on failure. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ninja-shreyash · 2026-08-10T09:56:26Z

+ *
+ * Requires `aggregates` and `groupBy` on the query. Supported for native entities
+ * only; gated by the tenant's `enable-having-on-query` feature
+ * flag — the server responds 400 when either doesn't hold. Maximum 5 conditions.


who enforces "max 5 conditions"?

The server does - the backend's HavingFilterValidator caps it (MAX_HAVING_FILTERS = 5) and returns 400 'Maximum 5 havingFilter conditions allowed per query'.

claude · 2026-08-10T10:02:36Z

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

sonarqubecloud · 2026-08-10T10:04:32Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

aayushuipath requested a review from a team August 6, 2026 07:15

claude Bot reviewed Aug 6, 2026

View reviewed changes

Comment thread src/models/data-fabric/entities.types.ts Outdated

aayushuipath mentioned this pull request Aug 6, 2026

[DS-9078] feat(data-fabric): document havingFilter post-aggregation filter UiPath/skills#2496

Open

claude Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread src/services/data-fabric/entities.ts

aayushuipath force-pushed the feat/entities-having-filter branch from 814bad9 to dc1993c Compare August 7, 2026 05:32

claude Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread tests/integration/shared/data-fabric/entities.integration.test.ts Outdated

aayushuipath and others added 3 commits August 7, 2026 11:17

aayushuipath force-pushed the feat/entities-having-filter branch from af80296 to 65ecdfc Compare August 7, 2026 05:47

claude Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread src/models/data-fabric/entities.types.ts Outdated

claude Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread tests/integration/shared/data-fabric/entities.integration.test.ts Outdated

test(data-fabric): use toHaveLength for the empty-groups assertion

f966ce4

Sonar S5906: toHaveLength reports the actual array contents on failure. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ninja-shreyash reviewed Aug 10, 2026

View reviewed changes

Uh oh!

Conversation

aayushuipath commented Aug 6, 2026

What

How

Server contract notes

Tests

Uh oh!

Uh oh!

claude Bot commented Aug 6, 2026

Review findings

Inline comment posted

entities.models.ts JSDoc not updated (file not in diff)

Uh oh!

aayushuipath commented Aug 7, 2026

Uh oh!

Uh oh!

claude Bot commented Aug 7, 2026

Review findings

Inline comment posted

Uh oh!

claude Bot commented Aug 7, 2026

Uh oh!

Uh oh!

claude Bot commented Aug 7, 2026

Uh oh!

Uh oh!

Uh oh!

claude Bot commented Aug 7, 2026

Review findings

New inline comments posted this run

Uh oh!

claude Bot commented Aug 7, 2026

Uh oh!

ninja-shreyash Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

aayushuipath Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

claude Bot commented Aug 10, 2026

Uh oh!

sonarqubecloud Bot commented Aug 10, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

`entities.models.ts` JSDoc not updated (file not in diff)

aayushuipath Aug 10, 2026 •

edited

Loading