See on GitHub

    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,
      use method IncludeExplanations, which is available in the IDocumentQuery interface.

      • Including explanations is available only when using Lucene as the underlying search engine.
      • You can configure which search engine will be used. Learn how in Selecting the search engine.

    Include explanations in a query 

    var products = session
    .Query<Product>()
     // Convert the IRavenQueryable to IDocumentQuery
     // to be able to use 'IncludeExplanations'
    .ToDocumentQuery()
     // Call IncludeExplanations, provide an out param for the explanations results
    .IncludeExplanations(out Explanations explanations)
     // Convert back to IRavenQueryable
     // to continue building the query using LINQ
    .ToQueryable()
     // Define query criteria
     // e.g. 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(products[0].Id);
    var products = await asyncSession
    .Query<Product>()
     // Convert the IRavenQueryable to IDocumentQuery
     // to be able to use 'IncludeExplanations'
    .ToAsyncDocumentQuery()
     // Call IncludeExplanations, provide an out param for the explanations results
    .IncludeExplanations(out Explanations explanations)
     // Convert back to IRavenQueryable
     // to continue building the query using LINQ
    .ToQueryable()
     // Define query criteria
     // e.g. 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(products[0].Id);
    // Query with `DocumentQuery`
var products = session.Advanced
    .DocumentQuery<Product>()
     // Call IncludeExplanations, provide an out param for the explanations results
    .IncludeExplanations(out Explanations explanations)
     // Define query criteria
     // e.g. 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(products[0].Id);
    // Query with `AsyncDocumentQuery`
var products = await asyncSession.Advanced
    .AsyncDocumentQuery<Product>()
     // Call IncludeExplanations, provide an out param for the explanations results
    .IncludeExplanations(out Explanations explanations)
     // Define query criteria
     // e.g. 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(products[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 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);
    Parameter 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.

    Home / Docs / Client Api / Session / Querying / Debugging / Include Explanations