This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Cardinality aggregations

The cardinality metric is a single-value metric aggregation that counts the number of unique or distinct values of a field.

The following example finds the number of unique products in an eCommerce store:

  1. GET opensearch_dashboards_sample_data_ecommerce/_search
  2. {
  3.   "size": 0,
  4.   "aggs": {
  5.     "unique_products": {
  6.       "cardinality": {
  7.         "field": "products.product_id"
  8.       }
  9.     }
  10.   }
  11. }

copy

Example response

  1. ...
  2.   "aggregations" : {
  3.     "unique_products" : {
  4.       "value" : 7033
  5.     }
  6.   }
  7. }

Cardinality count is approximate. If you have tens of thousands of products in your hypothetical store, an accurate cardinality calculation requires loading all the values into a hash set and returning its size. This approach doesn’t scale well; it requires huge amounts of memory and can cause high latencies.

You can control the trade-off between memory and accuracy with the precision_threshold setting. This setting defines the threshold below which counts are expected to be close to accurate. Above this value, counts might become a bit less accurate. The default value of precision_threshold is 3,000. The maximum supported value is 40,000.

  1. GET opensearch_dashboards_sample_data_ecommerce/_search
  2. {
  3.   "size": 0,
  4.   "aggs": {
  5.     "unique_products": {
  6.       "cardinality": {
  7.         "field": "products.product_id",
  8.         "precision_threshold": 10000
  9.       }
  10.     }
  11.   }
  12. }