Rename feature, feature_vector and feature_query (#37794)

Ranaming as follows:
feature -> rank_feature
feature_vector -> rank_features
feature query -> rank_feature query

Ranaming is done to distinguish from other vector types.

Closes #36723

Author: mayya-sharipova

docs/reference/mapping/types.asciidoc

@@ -43,9 +43,9 @@ string::        <<text,`text`>> and <<keyword,`keyword`>>
 
 <<alias>>::         Defines an alias to an existing field.
 
-<<feature>>::       Record numeric features to boost hits at query time.
+<<rank-feature>>::  Record numeric feature to boost hits at query time.
 
-<<feature-vector>>:: Record numeric feature vectors to boost hits at query time.
+<<rank-features>>:: Record numeric features to boost hits at query time.
 
 <<dense-vector>>::   Record dense vectors of float values.
 
@@ -100,9 +100,9 @@ include::types/percolator.asciidoc[]
 
 include::types/parent-join.asciidoc[]
 
-include::types/feature.asciidoc[]
+include::types/rank-feature.asciidoc[]
 
-include::types/feature-vector.asciidoc[]
+include::types/rank-features.asciidoc[]
 
 include::types/dense-vector.asciidoc[]
 

docs/reference/mapping/types/feature.asciidoc

@@ -0,0 +1,57 @@
+[[rank-feature]]
+=== Rank feature datatype
+
+A `rank_feature` field can index numbers so that they can later be used to boost
+documents in queries with a <<query-dsl-rank-feature-query,`rank_feature`>> query.
+
+[source,js]
+--------------------------------------------------
+PUT my_index
+{
+  "mappings": {
+    "properties": {
+      "pagerank": {
+        "type": "rank_feature" <1>
+      },
+      "url_length": {
+        "type": "rank_feature",
+        "positive_score_impact": false <2>
+      }
+    }
+  }
+}
+
+PUT my_index/_doc/1
+{
+  "pagerank": 8,
+  "url_length": 22
+}
+
+GET my_index/_search
+{
+  "query": {
+    "rank_feature": {
+      "field": "pagerank"
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+<1> Rank feature fields must use the `rank_feature` field type
+<2> Rank features that correlate negatively with the score need to declare it
+
+NOTE: `rank_feature` fields only support single-valued fields and strictly positive
+values. Multi-valued fields and negative values will be rejected.
+
+NOTE: `rank_feature` fields do not support querying, sorting or aggregating. They may
+only be used within <<query-dsl-rank-feature-query,`rank_feature`>> queries.
+
+NOTE: `rank_feature` fields only preserve 9 significant bits for the precision, which
+translates to a relative error of about 0.4%.
+
+Rank features that correlate negatively with the score should set
+`positive_score_impact` to `false` (defaults to `true`). This will be used by
+the <<query-dsl-rank-feature-query,`rank_feature`>> query to modify the scoring formula
+in such a way that the score decreases with the value of the feature instead of
+increasing. For instance in web search, the url length is a commonly used
+feature which correlates negatively with scores.

docs/reference/mapping/types/rank-feature.asciidoc

@@ -1,11 +1,11 @@
-[[feature-vector]]
-=== Feature vector datatype
+[[rank-features]]
+=== Rank features datatype
 
-A `feature_vector` field can index numeric feature vectors, so that they can
+A `rank_features` field can index numeric feature vectors, so that they can
 later be used to boost documents in queries with a
-<<query-dsl-feature-query,`feature`>> query.
+<<query-dsl-rank-feature-query,`rank_feature`>> query.
 
-It is analogous to the <<feature,`feature`>> datatype but is better suited
+It is analogous to the <<rank-feature,`rank_feature`>> datatype but is better suited
 when the list of features is sparse so that it wouldn't be reasonable to add
 one field to the mappings for each of them.
 
@@ -16,7 +16,7 @@ PUT my_index
   "mappings": {
     "properties": {
       "topics": {
-        "type": "feature_vector" <1>
+        "type": "rank_features" <1>
       }
     }
   }
@@ -41,22 +41,22 @@ PUT my_index/_doc/2
 GET my_index/_search
 {
   "query": {
-    "feature": {
+    "rank_feature": {
       "field": "topics.politics"
     }
   }
 }
 --------------------------------------------------
 // CONSOLE
-<1> Feature vector fields must use the `feature_vector` field type
-<2> Feature vector fields must be a hash with string keys and strictly positive numeric values
+<1> Rank features fields must use the `rank_features` field type
+<2> Rank features fields must be a hash with string keys and strictly positive numeric values
 
-NOTE: `feature_vector` fields only support single-valued features and strictly
+NOTE: `rank_features` fields only support single-valued features and strictly
 positive values. Multi-valued fields and zero or negative values will be rejected.
 
-NOTE: `feature_vector` fields do not support sorting or aggregating and may 
-only be queried using <<query-dsl-feature-query,`feature`>> queries.
+NOTE: `rank_features` fields do not support sorting or aggregating and may
+only be queried using <<query-dsl-rank-feature-query,`rank_feature`>> queries.
 
-NOTE: `feature_vector` fields only preserve 9 significant bits for the
+NOTE: `rank_features` fields only preserve 9 significant bits for the
 precision, which translates to a relative error of about 0.4%.
 

docs/reference/mapping/types/feature-vector.asciidoc renamed to docs/reference/mapping/types/rank-features.asciidoc

@@ -1,8 +1,8 @@
-[[query-dsl-feature-query]]
-=== Feature Query
+[[query-dsl-rank-feature-query]]
+=== Rank Feature Query
 
-The `feature` query is a specialized query that only works on
-<<feature,`feature`>> fields and <<feature-vector,`feature_vector`>> fields.
+The `rank_feature` query is a specialized query that only works on
+<<rank-feature,`rank_feature`>> fields and <<rank-features,`rank_features`>> fields.
 Its goal is to boost the score of documents based on the values of numeric
 features. It is typically put in a `should` clause of a
 <<query-dsl-bool-query,`bool`>> query so that its score is added to the score
@@ -32,14 +32,14 @@ PUT test
   "mappings": {
     "properties": {
       "pagerank": {
-        "type": "feature"
+        "type": "rank_feature"
       },
       "url_length": {
-        "type": "feature",
+        "type": "rank_feature",
         "positive_score_impact": false
       },
       "topics": {
-        "type": "feature_vector"
+        "type": "rank_features"
       }
     }
   }
@@ -97,18 +97,18 @@ GET test/_search
       ],
       "should": [
         {
-          "feature": {
+          "rank_feature": {
             "field": "pagerank"
           }
         },
         {
-          "feature": {
+          "rank_feature": {
             "field": "url_length",
             "boost": 0.1
           }
         },
         {
-          "feature": {
+          "rank_feature": {
             "field": "topics.sports",
             "boost": 0.4
           }
@@ -123,28 +123,28 @@ GET test/_search
 [float]
 === Supported functions
 
-The `feature` query supports 3 functions in order to boost scores using the
-values of features. If you do not know where to start, we recommend that you
+The `rank_feature` query supports 3 functions in order to boost scores using the
+values of rank features. If you do not know where to start, we recommend that you
 start with the `saturation` function, which is the default when no function is
 provided.
 
 [float]
 ==== Saturation
 
 This function gives a score that is equal to `S / (S + pivot)` where `S` is the
-value of the feature and `pivot` is a configurable pivot value so that the
+value of the rank feature and `pivot` is a configurable pivot value so that the
 result will be less than +0.5+ if `S` is less than pivot and greater than +0.5+
 otherwise. Scores are always is +(0, 1)+.
 
-If the feature has a negative score impact then the function will be computed as
+If the rank feature has a negative score impact then the function will be computed as
 `pivot / (S + pivot)`, which decreases when `S` increases.
 
 [source,js]
 --------------------------------------------------
 GET test/_search
 {
   "query": {
-    "feature": {
+    "rank_feature": {
       "field": "pagerank",
       "saturation": {
         "pivot": 8
@@ -166,7 +166,7 @@ train a good pivot value.
 GET test/_search
 {
   "query": {
-    "feature": {
+    "rank_feature": {
       "field": "pagerank",
       "saturation": {}
     }
@@ -180,17 +180,17 @@ GET test/_search
 ==== Logarithm
 
 This function gives a score that is equal to `log(scaling_factor + S)` where
-`S` is the value of the feature and `scaling_factor` is a configurable scaling
+`S` is the value of the rank feature and `scaling_factor` is a configurable scaling
 factor. Scores are unbounded.
 
-This function only supports features that have a positive score impact.
+This function only supports rank features that have a positive score impact.
 
 [source,js]
 --------------------------------------------------
 GET test/_search
 {
   "query": {
-    "feature": {
+    "rank_feature": {
       "field": "pagerank",
       "log": {
         "scaling_factor": 4
@@ -219,7 +219,7 @@ that you stick to the `saturation` function instead.
 GET test/_search
 {
   "query": {
-    "feature": {
+    "rank_feature": {
       "field": "pagerank",
       "sigmoid": {
         "pivot": 7,

docs/reference/query-dsl/feature-query.asciidoc renamed to docs/reference/query-dsl/rank-feature-query.asciidoc

@@ -211,7 +211,7 @@ There are faster alternative query types that can efficiently skip
 non-competitive hits:
 
 * If you want to boost documents on some static fields, use
- <<query-dsl-feature-query, Feature Query>>.
+ <<query-dsl-rank-feature-query, Rank Feature Query>>.
 
 
 ==== Transition from Function Score Query

docs/reference/query-dsl/script-score-query.asciidoc

@@ -23,7 +23,7 @@ A query that allows to modify the score of a sub-query with a script.
 This query finds queries that are stored as documents that match with
 the specified document.
 
-<<query-dsl-feature-query,`feature` query>>::
+<<query-dsl-rank-feature-query,`rank_feature` query>>::
 
 A query that computes scores based on the values of numeric features and is
 able to efficiently skip non-competitive hits.
@@ -40,6 +40,6 @@ include::script-score-query.asciidoc[]
 
 include::percolate-query.asciidoc[]
 
-include::feature-query.asciidoc[]
+include::rank-feature-query.asciidoc[]
 
 include::wrapper-query.asciidoc[]

docs/reference/query-dsl/special-queries.asciidoc

@@ -20,7 +20,7 @@
 package org.elasticsearch.index.mapper;
 
 import org.elasticsearch.index.mapper.MetadataFieldMapper.TypeParser;
-import org.elasticsearch.index.query.FeatureQueryBuilder;
+import org.elasticsearch.index.query.RankFeatureQueryBuilder;
 import org.elasticsearch.plugins.MapperPlugin;
 import org.elasticsearch.plugins.Plugin;
 import org.elasticsearch.plugins.SearchPlugin;
@@ -37,22 +37,23 @@ public Map<String, Mapper.TypeParser> getMappers() {
         Map<String, Mapper.TypeParser> mappers = new LinkedHashMap<>();
         mappers.put(ScaledFloatFieldMapper.CONTENT_TYPE, new ScaledFloatFieldMapper.TypeParser());
         mappers.put(TokenCountFieldMapper.CONTENT_TYPE, new TokenCountFieldMapper.TypeParser());
-        mappers.put(FeatureFieldMapper.CONTENT_TYPE, new FeatureFieldMapper.TypeParser());
-        mappers.put(FeatureVectorFieldMapper.CONTENT_TYPE, new FeatureVectorFieldMapper.TypeParser());
+        mappers.put(RankFeatureFieldMapper.CONTENT_TYPE, new RankFeatureFieldMapper.TypeParser());
+        mappers.put(RankFeaturesFieldMapper.CONTENT_TYPE, new RankFeaturesFieldMapper.TypeParser());
         mappers.put(DenseVectorFieldMapper.CONTENT_TYPE, new DenseVectorFieldMapper.TypeParser());
         mappers.put(SparseVectorFieldMapper.CONTENT_TYPE, new SparseVectorFieldMapper.TypeParser());
         return Collections.unmodifiableMap(mappers);
     }
 
     @Override
     public Map<String, TypeParser> getMetadataMappers() {
-        return Collections.singletonMap(FeatureMetaFieldMapper.CONTENT_TYPE, new FeatureMetaFieldMapper.TypeParser());
+        return Collections.singletonMap(RankFeatureMetaFieldMapper.CONTENT_TYPE, new RankFeatureMetaFieldMapper.TypeParser());
     }
 
     @Override
     public List<QuerySpec<?>> getQueries() {
         return Collections.singletonList(
-                new QuerySpec<>(FeatureQueryBuilder.NAME, FeatureQueryBuilder::new, p -> FeatureQueryBuilder.PARSER.parse(p, null)));
+            new QuerySpec<>(RankFeatureQueryBuilder.NAME, RankFeatureQueryBuilder::new,
+                p -> RankFeatureQueryBuilder.PARSER.parse(p, null)));
     }
 
 }