API Explorer

Aggregations

Why use aggregations?

Aggregations let you ask questions about your data instead of retrieving the full list of matching documents. Typical use‑cases include:

  • Building dashboards – e.g. “show the average renewal amount per month”
  • Powering filters – e.g. “list the top 10 contract owners and the number of contracts per owner”
  • Quick analytics – e.g. “count deals by stage and sum their values”

At request time you attach an aggs block whose shape is described below.

High‑level schema

{
  "field": "index field to aggregate on",
  "aggregationType": "one of: metric | groupBy | date_range | date_histogram",
  "options": "type‑specific options (see below)",
  "aggs": "(optional) nested aggregation – same schema recursively"
}

Common optional helpers (allowed everywhere unless stated otherwise):

  • size – max number of buckets to return (default: index.max_terms, hard‑limit 100)
  • sort – how to order buckets. Shape varies by aggregation type.

aggregationType: metric

Use when you need a single numeric answer (sum, average, …) instead of buckets.

FieldRequired?Description
field✔Numeric field to summarise
aggregationType✔metric
options.metricFunction✔sum, avg, max, min
options.size✖Number of buckets to keep (after sorting); max 100
options.sort✖{ field, aggFunc, order }
field – the field inside the bucket to sort by (usually same as parent)
aggFunc – one of the metric functions above
order – min or max

Example – average apps per user

{
  "field":"activeAppsCount",
  "aggregationType":"metric",
  "options":{"metricFunction":"avg"}
}

curl 'https://api.toriih.com/v1.0/users?aggs={%20%22field%22%3A%22activeAppsCount%22%2C%20%22aggregationType%22%3A%22metric%22%2C%20%22options%22%3A{%22metricFunction%22%3A%22avg%22}}' \
--header 'Authorization: Bearer <API_KEY>'

aggregationType: groupBy

Buckets documents by the exact value of field (keyword/text). Optionally compute metrics per bucket.

FieldRequired?Description
field✔Keyword or numeric field whose unique values become bucket keys
aggregationType✔groupBy
options.size✖Number of buckets to keep (after sorting); max 100
options.sort✖Same structure as metric
options.metricFunction✖total (document count) plus any metric functions (sum, avg, max, min) to compute inside each bucket

Example – group apps by source

{
  "field":"sources",
  "aggregationType":"groupBy",
  "options":{
    "sort":{
      "order":"desc",
      "aggFunc":"total"
    },
    "size":5
  }
}

curl 'https://api.toriih.com/v1.0/apps?aggs={%22field%22%3A%22sources%22%2C%22aggregationType%22%3A%22groupBy%22%2C%22options%22%3A{%22sort%22%3A{%22order%22%3A%22desc%22%2C%22aggFunc%22%3A%22total%22}%2C%22size%22%3A5}}' \
--header 'X-API-VERSION: 1.1' \
--header 'Authorization: Bearer <API_KEY>'

aggregationType: date_range

Splits documents into arbitrary, possibly overlapping, date ranges.

FieldRequired?Description
field✔Date field (RFC‑3339 strings)
aggregationType✔date_range
options.size✖Number of buckets to keep (after sorting); max 100
options.sort✖{ field, order } – same structure as metric but without aggFunc

aggregationType: date_histogram

Produces contiguous calendar buckets (week / month / quarter / year).

FieldRequired?Description
field✔Date field
aggregationType✔date_histogram
options.dateHistogramOptions.datePeriod✔One of weekly, monthly, quarterly, yearly
options.dateHistogramOptions.hardBounds✖{ min, max } – explicit min/max bounds; buckets outside are excluded
options.dateHistogramOptions.extendedBounds✖{ min, max } – still create empty buckets beyond data range
options.sort✖{ field, order }– same structure as metric but withoutaggFunc
options.size✖Number of buckets to keep (after sorting); max 100

Example – discovered apps over time

{
  "field":"creationTime",
  "aggregationType":"date_histogram",
  "options":{
    "dateHistogramOptions":{
      "datePeriod":"monthly"
		},
    "sort":{
      "field":"creationTime",
      "order":"asc"
    },
    "size":40
  }
}

curl 'https://api.toriih.com/v1.0/apps?aggs={%22field%22%3A%22creationTime%22%2C%22aggregationType%22%3A%22date_histogram%22%2C%22options%22%3A{%22dateHistogramOptions%22%3A{%22datePeriod%22%3A%22monthly%22}%2C%22sort%22%3A{%22field%22%3A%22creationTime%22%2C%22order%22%3A%22asc%22}%2C%22size%22%3A40}}' \
--header 'X-API-VERSION: 1.1' \
--header 'Authorization: Bearer <API_KEY>'

Sorting syntax

sort {
  field    string   			// bucket key or doc field to sort by
  order   "asc" | "desc" 	// (ascending / descending)
  aggFunc  enum    				// extra metric used for ordering (metric & groupBy only)
}

Nesting aggregations

Set aggs to another aggregation object to drill down. There is no hard depth limit, but response size grows with every level, so keep it reasonable.

Example – app spend by category

{
  "field":"category",
  "aggregationType":"groupBy",
  "options":{
    "sort":{
      "field":"expenses",
      "order":"desc",
      "aggFunc":"sum"
    },
    "size":5
  },
  "aggs":{
    "field":"expenses",
    "aggregationType":"metric",
    "options":{
      "metricFunction":"sum"
    }
  }
}

Quick reference

  • metricFunction: sum, avg, max, min (+ total inside groupBy)
  • aggregationType: metric, groupBy, date_range, date_histogram
  • sort.order: asc (ascending) or desc (descending)
  • size hard‑limited to 100