Advanced querying and aggregation

This topic covers query capabilities that go beyond the basic filtering, sorting, and paging described in Retrieve and filter collections. Some apply to any collection; others, such as grouping, apply only to specific resources.

In this topic:

Grouping and aggregation

Rather than returning individual entities, a collection can return its entities grouped by a field, with an aggregate calculated for each group. Grouping is requested through the groups sub-collection of an entity collection, not the collection itself:

GET /api/shared_spaces/{shared_space_id}/workspaces/{workspace_id}/work_items/groups?group_by=phase

Two parameters control the result:

• group_by. The field to group by. To group by a field of a referenced entity, name the sub-field in braces, as in group_by=release{agile_type}.

• group_data. An aggregate to compute for each group, as a function of a field: sum(<field>), count(<field>), or avg(<field>).

GET /api/.../work_items/groups?group_by=phase&group_data=count(id)

Note: The groups sub-collection groups by a single field. Reporting endpoints support their own grouping, over more than one field.

Cross-workspace queries

By default a request reads from a single workspace. On a shared-space or workspace collection, the cross_workspace parameter widens a read to several workspaces at once. Give it a comma-separated list of workspace IDs, or * to include every workspace the caller can access:

GET /api/shared_spaces/{shared_space_id}/workspaces/{workspace_id}/defects?cross_workspace=1002,1005

Cross-workspace reads are supported only in contexts that allow them; where the context does not, the request is rejected.

Filtering by subtype

For an aggregated entity type, the subtypes parameter restricts the request to specific subtypes, given as a comma-separated list. For example, a work item is an aggregated type whose subtypes include defect and story:

GET /api/.../work_items/groups?group_by=phase&subtypes=defect,story

You can achieve the same filtering in a query by matching the subtype field. See Filtering.

Numeric and logical identifiers

For entities that have a logical name, the server can return the logical name in place of the numeric ID. Set use_numeric_id=true to suppress that conversion and keep the raw numeric id in the response.

GET /api/.../phases?use_numeric_id=true

Requesting the maximum page size

In addition to a numeric value, the limit parameter accepts the value max, which returns the maximum page size that the server allows. For general paging, see Paging.

?limit=max