feat(entities): support havingFilter post-aggregation filter [DS-9078]

packages/uipath-platform/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-platform"
-version = "0.2.18"
+version = "0.2.19"
 description = "HTTP client library for programmatic access to UiPath Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath-platform/src/uipath/platform/entities/__init__.py

@@ -18,6 +18,9 @@
     EntityField,
     EntityFieldDataType,
     EntityFieldMetadata,
+    EntityHavingCondition,
+    EntityHavingFilter,
+    EntityHavingOperator,
     EntityImportRecordsResponse,
     EntityJoin,
     EntityMetadataUpdateOptions,
@@ -58,6 +61,9 @@
     "EntityField",
     "EntityFieldDataType",
     "EntityFieldMetadata",
+    "EntityHavingCondition",
+    "EntityHavingFilter",
+    "EntityHavingOperator",
     "EntityImportRecordsResponse",
     "EntityJoin",
     "EntityMetadataUpdateOptions",

packages/uipath-platform/src/uipath/platform/entities/_entities_service.py

@@ -45,6 +45,7 @@
     EntityBinning,
     EntityCreateFieldOptions,
     EntityCreateOptions,
+    EntityHavingFilter,
     EntityImportRecordsResponse,
     EntityJoin,
     EntityMetadataUpdateOptions,
