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

# Include Query Explanations

> Client language: PHP. 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), [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.php.md#order-by-score).
>
> - Each document in the results includes this score under the `@index-score` property in its metadata.
>
> - Use `includeExplanations` 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).
>
> - 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

```php
$explanations = new Explanations();

/** @var array<Product> $syrups */
$syrups = $session->advanced()->documentQuery(Product::class)
  ->includeExplanations(null, $explanations)
  ->search("Name", "Syrup")
  ->toList();

$scoreDetails = $explanations->getExplanations($syrups[0]->getId());
```

### RQL

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

> **Note**
>
> Please note that the First parameter is optional.  
> If you intend to use the default options, just paste `null` instead of the options object.

## View explanations

- The detailed explanations can be viewed from the **Query view** in Studio.

- Running a query with `includeExplanations` 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

```php
public function includeExplanations(?ExplanationOptions $options, Explanations &$explanations): DocumentQueryInterface;
```

| Parameter | Type | Description |
| - | - | - |
| **$options** | `?ExplanationOptions` | This object is optional.<br />If you intend to use the default options, place `null` here. |
| **&$explanations** | `Explanations` | <ul><li>A callback function (action) that takes <code>Explanations</code> as an argument. It will be called by the client with the resulting <code>Explanations</code>.</li><li>You can interact with the resulting <code>Explanations</code> inside your callback.</li></ul> |
