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 include_explanations when querying with a document_query.

  • In this page:

Include explanations in a query

# Prepare a callback
explanations_results: Optional[Explanations] = None

def explanations_callback(explanations: Explanations):
    explanations_results = explanations

# Query with 'document_query'

# Execute the query
results = list(
    # Prepare a query
    # Call include_expirations, provide an out param for the explanations results
    # Define query criteria
    # i.e. search for docs containing Syrup -or- Lager in their Name field
    .search("Name", "Syrup Lager")

# Get the score details for a specific document from the results
# Get explanations from the resulting Explanations object
score_details = explanations_results.explanations[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 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


def include_explanations(
    options: Optional[ExplanationOptions] = None,
    explanations_callback: Callable[[Explanations], None] = None,
) -> DocumentQuery[_T]: ...
Parameters Data type Description
explanations_callback Callable[[Explanations], None]
  • A callback function (action) that takes Explanations as an argument. It will be called by the client with the resulting Explanations.
  • You can interact with resulting Explanations inside your callback.
options (Optional) ExplanationOptions Can be a group_key string
Dict[str, List[str]]
  • Pass the resulting document ID for which to get score details.
  • Returns a list with all explanations.