Add a feature_vector field. (#31102)

This field is similar to the `feature` field but is better suited to index
sparse feature vectors. A use-case for this field could be to record topics
associated with every documents alongside a metric that quantifies how well
the topic is connected to this document, and then boost queries based on the
topics that the logged user is interested in.

Relates #27552

Author: jpountz

docs/reference/mapping/types.asciidoc

@@ -42,6 +42,8 @@ string::        <<text,`text`>> and <<keyword,`keyword`>>
 
 <<feature>>::       Record numeric features to boost hits at query time.
 
+<<feature-vector>>:: Record numeric feature vectors to boost hits at query time.
+
 [float]
 === Multi-fields
 
@@ -90,4 +92,4 @@ include::types/parent-join.asciidoc[]
 
 include::types/feature.asciidoc[]
 
-
+include::types/feature-vector.asciidoc[]

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

@@ -0,0 +1,64 @@
+[[feature-vector]]
+=== Feature vector datatype
+
+A `feature_vector` 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.
+
+It is analogous to the <<feature,`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.
+
+[source,js]
+--------------------------------------------------
+PUT my_index
+{
+  "mappings": {
+    "_doc": {
+      "properties": {
+        "topics": {
+          "type": "feature_vector" <1>
+        }
+      }
+    }
+  }
+}
+
+PUT my_index/_doc/1
+{
+  "topics": { <2>
+    "politics": 20,
+    "economics": 50.8
+  }
+}
+
+PUT my_index/_doc/2
+{
+  "topics": {
+    "politics": 5.2,
+    "sports": 80.1
+  }
+}
+
+GET my_index/_search
+{
+  "query": {
+    "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
+
+NOTE: `feature_vector` 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: `feature_vector` fields only preserve 9 significant bits for the
+precision, which translates to a relative error of about 0.4%.
+

docs/reference/query-dsl/feature-query.asciidoc

@@ -2,9 +2,10 @@
 === Feature Query
 
 The `feature` query is a specialized query that only works on
-<<feature,`feature`>> 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
+<<feature,`feature`>> fields and <<feature-vector,`feature_vector`>> 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
 of the query.
 
 Compared to using <<query-dsl-function-score-query,`function_score`>> or other
@@ -13,7 +14,16 @@ efficiently skip non-competitive hits when
 <<search-uri-request,`track_total_hits`>> is set to `false`. Speedups may be
 spectacular.
 
-Here is an example:
+Here is an example that indexes various features:
+ - https://en.wikipedia.org/wiki/PageRank[`pagerank`], a measure of the
+   importance of a website,
+ - `url_length`, the length of the url, which typically correlates negatively
+   with relevance,
+ - `topics`, which associates a list of topics with every document alongside a
+   measure of how well the document is connected to this topic.
+
+Then the example includes an example query that searches for `"2016"` and boosts
+based or `pagerank`, `url_length` and the `sports` topic.
 
 [source,js]
 --------------------------------------------------
@@ -28,6 +38,9 @@ PUT test
         "url_length": {
           "type": "feature",
           "positive_score_impact": false
+        },
+        "topics": {
+          "type": "feature_vector"
         }
       }
     }
@@ -36,32 +49,73 @@ PUT test
 
 PUT test/_doc/1
 {
-  "pagerank": 10,
-  "url_length": 50
+  "url": "http://en.wikipedia.org/wiki/2016_Summer_Olympics",
+  "content": "Rio 2016",
+  "pagerank": 50.3,
+  "url_length": 42,
+  "topics": {
+    "sports": 50,
+    "brazil": 30
+  }
 }
 
 PUT test/_doc/2
 {
-  "pagerank": 100,
-  "url_length": 20
+  "url": "http://en.wikipedia.org/wiki/2016_Brazilian_Grand_Prix",
+  "content": "Formula One motor race held on 13 November 2016 at the Autódromo José Carlos Pace in São Paulo, Brazil",
+  "pagerank": 50.3,
+  "url_length": 47,
+  "topics": {
+    "sports": 35,
+    "formula one": 65,
+    "brazil": 20
+  }
 }
 
-POST test/_refresh
-
-GET test/_search
+PUT test/_doc/3
 {
-  "query": {
-    "feature": {
-      "field": "pagerank"
-    }
+  "url": "http://en.wikipedia.org/wiki/Deadpool_(film)",
+  "content": "Deadpool is a 2016 American superhero film",
+  "pagerank": 50.3,
+  "url_length": 37,
+  "topics": {
+    "movies": 60,
+    "super hero": 65
   }
 }
 
-GET test/_search
+POST test/_refresh
+
+GET test/_search 
 {
   "query": {
-    "feature": {
-      "field": "url_length"
+    "bool": {
+      "must": [
+        {
+          "match": {
+            "content": "2016"
+          }
+        }
+      ],
+      "should": [
+        {
+          "feature": {
+            "field": "pagerank"
+          }
+        },
+        {
+          "feature": {
+            "field": "url_length",
+            "boost": 0.1
+          }
+        },
+        {
+          "feature": {
+            "field": "topics.sports",
+            "boost": 0.4
+          }
+        }
+      ]
     }
   }
 }

modules/mapper-extras/src/main/java/org/elasticsearch/index/mapper/FeatureFieldMapper.java

@@ -165,8 +165,7 @@ public Query existsQuery(QueryShardContext context) {
 
         @Override
         public IndexFieldData.Builder fielddataBuilder(String fullyQualifiedIndexName) {
-            failIfNoDocValues();
-            return new DocValuesIndexFieldData.Builder();
+            throw new UnsupportedOperationException("[feature] fields do not support sorting, scripting or aggregating");
         }
 
         @Override
@@ -229,10 +228,6 @@ protected String contentType() {
     protected void doXContentBody(XContentBuilder builder, boolean includeDefaults, Params params) throws IOException {
         super.doXContentBody(builder, includeDefaults, params);
 
-        if (includeDefaults || fieldType().nullValue() != null) {
-            builder.field("null_value", fieldType().nullValue());
-        }
-
         if (includeDefaults || fieldType().positiveScoreImpact() == false) {
             builder.field("positive_score_impact", fieldType().positiveScoreImpact());
         }