[DOC] Explain parameter dependencies in https://opensearch.org/docs/latest/api-reference/explain/

[dblock]

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Tell us about your request. Provide a summary of the request.

The parameters in https://opensearch.org/docs/latest/api-reference/explain/ are incorrect.

2.18 fails when I specify analyzer, analyze_wildcard, default_operator, df, or stored_fields as described.

[INFO] => POST /movies/_explain/movie2 ({
  "analyzer": "english"
}) [application/json] {
  "query": {
    "match": {
      "title": "Drive"
    }
  }
}
[INFO] <= 400 (application/json) | {
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "request [/movies/_explain/movie2] contains unrecognized parameter: [analyzer]"
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "request [/movies/_explain/movie2] contains unrecognized parameter: [analyzer]"
  },
  "status": 400
}

[INFO] => POST /movies/_explain/movie2 ({
  "analyze_wildcard": true
}) [application/json] {
  "query": {
    "match": {
      "title": "Drive"
    }
  }
}
[INFO] <= 400 (application/json) | {
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "request [/movies/_explain/movie2] contains unrecognized parameter: [analyze_wildcard]"
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "request [/movies/_explain/movie2] contains unrecognized parameter: [analyze_wildcard]"
  },
  "status": 400
}

Version: List the OpenSearch version to which this issue applies, e.g. 2.14, 2.12--2.14, or all.

2.18

What other resources are available? Provide links to related issues, POCs, steps for testing, etc.

[russcam]

Those parameters can only be used in conjunction with the q query string parameter to specify the query:

https://github.com/opensearch-project/OpenSearch/blob/1e08b5a075fa6018be6c0af959b2d638c2743d56/server/src/main/java/org/opensearch/rest/action/search/RestExplainAction.java#L70-L102

and

https://github.com/opensearch-project/OpenSearch/blob/aca2e9de7daaadee77c33e21ff5215c3f1e8600f/server/src/main/java/org/opensearch/rest/action/RestActions.java#L229-L244

This is essentially a shorthand query parameter form for building a query_string query. You can build the query_string query directly in the body if you prefer

POST /movies/_explain/movie2
{
  "query": {
    "query_string": {
      "default_field": "*",
      "query": "Drive",
      "analyzer": "english"
    }
  }
}

(or use "title" for default_field)

[dblock]

Thanks @russcam! Let's clarify this in the docs.

[dblock]

I added working tests for the rest of that explain DSL parameters in opensearch-project/opensearch-api-specification#688, thanks @russcam.