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.

Top hits aggregations

The top_hits metric is a multi-value metric aggregation that ranks the matching documents based on a relevance score for the field that’s being aggregated.

You can specify the following options:

  • from: The starting position of the hit.
  • size: The maximum size of hits to return. The default value is 3.
  • sort: How the matching hits are sorted. By default, the hits are sorted by the relevance score of the aggregation query.

The following example returns the top 5 products in your eCommerce data:

  1. GET opensearch_dashboards_sample_data_ecommerce/_search
  2. {
  3.   "size": 0,
  4.   "aggs": {
  5.     "top_hits_products": {
  6.       "top_hits": {
  7.         "size": 5
  8.       }
  9.     }
  10.   }
  11. }

copy

Example response

  1. ...
  2. "aggregations" : {
  3.   "top_hits_products" : {
  4.     "hits" : {
  5.       "total" : {
  6.         "value" : 4675,
  7.         "relation" : "eq"
  8.       },
  9.       "max_score" : 1.0,
  10.       "hits" : [
  11.         {
  12.           "_index" : "opensearch_dashboards_sample_data_ecommerce",
  13.           "_type" : "_doc",
  14.           "_id" : "glMlwXcBQVLeQPrkHPtI",
  15.           "_score" : 1.0,
  16.           "_source" : {
  17.             "category" : [
  18.               "Women's Accessories",
  19.               "Women's Clothing"
  20.             ],
  21.             "currency" : "EUR",
  22.             "customer_first_name" : "rania",
  23.             "customer_full_name" : "rania Evans",
  24.             "customer_gender" : "FEMALE",
  25.             "customer_id" : 24,
  26.             "customer_last_name" : "Evans",
  27.             "customer_phone" : "",
  28.             "day_of_week" : "Sunday",
  29.             "day_of_week_i" : 6,
  30.             "email" : "rania@evans-family.zzz",
  31.             "manufacturer" : [
  32.               "Tigress Enterprises"
  33.             ],
  34.             "order_date" : "2021-02-28T14:16:48+00:00",
  35.             "order_id" : 583581,
  36.             "products" : [
  37.               {
  38.                 "base_price" : 10.99,
  39.                 "discount_percentage" : 0,
  40.                 "quantity" : 1,
  41.                 "manufacturer" : "Tigress Enterprises",
  42.                 "tax_amount" : 0,
  43.                 "product_id" : 19024,
  44.                 "category" : "Women's Accessories",
  45.                 "sku" : "ZO0082400824",
  46.                 "taxless_price" : 10.99,
  47.                 "unit_discount_amount" : 0,
  48.                 "min_price" : 5.17,
  49.                 "_id" : "sold_product_583581_19024",
  50.                 "discount_amount" : 0,
  51.                 "created_on" : "2016-12-25T14:16:48+00:00",
  52.                 "product_name" : "Snood - white/grey/peach",
  53.                 "price" : 10.99,
  54.                 "taxful_price" : 10.99,
  55.                 "base_unit_price" : 10.99
  56.               },
  57.               {
  58.                 "base_price" : 32.99,
  59.                 "discount_percentage" : 0,
  60.                 "quantity" : 1,
  61.                 "manufacturer" : "Tigress Enterprises",
  62.                 "tax_amount" : 0,
  63.                 "product_id" : 19260,
  64.                 "category" : "Women's Clothing",
  65.                 "sku" : "ZO0071900719",
  66.                 "taxless_price" : 32.99,
  67.                 "unit_discount_amount" : 0,
  68.                 "min_price" : 17.15,
  69.                 "_id" : "sold_product_583581_19260",
  70.                 "discount_amount" : 0,
  71.                 "created_on" : "2016-12-25T14:16:48+00:00",
  72.                 "product_name" : "Cardigan - grey",
  73.                 "price" : 32.99,
  74.                 "taxful_price" : 32.99,
  75.                 "base_unit_price" : 32.99
  76.               }
  77.             ],
  78.             "sku" : [
  79.               "ZO0082400824",
  80.               "ZO0071900719"
  81.             ],
  82.             "taxful_total_price" : 43.98,
  83.             "taxless_total_price" : 43.98,
  84.             "total_quantity" : 2,
  85.             "total_unique_products" : 2,
  86.             "type" : "order",
  87.             "user" : "rani",
  88.             "geoip" : {
  89.               "country_iso_code" : "EG",
  90.               "location" : {
  91.                 "lon" : 31.3,
  92.                 "lat" : 30.1
  93.               },
  94.               "region_name" : "Cairo Governorate",
  95.               "continent_name" : "Africa",
  96.               "city_name" : "Cairo"
  97.             },
  98.             "event" : {
  99.               "dataset" : "sample_ecommerce"
  100.             }
  101.           }
  102.           ...
  103.         }
  104.       ]
  105.     }
  106.   }
  107.  }
  108. }