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

# Include Query Explanations

> Client language: C#. Also available for [Java](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/include-explanations.java.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), [Node.js](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/include-explanations.nodejs.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.md#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](https://docs.ravendb.net/6.2/client-api/session/querying/document-query/what-is-document-query.md) interface.
>
>   > **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.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

```csharp
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);
```

### Query\_async

```csharp
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);
```

### DocumentQuery

```csharp
// 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);
```

### DocumentQuery\_async

```csharp
// 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);
```

### 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

```csharp
IDocumentQuery<T> IncludeExplanations(out Explanations explanations);
```

| Parameter | Type | Description |
| - | - | - |
| **explanations** | `Explanations` | An *out* param that will be filled with the explanations results |

| `Explanations` | Description |
| - | - |
| `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> |
