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.

• This article provides examples of including explanations when making a dynamic-query.
  For including explanations when querying a static-index see Include explanations in index query.

• In this page:

  • Include explanations in a query
  • View explanations
  • Syntax

Include explanations in a query

• Query
• Query_async
• DocumentQuery
• DocumentQuery_async
• RQL

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.

• Sample score details:

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)	<ul><li>Pass the resulting document ID for which to get score details.</li><li>Returns a list with all explanations.</li></ul>