SearchTemplateDescriptor Explain method

[wyeager]

NEST/Elasticsearch.Net version:
7.9.0

Elasticsearch version:
7.9.2

Description of the problem including expected versus actual behavior:
SearchTemplateDescriptor Explain method places ?explain=true in URL when instead the endpoint seems to need "explain": true key value pair in request body

Steps to reproduce:

var searchResponse = await elasticClient
    .SearchTemplateAsync<MyObject>(searchTemplateDesc =>
        searchTemplateDesc
            .Index(myIndex)
            .Source(mySearchTemplate)
            .Params(myParams)
            .Explain());

Each element of searchResponse.Hits will have null for the value of its Explanation field.

Expected behavior
I would expect the Explanation field of each element of searchResponse.Hits to have a value when I call Explain() on the SearchTemplateDescriptor.

Additional Info:
I can send this raw request to:
http://localhost:9200/myIndex/_search/template

{
  "source" : {
      "query": { "match" : { "FirstName" : "{{FirstName}}" } }
  },
  "explain": true,
  "params" : {
    "FirstName": "John"
  }
}

and _explanation has a value.

However, setting ?explain=true in the URL and omitting "explain": true from the request body, like this:
http://localhost:9200/myIndex/_search/template?explain=true

{
  "source" : {
      "query": { "match" : { "FirstName" : "{{FirstName}}" } }
  },
  "params" : {
    "FirstName": "John"
  }
}

does not return an explanation.

I'm pretty sure the cause of the bug is that the SearchTemplateDescriptor Explain method is structuring the request the second way when it should be structuring it the first way.

[russcam]

Thanks for raising @wyeager! As you correctly conclude, the search template request adds the explain parameter to the query string

elasticsearch-net/src/Nest/Requests.NoNamespace.cs

Lines 3031 to 3036 in 13aed8a

	///<summary>Specify whether to return detailed information about score computation as part of a hit</summary>
	public bool? Explain
	{
	get => Q<bool? >("explain");
	set => Q("explain", value);
	}

This is because the REST API spec for search template defines it as a query string param (and the REST API specs do not have details about the request body):

elasticsearch-net/src/ApiGenerator/RestSpecification/Core/search_template.json

Lines 79 to 82 in 13aed8a

	"explain":{
	"type":"boolean",
	"description":"Specify whether to return detailed information about score computation as part of a hit"
	},

To fix this, the API generator for search template needs to be updated to

1. skip the "explain" query string parameter when generate the partial class for ISearchTemplateRequest et. al. Here's an example that skips parameters for ISearchRequest

   https://github.com/elastic/elasticsearch-net/blob/13aed8a519565a1b3f49ee944e78372fd953924e/src/ApiGenerator/Configuration/Overrides/Endpoints/SearchOverrides.cs

   then the API generator project needs to be re-run to regenerate types.

2. In the non-generated partial class of ISearchTemplateRequest, add the Explain property i.e.

   [DataMember(Name = "explain")]
   public bool? Explain { get; set; }

   and also add it to the concrete implementations, SearchTemplateRequest and SearchTemplateDescriptor<TDocument> (the latter implements the interface explicitly, with a method to set the value - see the other properties for examples).

Is this something that you'd like to tackle?

[stevejgordon]

Resolved in #6098. Will be released in 7.17.0.