---
title: "Include Query Timings"
url: "https://docs.ravendb.net/6.2/client-api/session/querying/debugging/query-timings"
version: "6.2"
language: "python"
---

# Include Query Timings

> Client language: Python. Also available for [C#](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/query-timings.md), [Java](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/query-timings.java.md), [PHP](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/query-timings.php.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/querying/debugging/query-timings.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,  
>   you can request to get detailed stats of the time spent by RavenDB on each part of the query.  
>   E.g. duration of search, loading documents, transforming results, total duration, etc.
>
> - By default, the timings stats are Not included in the query results, to avoid the measuring overhead.
>
> - **To include the query timings** in the query results:  
>   add a call to the `timings()` method in your query code, or add `include timings()` to an RQL query.  
>   See examples below.
>
> - In this page:
>   - [Include timings in a query](#include-timings-in-a-query)
>   - [View timings](#view-timings)
>   - [Syntax](#syntax)
>   - [Timings in a sharded database](#timings-in-a-sharded-database)

## Include timings in a query

### Query

```python
timings: Optional[QueryTimings] = None

# Prepare a callback
def timings_callback(timings_from_server: QueryTimings):
  timings = timings_from_server

results = list(
  session.advanced.document_query(object_type=Product)
  # Call timings, provide a callback function that will be called with result timings
  .timings(timings_callback)
  # Define query criteria
  # i.e. search for docs containing Syrup -or- Lager in their Name field
  .search("Name", "Syrup Lager")
  # Execute the query
)

# Get total query duration:
# =========================
total_query_duration = timings.duration_in_ms

# Get specific parts duration:
# ============================
timings_dictionary = timings.timings
optimizer_duration = timings_dictionary["Optimizer"].duration_in_ms
lucene_duration = timings_dictionary["Query"].timings["lucene"].duration_in_ms
```

### RQL

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

## View timings

- The detailed timings can be viewed from the [Query view](https://docs.ravendb.net/6.2/studio/database/queries/query-view.md) in the Studio.

- Running an RQL query with `include timings()` will show an additional **Timings Tab**  
  with a graphical representation of the time spent in each query part.

![Figure 1. Include timings graphical results](https://docs.ravendb.net/assets/images/include-timings-15db05cff6a6735293893839af694192.png)

## Syntax

```python
def timings(self, timings_callback: Callable[[QueryTimings], None]) -> DocumentQuery[_T]: ...
```

| Parameter | Type | Description |
| - | - | - |
| **timings\_callback** | `Callable[[QueryTimings], None]` | A callback function (action) that takes `QueryTimings` as an argument. It will be called by the client with the resulting `QueryTimings`. You can interact with the resulting `QueryTimings` inside your callback. |

```python
class QueryTimings:
  def __init__(self, duration_in_ms: int = None, timings: Dict[str, QueryTimings] = None):
      self.duration_in_ms = duration_in_ms
      self.timings = timings or {}
```

| `QueryTimings` | | |
| - | - | - |
| **duration\_in\_ms** | `int` | Total duration |
| **timings** | `Dict[str, QueryTimings]` | Dictionary with `QueryTimings` info per time part |

## Timings in a sharded database

- In a sharded database, timings for each part are provided **per shard**.

- Learn more in [timings in a sharded database](https://docs.ravendb.net/6.2/sharding/querying.md#timing-queries).
