Unify custom scores

===================

The custom boost factor, custom script boost and the filters function query all do the same thing: They take a query and for each found document compute a new score based on the query score and some script, come custom boost factor or a combination of these two. However, the json format for these three functionalities is very different. This makes it hard to add new functions.

This commit introduces one keyword <code>function_score</code> for all three functions.

The new format can be used to either compute a new score with one function:

	"function_score": {
        "(query|filter)": {},
        "boost": "boost for the whole query",
        "function": {}
    }

or allow to combine the newly computed scores

    "function_score": {
        "(query|filter)": {},
        "boost": "boost for the whole query",
        "functions": [
            {
                "filter": {},
                "function": {}
            },
            {
                "function": {}
            }
        ],
        "score_mode": "(mult|max|...)"
    }

<code>function</code> here can be either

	"script_score": {
    	"lang": "lang",
    	"params": {
        	"param1": "value1",
        	"param2": "value2"
   		 },
    	"script": "some script"
	}

or

	"boost_factor" : number

New custom functions can be added via the function score module.

Changes
---------

The custom boost factor query

	"custom_boost_factor" : {
    	"query" : {
        	....
    	},
    	"boost_factor" : 5.2
	}

becomes

	"function_score" : {
    	"query" : {
        	....
    	},
    	"boost_factor" : 5.2
	}

The custom script score

	"custom_score" : {
    	"query" : {
        	....
	    },
    	"params" : {
        	"param1" : 2,
 	       	"param2" : 3.1
    	},
	    "script" : "_score * doc['my_numeric_field'].value / pow(param1, param2)"
	}

becomes

	"custom_score" : {
    	"query" : {
        	....
	    },
	    "script_score" : {

    		"params" : {
        		"param1" : 2,
 	       		"param2" : 3.1
    		},
	    	"script" : "_score * doc['my_numeric_field'].value / pow(param1, param2)"
	    }
	}

and the custom filters score query

    "custom_filters_score" : {
        "query" : {
            "match_all" : {}
       	 },
        "filters" : [
            {
                "filter" : { "range" : { "age" : {"from" : 0, "to" : 10} } },
                "boost" : "3"
            },
            {
                "filter" : { "range" : { "age" : {"from" : 10, "to" : 20} } },
                "script" : "_score * doc['my_numeric_field'].value / pow(param1, param2)"
            }
        ],
        "score_mode" : "first",
        "params" : {
        	"param1" : 2,
 	       	"param2" : 3.1
    	}
    	"score_mode" : "first"
    }

becomes:

    "function_score" : {
        "query" : {
            "match_all" : {}
       	},
        "functions" : [
            {
                "filter" : { "range" : { "age" : {"from" : 0, "to" : 10} } },
                "boost" : "3"
            },
            {
                "filter" : { "range" : { "age" : {"from" : 10, "to" : 20} } },
                "script_score" : {
                	"script" : "_score * doc['my_numeric_field'].value / pow(param1, param2)",
                	"params" : {
        				"param1" : 2,
 	       				"param2" : 3.1
    				}

            	}
            }
        ],
        "score_mode" : "first",
    }

Partially closes issue #3423

src/main/java/org/elasticsearch/common/lucene/search/function/BoostScoreFunction.java

@@ -49,7 +49,7 @@ public float score(int docId, float subQueryScore) {
     }
 
     @Override
