Query DSL: custom score (scripted) query

[kimchy]

custom_score query allows to wrap another query and customize the scoring of it optionally with a computation derived from other field values in the doc (numeric ones). Here is a simple sample:

"custom_score" : {
    "query" : {
        ....
    },
    "script" : "score * doc['my_numeric_field'].value"
}

The script uses mvel (http://mvel.codehaus.org/) which gives a lot of flexibility in terms of what can be computed and is really fast. Other options considered were building a Json based AST (which will be faster, and might be implemented in the future), or using javascript, which is not as fast on the JVM (rhino).

There are "extensions" to mvel provided, they include the score variable, which is the score of the internal query. The idea of providing the score and let the user use it is to allow for complete control over the scoring, without internally multiplying whatever the script produced with the score. This allows for the sub query score to be discarded if needed, or computed on a different "scale" than multiplying.

It also provides all the Math functions (will be listed in the final docs). The more interesting one is the doc[field_name], which actually returns an object that has the following common properties:

• doc['field_name'].value: The native numeric value of the field. For example, if its a short type, it will be short.
• doc['field_name'].values: The native numeric array values of the field. For example, if its a short type, it will be short[]. Remember, a field can have several values within a single doc. Returns an empty array if the field has no values.
• doc['field_name'].stringValue: The string value of the field.
• doc['field_name'].doubleValue: The converted double of the field. Replace double with int, long, float, short, byte. Returns an empty array if the field has no values.
• doc['field_name'].doubleValues: A converted double values array.
• doc['field_name'].date: Applies only to date / long (timestamp) types, returns a MutableDateTime (http://joda-time.sourceforge.net/api-release/org/joda/time/MutableDateTime.html) allowing to get date / time specific data.
• doc['field_name'].dates: Applies only to date / long (timestamp) types, returns a MutableDateTime array (http://joda-time.sourceforge.net/api-release/org/joda/time/MutableDateTime.html) allowing to get date / time specific data.
• doc['field_name'].empty: A boolean indicating if the field has no values within the doc.
• doc['field_name'].multiValued: A boolean indicating that the field has several values within the corpus.

custom_score also allows to accept parameters to scripts (allowing to reuse scripts for better performance). Parameters are simple json object that can then be accessed in the script, for example:

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

[kimchy]

Query DSL: custom score (scripted) query, closed by 751c56f.