---
title: "Include Query Explanations"
url: "https://docs.ravendb.net/6.2/client-api/session/querying/debugging/include-explanations"
version: "6.2"
language: "nodejs"
---

# Include Query Explanations

> Client language: Node.js. Also available for [Java](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/include-explanations.java.md), [C#](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/include-explanations.md), [Python](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/include-explanations.python.md), [PHP](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/include-explanations.php.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - 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](https://docs.ravendb.net/6.2/client-api/session/querying/sort-query-results.nodejs.md#order-by-score).
>
> - Each document in the results includes this score under the `@index-score` property in its metadata.
>
> - Use `includeExplanations` in your query **to get the score details** and see how it was calculated.
>
>   > **Info**
>   >
>   > - 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](https://docs.ravendb.net/6.2/indexes/search-engine/corax.md#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](https://docs.ravendb.net/6.2/indexes/querying/include-explanations.nodejs.md).
>
> - In this page:
>   - [Include explanations in a query](#include-explanations-in-a-query)
>   - [View explanations](#view-explanations)
>   - [Syntax](#syntax)

## Include explanations in a query

### Query

```javascript
// Define an object that will receive the explanations results
let explanationsResults;

const products = await session.query({ collection: "Products" })
   // Call includeExplanations, pass a callback function
   // Output param 'explanationsResults' will be filled with explanations results when query returns 
  .includeExplanations(e => explanationsResults = e)
   // Define query criteria
   // i.e. search for docs containing Syrup -or- Lager in their Name field
  .search("Name", "Syrup Lager")
   // Execute the query
  .all();

// Get the score details for a specific document from 'explanationsResults'
const id = session.advanced.getDocumentId(products[0]);
const scoreDetails = explanationsResults.explanations[id];
```

### RQL

```sql
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](https://docs.ravendb.net/assets/images/include-explanations-1-9517add714b0b4645b93406852a01992.png)

- Sample score details:

![Figure 2. View explanations](https://docs.ravendb.net/assets/images/include-explanations-2-bc9760306eae71080b4fd24701a0fd46.png)

## Syntax

```javascript
query.includeExplanations(explanationsCallback)
```

| Parameter | Type | Description |
| - | - | - |
| **explanationsCallback** | `(explanationsResults) => void` | <ul><li>A callback function with an output parameter.</li><li>The parameter passed to the callback will be filled with the <code>Explanations</code> object when the query returns.</li></ul> |

```javascript
// The Explanations object:
// ========================

class Explanations {
  get explanations(): {
      [key: string]: string[]; // An explanations list per document ID key
  };
}
```
