scripts: add explainable script again

explainable scripts were removed in #7245 but they were used.
This commit adds them again.

closes #8561

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

@@ -22,6 +22,8 @@
 import org.apache.lucene.search.Explanation;
 import org.elasticsearch.common.lucene.ReaderContextAware;
 
+import java.io.IOException;
+
 /**
  *
  */
@@ -31,7 +33,7 @@ public abstract class ScoreFunction implements ReaderContextAware {
 
     public abstract double score(int docId, float subQueryScore);
 
-    public abstract Explanation explainScore(int docId, float subQueryScore);
+    public abstract Explanation explainScore(int docId, float subQueryScore) throws IOException;
 
     public CombineFunction getDefaultScoreCombiner() {
         return scoreCombiner;

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

@@ -23,6 +23,7 @@
 import org.apache.lucene.search.Explanation;
 import org.apache.lucene.search.Scorer;
 import org.elasticsearch.script.ScriptException;
+import org.elasticsearch.script.ExplainableSearchScript;
 import org.elasticsearch.script.SearchScript;
 
 import java.io.IOException;
@@ -105,14 +106,21 @@ public double score(int docId, float subQueryScore) {
     }
 
     @Override
-    public Explanation explainScore(int docId, float subQueryScore) {
+    public Explanation explainScore(int docId, float subQueryScore) throws IOException {
         Explanation exp;
-        double score = score(docId, subQueryScore);
-        String explanation = "script score function, computed with script:\"" + sScript;
-        if (params != null) {
-            explanation += "\" and parameters: \n" + params.toString();
+        if (script instanceof ExplainableSearchScript) {
+            script.setNextDocId(docId);
+            scorer.docid = docId;
+            scorer.score = subQueryScore;
+            exp = ((ExplainableSearchScript) script).explain(subQueryScore);
+        } else {
+            double score = score(docId, subQueryScore);
+            String explanation = "script score function, computed with script:\"" + sScript;
+            if (params != null) {
+                explanation += "\" and parameters: \n" + params.toString();
+            }
+            exp = new Explanation(CombineFunction.toFloat(score), explanation);
         }
-        exp = new Explanation(CombineFunction.toFloat(score), explanation);
         return exp;
     }
 

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

@@ -65,7 +65,7 @@ public double score(int docId, float subQueryScore) {
     }
 
     @Override
-    public Explanation explainScore(int docId, float score) {
+    public Explanation explainScore(int docId, float score) throws IOException {
         Explanation functionScoreExplanation;
         Explanation functionExplanation = scoreFunction.explainScore(docId, score);
         functionScoreExplanation = new ComplexExplanation(true, functionExplanation.getValue() * (float) getWeight(), "product of:");

src/main/java/org/elasticsearch/script/ExplainableSearchScript.java

@@ -0,0 +1,59 @@
+/*
+ * Licensed to Elasticsearch 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.script;
+
+/*
+ * Licensed to Elasticsearch 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.
+ */
+
+import org.apache.lucene.search.Explanation;
+
+import java.io.IOException;
+
+/**
+ * To be implemented by {@link SearchScript} which can provided an {@link Explanation} of the score
+ * This is currently not used inside elasticsearch but it is used, see for example here:
+ * https://github.com/elasticsearch/elasticsearch/issues/8561
+ */
+public interface ExplainableSearchScript extends SearchScript {
+
+    /**
+     * Build the explanation of the current document being scored
+     *
+     * @param score the score
+     */
+    Explanation explain(float score) throws IOException;
+
+}

src/test/java/org/elasticsearch/search/functionscore/ExplainableScriptPlugin.java

@@ -0,0 +1,41 @@
+/*
+ * Licensed to Elasticsearch 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.search.functionscore;
+
+import org.elasticsearch.plugins.AbstractPlugin;
+import org.elasticsearch.script.ScriptModule;
+
+public class ExplainableScriptPlugin extends AbstractPlugin {
+
+    public ExplainableScriptPlugin() {}
+    @Override
+    public String name() {
+        return "native-explainable-script";
+    }
+
+    @Override
+    public String description() {
+        return "Native explainable script";
+    }
+
+    public void onModule(ScriptModule module) {
+        module.registerScript("native_explainable_script", ExplainableScriptTests.MyNativeScriptFactory.class);
+    }
+}

src/test/java/org/elasticsearch/search/functionscore/ExplainableScriptTests.java

@@ -0,0 +1,112 @@
+/*
+ * Licensed to Elasticsearch 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.search.functionscore;
+
+import org.apache.lucene.search.Explanation;
+import org.elasticsearch.action.index.IndexRequestBuilder;
+import org.elasticsearch.action.search.SearchResponse;
+import org.elasticsearch.action.search.SearchType;
+import org.elasticsearch.common.Nullable;
+import org.elasticsearch.common.settings.Settings;
+import org.elasticsearch.index.fielddata.ScriptDocValues;
+import org.elasticsearch.script.AbstractDoubleSearchScript;
+import org.elasticsearch.script.ExecutableScript;
+import org.elasticsearch.script.ExplainableSearchScript;
+import org.elasticsearch.script.NativeScriptFactory;
+import org.elasticsearch.search.SearchHit;
+import org.elasticsearch.search.SearchHits;
+import org.elasticsearch.test.ElasticsearchIntegrationTest;
+import org.elasticsearch.test.hamcrest.ElasticsearchAssertions;
+import org.junit.Test;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ExecutionException;
+
+import static org.elasticsearch.client.Requests.searchRequest;
+import static org.elasticsearch.common.settings.ImmutableSettings.settingsBuilder;
+import static org.elasticsearch.common.xcontent.XContentFactory.jsonBuilder;
+import static org.elasticsearch.index.query.QueryBuilders.functionScoreQuery;
+import static org.elasticsearch.index.query.QueryBuilders.termQuery;
+import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.scriptFunction;
+import static org.elasticsearch.search.builder.SearchSourceBuilder.searchSource;
+import static org.elasticsearch.test.ElasticsearchIntegrationTest.ClusterScope;
+import static org.elasticsearch.test.ElasticsearchIntegrationTest.Scope;
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.equalTo;
+
+@ClusterScope(scope = Scope.SUITE, numDataNodes = 1)
+public class ExplainableScriptTests extends ElasticsearchIntegrationTest {
+
+    @Override
+    protected Settings nodeSettings(int nodeOrdinal) {
+        return settingsBuilder()
+                .put(super.nodeSettings(nodeOrdinal))
+                .put("plugin.types", ExplainableScriptPlugin.class.getName())
+                .build();
+    }
+
+    @Test
+    public void testNativeExplainScript() throws InterruptedException, IOException, ExecutionException {
+
+        List<IndexRequestBuilder> indexRequests = new ArrayList<>();
+        for (int i = 0; i < 20; i++) {
+            indexRequests.add(client().prepareIndex("test", "type").setId(Integer.toString(i)).setSource(
+                    jsonBuilder().startObject().field("number_field", i).field("text", "text").endObject()));
+        }
+        indexRandom(true, true, indexRequests);
+        client().admin().indices().prepareRefresh().execute().actionGet();
+        ensureYellow();
+        SearchResponse response = client().search(searchRequest().searchType(SearchType.QUERY_THEN_FETCH).source(
+                searchSource().explain(true).query(functionScoreQuery(termQuery("text", "text")).add(scriptFunction("native_explainable_script", "native")).boostMode("sum")))).actionGet();
+
+        ElasticsearchAssertions.assertNoFailures(response);
+        SearchHits hits = response.getHits();
+        assertThat(hits.getTotalHits(), equalTo(20l));
+        int idCounter = 19;
+        for (SearchHit hit : hits.getHits()) {
+            assertThat(hit.getId(), equalTo(Integer.toString(idCounter)));
+            assertThat(hit.explanation().toString(), containsString(Double.toString(idCounter) + " = This script returned " + Double.toString(idCounter)));
+            idCounter--;
+        }
+    }
+
+    static class MyNativeScriptFactory implements NativeScriptFactory {
+        @Override
+        public ExecutableScript newScript(@Nullable Map<String, Object> params) {
+            return new MyScript();
+        }
+    }
+
+    static class MyScript extends AbstractDoubleSearchScript implements ExplainableSearchScript {
+
+        @Override
+        public double runAsDouble() {
+            return ((Number) ((ScriptDocValues) doc().get("number_field")).getValues().get(0)).doubleValue();
+        }
+
+        @Override
+        public Explanation explain(float score) throws IOException {
+            return new Explanation((float) (runAsDouble()), "This script returned " + runAsDouble());
+        }
+    }
+}