Explain

    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 () is calculated for every result.

    OpenSearch uses a probabilistic ranking framework called Okapi BM25 to calculate relevance scores. Okapi BM25 is based on the original 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.

    copy

    More often, you want the output for a single document. In that case, specify the document ID in the URL:

    copy

    FieldDescription
    matchedIndicates if the document is a match for the query.
    explanationThe 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, , 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.