-    public float factor(int docId) {
+    public double factor(int docId) {
         return boost;
     }
 

src/main/java/org/elasticsearch/common/lucene/search/function/FiltersFunctionScoreQuery.java

@@ -287,7 +287,7 @@ public int nextDoc() throws IOException {
         @Override
         public float score() throws IOException {
             int docId = scorer.docID();
-            float factor = 1.0f;
+            double factor = 1.0f;
             if (scoreMode == ScoreMode.First) {
                 for (int i = 0; i < filterFunctions.length; i++) {
                     if (docSets[i].get(docId)) {
@@ -296,7 +296,7 @@ public float score() throws IOException {
                     }
                 }
             } else if (scoreMode == ScoreMode.Max) {
-                float maxFactor = Float.NEGATIVE_INFINITY;
+                double maxFactor = Double.NEGATIVE_INFINITY;
                 for (int i = 0; i < filterFunctions.length; i++) {
                     if (docSets[i].get(docId)) {
                         maxFactor = Math.max(filterFunctions[i].function.factor(docId), maxFactor);
@@ -306,7 +306,7 @@ public float score() throws IOException {
                     factor = maxFactor;
                 }
             } else if (scoreMode == ScoreMode.Min) {
-                float minFactor = Float.POSITIVE_INFINITY;
+                double minFactor = Double.POSITIVE_INFINITY;
                 for (int i = 0; i < filterFunctions.length; i++) {
                     if (docSets[i].get(docId)) {
                         minFactor = Math.min(filterFunctions[i].function.factor(docId), minFactor);
@@ -322,7 +322,7 @@ public float score() throws IOException {
                     }
                 }
             } else { // Avg / Total
-                float totalFactor = 0.0f;
+                double totalFactor = 0.0f;
                 int count = 0;
                 for (int i = 0; i < filterFunctions.length; i++) {
                     if (docSets[i].get(docId)) {
@@ -341,7 +341,7 @@ public float score() throws IOException {
                 factor = maxBoost;
             }
             float score = scorer.score();
-            return subQueryBoost * score * factor;
+            return (float)(subQueryBoost * score * factor);
         }
 
         @Override

src/main/java/org/elasticsearch/common/lucene/search/function/FunctionScoreQuery.java

@@ -36,12 +36,21 @@ public class FunctionScoreQuery extends Query {
 
     Query subQuery;
     final ScoreFunction function;
+    float maxBoost = Float.MAX_VALUE;
 
     public FunctionScoreQuery(Query subQuery, ScoreFunction function) {
         this.subQuery = subQuery;
         this.function = function;
     }
 
+    public void setMaxBoost(float maxBoost) {
+        this.maxBoost = maxBoost;
+    }
+
+    public float getMaxBoost() {
+        return this.maxBoost;
+    }
+
     public Query getSubQuery() {
         return subQuery;
     }
@@ -53,7 +62,9 @@ public ScoreFunction getFunction() {
     @Override
     public Query rewrite(IndexReader reader) throws IOException {
         Query newQ = subQuery.rewrite(reader);
-        if (newQ == subQuery) return this;
+        if (newQ == subQuery){
+            return this;
+        }
         FunctionScoreQuery bq = (FunctionScoreQuery) this.clone();
         bq.subQuery = newQ;
         return bq;
@@ -101,7 +112,7 @@ public Scorer scorer(AtomicReaderContext context, boolean scoreDocsInOrder, bool
                 return null;
             }
             function.setNextReader(context);
-            return new CustomBoostFactorScorer(this, subQueryScorer, function);
+            return new CustomBoostFactorScorer(this, subQueryScorer, function, maxBoost);
         }
 
         @Override
@@ -121,18 +132,20 @@ public Explanation explain(AtomicReaderContext context, int doc) throws IOExcept
         }
     }
 
-
     static class CustomBoostFactorScorer extends Scorer {
 
         private final float subQueryBoost;
         private final Scorer scorer;
         private final ScoreFunction function;
+        private final float maxBoost;
 
-        private CustomBoostFactorScorer(CustomBoostFactorWeight w, Scorer scorer, ScoreFunction function) throws IOException {
+        private CustomBoostFactorScorer(CustomBoostFactorWeight w, Scorer scorer, ScoreFunction function, float maxBoost)
+                throws IOException {
             super(w);
             this.subQueryBoost = w.getQuery().getBoost();
             this.scorer = scorer;
             this.function = function;
+            this.maxBoost = maxBoost;
         }
 
         @Override
@@ -152,7 +165,8 @@ public int nextDoc() throws IOException {
 
         @Override
         public float score() throws IOException {
-            return subQueryBoost * function.score(scorer.docID(), scorer.score());
+            float factor = (float)function.score(scorer.docID(), scorer.score());
+            return subQueryBoost * Math.min(maxBoost, factor);
         }
 
         @Override
@@ -166,7 +180,6 @@ public long cost() {
         }
     }
 
-
     public String toString(String field) {
         StringBuilder sb = new StringBuilder();
         sb.append("custom score (").append(subQuery.toString(field)).append(",function=").append(function).append(')');
@@ -175,15 +188,14 @@ public String toString(String field) {
     }
 
     public boolean equals(Object o) {
-        if (getClass() != o.getClass()) return false;
+        if (getClass() != o.getClass())
+            return false;
         FunctionScoreQuery other = (FunctionScoreQuery) o;
-        return this.getBoost() == other.getBoost()
-                && this.subQuery.equals(other.subQuery)
-                && this.function.equals(other.function);
+        return this.getBoost() == other.getBoost() && this.subQuery.equals(other.subQuery) && this.function.equals(other.function)
+                && this.maxBoost == other.maxBoost;
     }
 
     public int hashCode() {
         return subQuery.hashCode() + 31 * function.hashCode() ^ Float.floatToIntBits(getBoost());
     }
 }
-

src/main/java/org/elasticsearch/common/lucene/search/function/ScoreFunction.java

@@ -31,7 +31,7 @@ public interface ScoreFunction {
 
     float score(int docId, float subQueryScore);
 
-    float factor(int docId);
+    double factor(int docId);
 
     Explanation explainScore(int docId, Explanation subQueryExpl);
 

src/main/java/org/elasticsearch/common/lucene/search/function/ScriptScoreFunction.java

@@ -0,0 +1,86 @@
+/*
+ * Licensed to ElasticSearch and Shay Banon under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. ElasticSearch licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.common.lucene.search.function;
+
+import org.apache.lucene.index.AtomicReaderContext;
+import org.apache.lucene.search.Explanation;
+import org.elasticsearch.script.ExplainableSearchScript;
+import org.elasticsearch.script.SearchScript;
+
+import java.util.Map;
+
+public class ScriptScoreFunction implements ScoreFunction {
+
+    private final String sScript;
+
+    private final Map<String, Object> params;
+
+    private final SearchScript script;
+
+    public ScriptScoreFunction(String sScript, Map<String, Object> params, SearchScript script) {
+        this.sScript = sScript;
+        this.params = params;
+        this.script = script;
+    }
+
+    @Override
+    public void setNextReader(AtomicReaderContext ctx) {
+        script.setNextReader(ctx);
+    }
+
+    @Override
+    public float score(int docId, float subQueryScore) {
+        script.setNextDocId(docId);
+        script.setNextScore(subQueryScore);
+        return script.runAsFloat();
+    }
+
+    @Override
+    public double factor(int docId) {
+        // just the factor, so don't provide _score
+        script.setNextDocId(docId);
+        return script.runAsFloat();
+    }
+
+    @Override
+    public Explanation explainScore(int docId, Explanation subQueryExpl) {
+        Explanation exp;
+        if (script instanceof ExplainableSearchScript) {
+            script.setNextDocId(docId);
+            script.setNextScore(subQueryExpl.getValue());
+            exp = ((ExplainableSearchScript) script).explain(subQueryExpl);
+        } else {
+            double score = score(docId, subQueryExpl.getValue());
+            exp = new Explanation((float)score, "script score function: composed of:");
+            exp.addDetail(subQueryExpl);
+        }
+        return exp;
+    }
+
+    @Override
+    public Explanation explainFactor(int docId) {
+        return new Explanation((float)factor(docId), "script_factor");
+    }
+
+    @Override
+    public String toString() {
+        return "script[" + sScript + "], params [" + params + "]";
+    }
+}

src/main/java/org/elasticsearch/index/query/CustomBoostFactorQueryBuilder.java

@@ -20,13 +20,14 @@
 package org.elasticsearch.index.query;
 
 import org.elasticsearch.common.xcontent.XContentBuilder;
+import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder;
 
 import java.io.IOException;
 
 /**
  * A query that simply applies the boost factor to another query (multiply it).
- *
- *
+ * 
+ * @deprecated use {@link FunctionScoreQueryBuilder} instead.
  */
 public class CustomBoostFactorQueryBuilder extends BaseQueryBuilder {
 
@@ -35,9 +36,11 @@ public class CustomBoostFactorQueryBuilder extends BaseQueryBuilder {
     private float boostFactor = -1;
 
     /**
-     * A query that simply applies the boost factor to another query (multiply it).
-     *
-     * @param queryBuilder The query to apply the boost factor to.
+     * A query that simply applies the boost factor to another query (multiply
+     * it).
+     * 
+     * @param queryBuilder
+     *            The query to apply the boost factor to.
      */
     public CustomBoostFactorQueryBuilder(QueryBuilder queryBuilder) {
         this.queryBuilder = queryBuilder;

src/main/java/org/elasticsearch/index/query/CustomBoostFactorQueryParser.java

@@ -25,11 +25,12 @@
 import org.elasticsearch.common.lucene.search.function.BoostScoreFunction;
 import org.elasticsearch.common.lucene.search.function.FunctionScoreQuery;
 import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.index.query.functionscore.FunctionScoreQueryParser;
 
 import java.io.IOException;
 
 /**
- *
+ * @deprecated use {@link FunctionScoreQueryParser} instead.
  */
 public class CustomBoostFactorQueryParser implements QueryParser {
 
@@ -41,7 +42,7 @@ public CustomBoostFactorQueryParser() {
 
     @Override
     public String[] names() {
-        return new String[]{NAME, Strings.toCamelCase(NAME)};
+        return new String[] { NAME, Strings.toCamelCase(NAME) };
     }
 
     @Override
@@ -63,15 +64,17 @@ public Query parse(QueryParseContext parseContext) throws IOException, QueryPars
                     query = parseContext.parseInnerQuery();
                     queryFound = true;
                 } else {
-                    throw new QueryParsingException(parseContext.index(), "[custom_boost_factor] query does not support [" + currentFieldName + "]");
+                    throw new QueryParsingException(parseContext.index(), "[custom_boost_factor] query does not support ["
+                            + currentFieldName + "]");
                 }
             } else if (token.isValue()) {
                 if ("boost_factor".equals(currentFieldName) || "boostFactor".equals(currentFieldName)) {
                     boostFactor = parser.floatValue();
                 } else if ("boost".equals(currentFieldName)) {
                     boost = parser.floatValue();
                 } else {
-                    throw new QueryParsingException(parseContext.index(), "[custom_boost_factor] query does not support [" + currentFieldName + "]");
+                    throw new QueryParsingException(parseContext.index(), "[custom_boost_factor] query does not support ["
+                            + currentFieldName + "]");
                 }
             }
         }

src/main/java/org/elasticsearch/index/query/CustomFiltersScoreQueryBuilder.java

@@ -22,13 +22,17 @@
 import com.google.common.collect.Maps;
 import gnu.trove.list.array.TFloatArrayList;
 import org.elasticsearch.common.xcontent.XContentBuilder;
+import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder;
 
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Map;
 
 /**
- * A query that uses a filters with a script associated with them to compute the score.
+ * A query that uses a filters with a script associated with them to compute the
+ * score.
+ * 
+ * @deprecated use {@link FunctionScoreQueryBuilder} instead.
  */
 public class CustomFiltersScoreQueryBuilder extends BaseQueryBuilder implements BoostableQueryBuilder<CustomFiltersScoreQueryBuilder> {
 
@@ -108,8 +112,9 @@ public CustomFiltersScoreQueryBuilder maxBoost(float maxBoost) {
     }
 
     /**
-     * Sets the boost for this query.  Documents matching this query will (in addition to the normal
-     * weightings) have their score multiplied by the boost provided.
+     * Sets the boost for this query. Documents matching this query will (in
+     * addition to the normal weightings) have their score multiplied by the
+     * boost provided.
      */
     public CustomFiltersScoreQueryBuilder boost(float boost) {
         this.boost = boost;