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.

    • Use include_explanations to get the score details** and see how it was calculated.

    • 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
    session.advanced.document_query(object_type=Product)
    # Call include_expirations, provide an out param for the explanations results
    .include_explanations()
    # 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

    Syntax 

    def include_explanations(
    self,
    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
    Explanations
    Dict[str, List[str]]
    • 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