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

# Include Query Explanations

> Client language: Java. Also available for [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), [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."

`includeExplanations` allows to investigate details related to score assigned for each query result.

> **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).

## Syntax

```java
IDocumentQuery<T> includeExplanations(Reference<Explanations> explanations);
```

## Example

### Query

```java
Reference<Explanations> explanationRef = new Reference<>();
List<Product> syrups = session.advanced().documentQuery(Product.class)
  .includeExplanations(explanationRef)
  .search("Name", "Syrup")
  .toList();

String[] scoreDetails = explanationRef.value.getExplanations(syrups.get(0).getId());
```

### RQL

```sql
from "Products" 
where search(Name, "Syrup")
include explanations()
```

---

Sample explanation:

```
4.650658 = (MATCH) fieldWeight(search(Name):syrup in 2), product of:
  1 = tf(termFreq(search(Name):syrup)=1)
  4.650658 = idf(docFreq=1, maxDocs=77)
  1 = fieldNorm(field=search(Name), doc=2)
```
