Aggregations

Aggregations allow to perform simple arithmetic operations on result of some query. Aggregations are only applied to record set returned by query, after all the filters are applied.

Following example calculates maximum, minimum and average value of decimal_value attribute of all deals available for $ACCESS_TOKEN owner.

Note the use of "hits": false parameter - it is used not to fetch query results, since the important part in the response is aggregation result and not single items themselves.

Fetch deals

POST /v3/deals/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
	"items": [
		{
			"data": {
				"aggregations": [
					{
						"attribute": {
							"name": "decimal_value"
						},
						"aggregation_type": "max"
					},
					{
						"attribute": {
							"name": "decimal_value"
						},
						"aggregation_type": "min"
					},
					{
						"attribute": {
							"name": "decimal_value"
						},
						"aggregation_type": "avg"
					}
				],
				"hits": false
			}
		}
	]
}

Content-Type: application/json; charset=UTF-8

{
    "items": [
        {
            "successful": true,
            "items": [],
            "meta": {
                "aggregations": {
                    "decimal_value": {
                        "min": 14.05441,
                        "avg": 2670660,
                        "max": 34463590
                    }
                },
                "count": 0,
                "http_status": "200 OK",
                "links": {},
                "total_count": 13,
                "type": "collection"
            }
        }
    ]
}

---

As stated previously, additional filtering can be applied. Following request may be used to calculate average deal value, won by Jane Doe in 2nd quarter of 2017. It contains two main parts: filter for narrowing record set (just as described in filtering section) and aggregation definition to aggregate query results.

Fetch deals

POST /v3/deals/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "data": {
        "query": {
          "filter": {
            "and": [
              {
                "filter": {
                  "attribute": {
                    "name": "owner.name"
                  },
                  "parameter": {
                    "eq": "Jane Doe"
                  }
                }
              },
              {
                "filter": {
                  "attribute": {
                    "name": "is_won"
                  },
                  "parameter": {
                    "eq": true
                  }
                }
              },
              {
                "filter": {
                  "attribute": {
                    "name": "close_date"
                  },
                  "parameter": {
                    "range": {
                      "gte": "2017-04-01",
                      "lte": "2017-06-30"
                    }
                  }
                }
              }
            ]
          }
        },
        "aggregations": [
          {
            "attribute": {
              "name": "decimal_value"
            },
            "aggregation_type": "avg"
          }
        ],
        "hits": false
      }
    }
  ]
}

Content-Type: application/json; charset=UTF-8

{
    "items": [
        {
            "successful": true,
            "items": [],
            "meta": {
                "aggregations": {
                    "decimal_value": {
                        "avg": 6000
                    }
                },
                "count": 0,
                "http_status": "200 OK",
                "links": {},
                "total_count": 2,
                "type": "collection"
            }
        }
    ]
}