diff --git a/_opensearch/rest-api/explain.md b/_opensearch/rest-api/explain.md deleted file mode 100644 index 1d56dbd7..00000000 --- a/_opensearch/rest-api/explain.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -layout: default -title: Explain -parent: REST API reference -nav_order: 140 ---- - -# Explain -Introduced 1.0 -{: .label .label-purple } - -Wondering why a specific document ranks higher (or lower) for a query? You can use the explain API for an explanation of how the relevance score (`_score`) is calculated for every result. - -OpenSearch uses a probabilistic ranking framework called [Okapi BM25](https://en.wikipedia.org/wiki/Okapi_BM25) to calculate relevance scores. Okapi BM25 is based on the original [TF/IDF](http://lucene.apache.org/core/4_0_0/core/org/apache/lucene/search/package-summary.html#scoring) framework used by Apache Lucene. - -The explain API is an expensive operation in terms of both resources and time. On production clusters, we recommend using it sparingly for the purpose of troubleshooting. -{: .warning } - - -## Example - -To see the explain output for all results, set the `explain` flag to `true` either in the URL or in the body of the request: - -```json -POST kibana_sample_data_ecommerce/_search?explain=true -{ - "query": { - "match": { - "customer_first_name": "Mary" - } - } -} -``` - -More often, you want the output for a single document. In that case, specify the document ID in the URL: - -```json -POST kibana_sample_data_ecommerce/_explain/EVz1Q3sBgg5eWQP6RSte -{ - "query": { - "match": { - "customer_first_name": "Mary" - } - } -} -``` - -## Path and HTTP methods - -``` -GET /_explain/ -POST /_explain/ -``` - -## URL parameters - -You must specify the index and document ID. All other URL parameters are optional. - -Parameter | Type | Description | Required -:--- | :--- | :--- | :--- -`` | String | Name of the index. You can only specify a single index. | Yes -`<_id>` | String | A unique identifier to attach to the document. | Yes -`analyzer` | String | The analyzer to use in the query string. | No -`analyze_wildcard` | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is false. | No -`default_operator` | String | Indicates whether the default operator for a string query should be AND or OR. Default is OR. | No -`df` | String | The default field in case a field prefix is not provided in the query string. | No -`lenient` | Boolean | Specifies whether OpenSearch should ignore format-based query failures (for example, querying a text field for an integer). Default is false. | No -`preference` | String | Specifies a preference of which shard to retrieve results from. Available options are `_local`, which tells the operation to retrieve results from a locally allocated shard replica, and a custom string value assigned to a specific shard replica. By default, OpenSearch executes the explain operation on random shards. | No -`q` | String | Query in the Lucene query string syntax. | No -`stored_fields` | Boolean | If true, the operation retrieves document fields stored in the index rather than the document’s `_source`. Default is false. | No -`routing` | String | Value used to route the operation to a specific shard. | No -`_source` | String | Whether to include the `_source` field in the response body. Default is true. | No -`_source_excludes` | String | A comma-separated list of source fields to exclude in the query response. | No -`_source_includes` | String | A comma-separated list of source fields to include in the query response. | No - -## Response - -```json -{ - "_index" : "kibana_sample_data_ecommerce", - "_type" : "_doc", - "_id" : "EVz1Q3sBgg5eWQP6RSte", - "matched" : true, - "explanation" : { - "value" : 3.5671005, - "description" : "weight(customer_first_name:mary in 1) [PerFieldSimilarity], result of:", - "details" : [ - { - "value" : 3.5671005, - "description" : "score(freq=1.0), computed as boost * idf * tf from:", - "details" : [ - { - "value" : 2.2, - "description" : "boost", - "details" : [ ] - }, - { - "value" : 3.4100041, - "description" : "idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:", - "details" : [ - { - "value" : 154, - "description" : "n, number of documents containing term", - "details" : [ ] - }, - { - "value" : 4675, - "description" : "N, total number of documents with field", - "details" : [ ] - } - ] - }, - { - "value" : 0.47548598, - "description" : "tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:", - "details" : [ - { - "value" : 1.0, - "description" : "freq, occurrences of term within document", - "details" : [ ] - }, - { - "value" : 1.2, - "description" : "k1, term saturation parameter", - "details" : [ ] - }, - { - "value" : 0.75, - "description" : "b, length normalization parameter", - "details" : [ ] - }, - { - "value" : 1.0, - "description" : "dl, length of field", - "details" : [ ] - }, - { - "value" : 1.1206417, - "description" : "avgdl, average length of field", - "details" : [ ] - } - ] - } - ] - } - ] - } -} -``` - -## Response body fields - -Field | Description -:--- | :--- -`matched` | Indicates if the document is a match for the query. -`explanation` | The `explanation` object has three properties: `value`, `description`, and `details`. The `value` shows the result of the calculation, the `description` explains what type of calculation is performed, and the `details` shows any subcalculations performed. -Term frequency (`tf`) | How many times the term appears in a field for a given document. The more times the term occurs the higher is the relevance score. -Inverse document frequency (`idf`) | How often the term appears within the index (across all the documents). The more often the term appears the lower is the relevance score. -Field normalization factor (`fieldNorm`) | The length of the field. OpenSearch assigns a higher relevance score to a term appearing in a relatively short field. - -The `tf`, `idf`, and `fieldNorm` values are calculated and stored at index time when a document is added or updated. The values might have some (typically small) inaccuracies as it’s based on summing the samples returned from each shard. - -Individual queries include other factors for calculating the relevance score, such as term proximity, fuzziness, and so on.