@@ -1627,6 +1628,7 @@ def retrieve_records(
         expansion_level: Optional[int] = None,
         aggregates: Optional[List[EntityAggregate]] = None,
         group_by: Optional[List[str]] = None,
+        having_filter: Optional[EntityHavingFilter] = None,
         joins: Optional[List[EntityJoin]] = None,
         binnings: Optional[List[EntityBinning]] = None,
         start: Optional[int] = None,
@@ -1656,6 +1658,11 @@ def retrieve_records(
             group_by (Optional[List[str]]): Fields to group aggregate results
                 by. Maximum 5; required when both ``aggregates`` and
                 ``selected_fields`` are supplied.
+            having_filter (Optional[EntityHavingFilter]): Post-aggregation
+                filter (SQL ``HAVING``) on declared aggregate aliases;
+                requires ``aggregates`` and ``group_by``. Maximum 5
+                conditions. Native entities only; gated by the
+                ``enable-having-on-query`` feature flag on the backend.
             joins (Optional[List[EntityJoin]]): Cross-entity joins. Maximum
                 3, all of the same type.
             binnings (Optional[List[EntityBinning]]): Bucket numeric or date
@@ -1726,6 +1733,38 @@ def retrieve_records(
                 )
                 for row in result.items:
                     print(row.status, row.total)
+
+            HAVING (keep only statuses with more than 5 records)::
+
+                from uipath.platform.entities import (
+                    EntityAggregate,
+                    EntityAggregateFunction,
+                    EntityHavingCondition,
+                    EntityHavingFilter,
+                    EntityHavingOperator,
+                )
+
+                result = entities_service.retrieve_records(
+                    "Customers",
+                    selected_fields=["status"],
+                    group_by=["status"],
+                    aggregates=[
+                        EntityAggregate(
+                            function=EntityAggregateFunction.Count,
+                            field="Id",
+                            alias="total",
+                        )
+                    ],
+                    having_filter=EntityHavingFilter(
+                        aggregate_filters=[
+                            EntityHavingCondition(
+                                aggregate_alias="total",
+                                operator=EntityHavingOperator.GreaterThan,
+                                value="5",
+                            )
+                        ],
+                    ),
+                )
         """
         return self._data.retrieve_records(
             entity_key,
@@ -1736,6 +1775,7 @@ def retrieve_records(
             expansion_level=expansion_level,
             aggregates=aggregates,
             group_by=group_by,
+            having_filter=having_filter,
             joins=joins,
             binnings=binnings,
             start=start,
@@ -1753,6 +1793,7 @@ async def retrieve_records_async(
         expansion_level: Optional[int] = None,
         aggregates: Optional[List[EntityAggregate]] = None,
         group_by: Optional[List[str]] = None,
+        having_filter: Optional[EntityHavingFilter] = None,
         joins: Optional[List[EntityJoin]] = None,
         binnings: Optional[List[EntityBinning]] = None,
         start: Optional[int] = None,
@@ -1780,6 +1821,11 @@ async def retrieve_records_async(
             group_by (Optional[List[str]]): Fields to group aggregate results
                 by. Maximum 5; required when both ``aggregates`` and
                 ``selected_fields`` are supplied.
+            having_filter (Optional[EntityHavingFilter]): Post-aggregation
+                filter (SQL ``HAVING``) on declared aggregate aliases;
+                requires ``aggregates`` and ``group_by``. Maximum 5
+                conditions. Native entities only; gated by the
+                ``enable-having-on-query`` feature flag on the backend.
             joins (Optional[List[EntityJoin]]): Cross-entity joins. Maximum
                 3, all of the same type.
             binnings (Optional[List[EntityBinning]]): Bucket numeric or date
@@ -1825,6 +1871,7 @@ async def retrieve_records_async(
             expansion_level=expansion_level,
             aggregates=aggregates,
             group_by=group_by,
+            having_filter=having_filter,
             joins=joins,
             binnings=binnings,
             start=start,

packages/uipath-platform/src/uipath/platform/entities/_entity_data_service.py

@@ -30,6 +30,7 @@
     ChoiceSetValue,
     EntityAggregate,
     EntityBinning,
+    EntityHavingFilter,
     EntityImportRecordsResponse,
     EntityJoin,
     EntityQueryFilterGroup,
@@ -451,6 +452,7 @@ def retrieve_records(
         expansion_level: Optional[int] = None,
         aggregates: Optional[List[EntityAggregate]] = None,
         group_by: Optional[List[str]] = None,
+        having_filter: Optional[EntityHavingFilter] = None,
         joins: Optional[List[EntityJoin]] = None,
         binnings: Optional[List[EntityBinning]] = None,
         start: Optional[int] = None,
@@ -466,6 +468,7 @@ def retrieve_records(
             expansion_level=expansion_level,
             aggregates=aggregates,
             group_by=group_by,
+            having_filter=having_filter,
             joins=joins,
             binnings=binnings,
             start=start,
@@ -486,6 +489,7 @@ async def retrieve_records_async(
         expansion_level: Optional[int] = None,
         aggregates: Optional[List[EntityAggregate]] = None,
         group_by: Optional[List[str]] = None,
+        having_filter: Optional[EntityHavingFilter] = None,
         joins: Optional[List[EntityJoin]] = None,
         binnings: Optional[List[EntityBinning]] = None,
         start: Optional[int] = None,
@@ -501,6 +505,7 @@ async def retrieve_records_async(
             expansion_level=expansion_level,
             aggregates=aggregates,
             group_by=group_by,
+            having_filter=having_filter,
             joins=joins,
             binnings=binnings,
             start=start,
@@ -890,15 +895,17 @@ def _retrieve_records_spec(
         expansion_level: Optional[int] = None,
         aggregates: Optional[List[Any]] = None,
         group_by: Optional[List[str]] = None,
+        having_filter: Optional[EntityHavingFilter] = None,
         joins: Optional[List[EntityJoin]] = None,
         binnings: Optional[List[EntityBinning]] = None,
         start: Optional[int] = None,
         limit: Optional[int] = None,
     ) -> RequestSpec:
         """Build the request spec for the structured-query endpoint.
 
-        Filters, sorting, projection, expansions, aggregates, group-by, joins,
-        binnings, ``start``, and ``limit`` are placed in the JSON body;
+        Filters, sorting, projection, expansions, aggregates, group-by,
+        having, joins, binnings, ``start``, and ``limit`` are placed in the
+        JSON body;
         ``expansionLevel`` is a URL query parameter. The V2 endpoint is used
         only when ``binnings`` are supplied.
         """
@@ -929,6 +936,15 @@ def _retrieve_records_spec(
             ]
         if group_by:
             body["groupBy"] = list(group_by)
+        if having_filter is not None:
+            if not aggregates or not group_by:
+                raise ValueError(
+                    "having_filter requires aggregates and group_by; "
+                    "row-level conditions belong in filter_group."
+                )
+            body["havingFilter"] = having_filter.model_dump(
+                by_alias=True, exclude_none=True
+            )
         if joins:
             body["joins"] = [
                 j.model_dump(by_alias=True, exclude_none=True) for j in joins

packages/uipath-platform/src/uipath/platform/entities/entities.py

@@ -547,6 +547,47 @@ class EntityAggregate(BaseModel):
     alias: Optional[str] = None
 
 
+class EntityHavingOperator(str, Enum):
+    """Comparison operators supported in HAVING conditions."""
+
+    Equals = "="
+    NotEquals = "!="
+    GreaterThan = ">"
+    GreaterThanOrEqual = ">="
+    LessThan = "<"
+    LessThanOrEqual = "<="
+
+
+class EntityHavingCondition(BaseModel):
+    """A single HAVING condition on a declared aggregate alias."""
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+    aggregate_alias: str = Field(alias="aggregateAlias")
+    operator: EntityHavingOperator
+    value: str
+
+
+class EntityHavingFilter(BaseModel):
+    """Post-aggregation filter (SQL ``HAVING``) over declared aggregate aliases.
+
+    Conditions may reference aggregate aliases only; row-level conditions
+    belong in ``filter_group``, which the database applies before grouping.
+    Supported for native entities only and gated by the
+    ``enable-having-on-query`` feature flag on the backend. Maximum 5
+    conditions per query.
+    """
+
+    model_config = ConfigDict(validate_by_name=True, validate_by_alias=True)
+
+    logical_operator: Optional[LogicalOperator] = Field(
+        default=None, alias="logicalOperator"
+    )
+    aggregate_filters: List[EntityHavingCondition] = Field(
+        alias="aggregateFilters", min_length=1
+    )
+
+
 class EntityJoin(BaseModel):
     """Multi-entity JOIN definition for cross-entity queries."""
 

packages/uipath-platform/tests/services/test_entities_service.py

@@ -1475,6 +1475,91 @@ def test_query_v2_when_binnings_provided(
         assert sent is not None
         assert "/v2/EntityService/" in str(sent.url)
 
+    def test_query_having_filter_sent_in_body(
+        self,
+        httpx_mock: HTTPXMock,
+        service: EntitiesService,
+        base_url: str,
+        org: str,
+        tenant: str,
+        version: str,
+    ) -> None:
+        """``having_filter`` is serialized with camelCase wire keys."""
+        from uipath.platform.entities import (
+            EntityAggregate,
+            EntityAggregateFunction,
+            EntityHavingCondition,
+            EntityHavingFilter,
+            EntityHavingOperator,
+            LogicalOperator,
+        )
+
+        entity_key = uuid.uuid4()
+        httpx_mock.add_response(
+            url=re.compile(
+                rf"{base_url}{org}{tenant}/datafabric_/api/EntityService/entity/{entity_key}/query.*"
+            ),
+            status_code=200,
+            json={"value": [{"status": "active", "total": 12}], "totalRecordCount": 1},
+        )
+
+        service.retrieve_records(
+            entity_key=str(entity_key),
+            selected_fields=["status"],
+            group_by=["status"],
+            aggregates=[
+                EntityAggregate(
+                    function=EntityAggregateFunction.Count,
+                    field="Id",
+                    alias="total",
+                )
+            ],
+            having_filter=EntityHavingFilter(
+                logical_operator=LogicalOperator.And,
+                aggregate_filters=[
+                    EntityHavingCondition(
+                        aggregate_alias="total",
+                        operator=EntityHavingOperator.GreaterThan,
+                        value="5",
+                    )
+                ],
+            ),
+        )
+
+        sent = httpx_mock.get_request()
+        assert sent is not None
+        body = json.loads(sent.content)
+        assert body["havingFilter"] == {
+            "logicalOperator": 0,
+            "aggregateFilters": [
+                {"aggregateAlias": "total", "operator": ">", "value": "5"}
+            ],
+        }
+
+    def test_query_having_filter_requires_aggregates_and_group_by(
+        self,
+        service: EntitiesService,
+    ) -> None:
+        """``having_filter`` without aggregates + group_by fails locally, no HTTP."""
+        from uipath.platform.entities import (
+            EntityHavingCondition,
+            EntityHavingFilter,
+            EntityHavingOperator,
+        )
+
+        having = EntityHavingFilter(
+            aggregate_filters=[
+                EntityHavingCondition(
+                    aggregate_alias="total",
+                    operator=EntityHavingOperator.GreaterThan,
+                    value="5",
+                )
+            ],
+        )
+
+        with pytest.raises(ValueError, match="aggregates and group_by"):
+            service.retrieve_records(entity_key="ent-1", having_filter=having)
+
     def test_upload_attachment_sends_multipart(
         self,
         httpx_mock: HTTPXMock,