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.

Rank field types

The following table lists all rank field types that OpenSearch supports.

Field data typeDescription
rank_featureBoosts or decreases the relevance score of documents.
rank_featuresBoosts or decreases the relevance score of documents. Used when the list of features is sparse.

Rank feature and rank features fields can be queried with rank feature queries only. They do not support aggregating or sorting.

Rank feature

A rank feature field type uses a positive float value to boost or decrease the relevance score of a document in a rank_feature query. By default, this value boosts the relevance score. To decrease the relevance score, set the optional positive_score_impact parameter to false.

Example

Create a mapping with a rank feature field:

  1. PUT chessplayers
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "name" : {
  6.         "type" : "text"
  7.       },
  8.       "rating": {
  9.         "type": "rank_feature" 
  10.       },
  11.       "age": {
  12.         "type": "rank_feature",
  13.         "positive_score_impact": false 
  14.       }
  15.     }
  16.   }
  17. }

copy

Index three documents with a rank_feature field that boosts the score (rating) and a rank_feature field that decreases the score (age):

  1. PUT testindex1/_doc/1
  2. {
  3.   "name" : "John Doe",
  4.   "rating" : 2554,
  5.   "age" : 75
  6. }

copy

  1. PUT testindex1/_doc/2
  2. {
  3.   "name" : "Kwaku Mensah",
  4.   "rating" : 2067,
  5.   "age": 10
  6. }

copy

  1. PUT testindex1/_doc/3
  2. {
  3.   "name" : "Nikki Wolf",
  4.   "rating" : 1864,
  5.   "age" : 22
  6. }

copy

Rank feature query

Using a rank feature query, you can rank players by rating, by age, or by both rating and age. If you rank players by rating, higher-rated players will have higher relevance scores. If you rank players by age, younger players will have higher relevance scores.

Use a rank feature query to search for players based on age and rating:

  1. GET chessplayers/_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "should": [
  6.         {
  7.           "rank_feature": {
  8.             "field": "rating"
  9.           }
  10.         },
  11.         {
  12.           "rank_feature": {
  13.             "field": "age"
  14.           }
  15.         }
  16.       ]
  17.     }
  18.   }
  19. }

copy

When ranked by both age and rating, younger players and players who are more highly ranked score better:

  1. {
  2.   "took" : 2,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 3,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 1.2093145,
  16.     "hits" : [
  17.       {
  18.         "_index" : "chessplayers",
  19.         "_type" : "_doc",
  20.         "_id" : "2",
  21.         "_score" : 1.2093145,
  22.         "_source" : {
  23.           "name" : "Kwaku Mensah",
  24.           "rating" : 1967,
  25.           "age" : 10
  26.         }
  27.       },
  28.       {
  29.         "_index" : "chessplayers",
  30.         "_type" : "_doc",
  31.         "_id" : "3",
  32.         "_score" : 1.0150313,
  33.         "_source" : {
  34.           "name" : "Nikki Wolf",
  35.           "rating" : 1864,
  36.           "age" : 22
  37.         }
  38.       },
  39.       {
  40.         "_index" : "chessplayers",
  41.         "_type" : "_doc",
  42.         "_id" : "1",
  43.         "_score" : 0.8098284,
  44.         "_source" : {
  45.           "name" : "John Doe",
  46.           "rating" : 2554,
  47.           "age" : 75
  48.         }
  49.       }
  50.     ]
  51.   }
  52. }

Rank features

A rank features field type is similar to the rank feature field type, but it is more suitable for a sparse list of features. A rank features field can index numeric feature vectors that are later used to boost or decrease documents’ relevance scores in rank_feature queries.

Example

Create a mapping with a rank features field:

  1. PUT testindex1
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "correlations": {
  6.         "type": "rank_features" 
  7.       }
  8.     }
  9.   }
  10. }

copy

To index a document with a rank features field, use a hashmap with string keys and positive float values:

  1. PUT testindex1/_doc/1
  2. {
  3.   "correlations": { 
  4.     "young kids" : 1,
  5.     "older kids" : 15,
  6.     "teens" : 25.9
  7.   }
  8. }

copy

  1. PUT testindex1/_doc/2
  2. {
  3.   "correlations": {
  4.     "teens": 10,
  5.     "adults": 95.7
  6.   }
  7. }

copy

Query the documents using a rank feature query:

  1. GET testindex1/_search
  2. {
  3.   "query": {
  4.     "rank_feature": {
  5.       "field": "correlations.teens"
  6.     }
  7.   }
  8. }

copy

The response is ranked by relevance score:

  1. {
  2.   "took" : 123,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 2,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 0.6258503,
  16.     "hits" : [
  17.       {
  18.         "_index" : "testindex1",
  19.         "_type" : "_doc",
  20.         "_id" : "1",
  21.         "_score" : 0.6258503,
  22.         "_source" : {
  23.           "correlations" : {
  24.             "young kids" : 1,
  25.             "older kids" : 15,
  26.             "teens" : 25.9
  27.           }
  28.         }
  29.       },
  30.       {
  31.         "_index" : "testindex1",
  32.         "_type" : "_doc",
  33.         "_id" : "2",
  34.         "_score" : 0.39263803,
  35.         "_source" : {
  36.           "correlations" : {
  37.             "teens" : 10,
  38.             "adults" : 95.7
  39.           }
  40.         }
  41.       }
  42.     ]
  43.   }
  44. }

Rank feature and rank features fields use top nine significant bits for precision, leading to about 0.4% relative error. Values are stored with a relative precision of 2−8 = 0.00390625.