Include Query Explanations


  • When making a query, each document in the query results is assigned a score.
    This score determines the order by which the documents come back in the results when requesting
    to order by score.

  • Each document in the results includes this score under the @index-score property in its metadata.

  • To get the score details and see how it was calculated,
    you can use IncludeExplanations when querying with a DocumentQuery.

  • In this page:


Include explanations in a query

// Query with `DocumentQuery`
var results = session.Advanced.DocumentQuery<Product>()
    
     // Call IncludeExplanations, provide an out param for the explanations results
    .IncludeExplanations(out Explanations explanations)
     // Define query criteria
     // i.e. search for docs containing Syrup -or- Lager in their Name field
    .Search(x => x.Name, "Syrup Lager")
     // Execute the query
    .ToList();

// Get the score details for a specific document from the results
// Call GetExplanations on the resulting Explanations object
string[] scoreDetails = explanations.GetExplanations(results[0].Id);
// Query with `AsyncDocumentQuery`
var results = await asyncSession.Advanced.AsyncDocumentQuery<Product>()
    
     // Call IncludeExplanations, provide an out param for the explanations results
    .IncludeExplanations(out Explanations explanations)
     // Define query criteria
     // i.e. search for docs containing Syrup -or- Lager in their Name field
    .Search(x => x.Name, "Syrup Lager")
     // Execute the query
    .ToListAsync();

// Get the score details for a specific document from the results
// Call GetExplanations on the resulting Explanations object
string[] scoreDetails = explanations.GetExplanations(results[0].Id);
from "Products"
where search(Name, "Syrup") or search(Name, "Lager")
include explanations()

View explanations

  • The detailed explanations can be viewed from the Query view in the Studio.

  • Running a query with include explanations() will show an additional Explanations Tab.

Figure 1. Explanations in the Studio

Include explanations

  • Sample score details:
Figure 2. View explanations

View explanation

Syntax

IDocumentQuery<T> IncludeExplanations(out Explanations explanations);
Parameters Data type Description
explanations Explanations An out param that will be filled with the explanations results
Explanations
string[] GetExplanations(string docId)
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.