Skip to main content
New support request

Aggregations

Log in to add to favourites

Page last updated 28 October 2025

Aggregations allow you to group data by specific fields and return a count of entries matching each value, providing insights into data distribution and allowing refined searches.

Defining and Using Aggregations

Aggregations can be added to a search query using an aggregations object. This allows you to group results by a specific field and return a count of entries matching each value. Here's how to set up aggregations:

Example Aggregation Setup

JSON
{
  "where": [
    { "field": "sys.versionStatus", "equalTo": "latest" }
  ],
  "aggregations": {
    "tags": {
      "field": "entryTags",
      "missing": "Untagged",
      "size": 5
    }
  },
  "pageIndex": 0,
  "pageSize": 10
}
  1. Aggregations Object: Add an aggregations object alongside your normal search query.
    The user defined name of the child object (e.g., tags) determines how the results will appear in the response.
  2. Field: Specify the field you want to group by using the field attribute.
    Limitation: Fields with a dataFormat of tag have been specifically designed to retain their original casing in aggregation results. All other field types will return values in lowercase by default.
  3. Missing Attribute: Use missing to assign a value (e.g., "Untagged") to items that lack a value for the specified field. If omitted the missing count will not appear in the results.
  4. Size: Define the number of groupings to return using the size attribute. The default is 10 if not specified.

Examples

Example 1: Returning Entries Along with Aggregations

Endpoint

POST /api/delivery/projects/website/entries/search

Request Body

JSON
{
  "where": [
    { "field": "sys.versionStatus", "equalTo": "latest" }
  ],
  "aggregations": {
    "tags": {
      "missing": "Untagged",
      "field": "entryTags",
      "size": 20
    }
  },
  "pageIndex": 0,
  "pageSize": 10
}

Explanation

  • Retrieves entries and aggregations in the same response.
  • Limits returned entries to the first 10 using pageSize.
  • Aggregates data by the entryTags field as tags.
    • Labels missing values as "Untagged."
    • Returns the top 20 tags.

Result Example

JSON
{
  "pageIndex": 0,
  "pageSize": 10,
  "totalCount": 509,
  "pageCount": 51,
  "items": [
   ... Entry data ...
  ],
  "aggregations": {
    "tags": {
      "Untagged": 500,
      "Car": 7,
      "Truck": 5,
      "Motorbike": 2
    }
  }
}

Example 2: Using  multiple Aggregations with a where Query

Endpoint

POST /api/delivery/projects/website/entries/search

Request Body

JSON
{
  "where": [
    { "field": "sys.versionStatus", "equalTo": "latest" }
  ],
  "aggregations": {
    "tags": {
      "missing": "Untagged",
      "field": "entryTags",
      "size": 20
    },
    "another": {
      "field": "myField",
      "size": 5
    }
  },
  "pageIndex": 0,
  "pageSize": 0
}

Explanation

  • Filters entries to retrieve only the latest version.
  • Aggregates data by the entryTags field as tags.
    • Labels missing values as "Untagged".
    • Returns the top 20 tags.
  • Aggregates data by the myField field as another.
    • Returns the top 5 values.
  • Suppresses entry results by setting pageSize to 0.

Result Example

JSON
{
  "pageIndex": 0,
  "pageSize": 0,
  "totalCount": 509,
  "pageCount": 0,
  "items": [],
  "aggregations": {
    "tags": {
      "Untagged": 500,
      "Car": 7,
      "Ferrari": 4,
      "Toyota": 4
    },
    "another": {
      "value1": 8,
      "value3": 5,
      "value2": 1
    }
  }
}

Example 3: Using Aggregations with ZenQL

  • Aggregates data by the entryTags field as tags .
    • Labels missing values as "Untagged".
    • Returns the top 20 tags.

Endpoint

GET /api/delivery/projects/website/entries?zenql=sys.versionStatus=latest&aggregations={"tags":{"field":"entryTags"}}&pagesize=0

Explanation

  • Filters entries using ZenQL to retrieve only the latest versions.
  • Groups entries by the entryTags field.
  • Omits entry details by setting pagesize=0.

Result Example

JSON
{
  "pageIndex": 0,
  "pageSize": 0,
  "totalCount": 509,
  "pageCount": 0,
  "items": [],
  "aggregations": {
    "tags": {
      "Car": 10,
      "Truck": 5,
      "Motorbike": 2
    }
  }
}

Example 4: Refining Searches with Aggregations

Request Body

JSON
{
  "where": [
    { "field": "sys.versionStatus", "equalTo": "latest" },
    { "field": "entryTags", "equalTo": "car" },
    { "field": "entryTags", "equalTo": "red" }
  ],
  "aggregations": {
    "tags": {
      "missing": "Untagged",
      "field": "entryTags",
      "size": 20
    }
  },
  "pageIndex": 0,
  "pageSize": 0
}

Explanation

  • Filters entries tagged with "car" and "red".
  • Aggregates additional tags for refined filtering.

Result Example

JSON
{
  "pageIndex": 0,
  "pageSize": 0,
  "totalCount": 509,
  "pageCount": 0,
  "items": [],
  "aggregations": {
    "tags": {
      "Convertible": 3,
      "SUV": 2
    }
  }
}

Key Use Cases

  1. Understanding Data Distribution: Aggregations let you group data by specific fields, providing counts for each category (e.g., tags or statuses). This helps you quickly understand how data is distributed.
  2. Handling Missing Values: Use the missing property to group entries that lack a value for the specified field, ensuring such entries are included in the results. Note: "Untagged" cannot be used as an actual tag value.
  3. Refining Searches: Aggregations reveal additional filtering options (e.g., related tags) that can guide further refinement of your searches. Start with broad queries and use aggregation results to drill down into specific subsets of data.

Still need help?

If you still need help after reading this article, don't hesitate to reach out to the Contensis community on Slack or raise a support ticket to get help from our team.
New support request