---
title: "Querying Time Series: Overview & Syntax"
url: "https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/overview-and-syntax"
version: "6.2"
language: "python"
---

# Querying Time Series: Overview & Syntax

> Client language: Python. Also available for [C#](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/overview-and-syntax.md), [PHP](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/overview-and-syntax.php.md), [Node.js](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/overview-and-syntax.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**
>
> - Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries.
>
> - Querying time series data is native to RavenDB's queries.  
>   Clients can express time series queries in high-level LINQ expressions or directly in [RQL](https://docs.ravendb.net/6.2/client-api/session/querying/what-is-rql.md).
>
> - Queries can be executed as dynamic queries or over [time series indexes](https://docs.ravendb.net/6.2/document-extensions/timeseries/indexing.python.md).
>
> - In this page:
>   - [Time series query capabilities](#time-series-query-capabilities)
>   - [Server and client queries](#server-and-client-queries)
>   - [Dynamic and index queries](#dynamic-and-index-queries)
>   - [Scaling query results](#scaling-query-results)
>   - [RQL syntax](#rql-syntax)
>     - [`select timeseries` syntax](#section)
>     - [`declare timeseries` syntax](#section-1)
>   - [Combine time series and custom functions](#combine-time-series-and-custom-functions)
>   - [Use Studio To experiment](#use-studio-to-experiment)

## Time series query capabilities

Time series query can -

- [Choose a range of time series entries](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/choosing-query-range.python.md) to query from.
- [Filter](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/filtering.python.md) time series entries by their tags, values and timestamps.
- [Aggregate](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/aggregation-and-projections.md)  time series entries into groups by a chosen time resolution,  
  e.g. gather the prices of a stock that's been collected over the past two months to week-long groups.  
  Entries can also be aggregated by their tags.
- Select entries by various criteria, e.g. by the min and max values of each aggregated group,  
  and [project](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/aggregation-and-projections.md) them to the client.
- Calculate [statistical measures](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/statistics.md): the percentile, slope, or standard deviation of a time series.

## Server and client queries

Time series queries are executed by the server and their results are projected to the client,  
so they require very little client computation resources.

- The server runs time series queries using RQL.
- Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**.  
  High level queries are translated to RQL by the client before sending them to the server for execution.

## Dynamic and index queries

- **Dynamic queries**:
  - Time series indexes are Not created automatically by the server when making a dynamic query.
  - Use dynamic queries when time series you query are not indexed,  
    or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.python.md#queries-always-provide-results-using-an-index).
    E.g. -

```javascript
// Query for time series named "HeartRates" in employees hired after 1994
from Employees as e
where HiredAt > "1994-01-01"
select timeseries(
  from HeartRates
)
```

- **Index queries**:
  - Static time series indexes can be created by clients (or using Studio).  
    To learn how to create such indexes, see [indexing time series](https://docs.ravendb.net/6.2/document-extensions/timeseries/indexing.python.md).
  - Examples of querying a static time series index can be found in [querying time series indexes](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/using-indexes.python.md).

## Scaling query results

- Time series query results can be **scaled**, multiplied by some number.
  This doesn't change the values themselves, only the output of the query.
  Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format.

- There are several use cases for scaling.
  For example, suppose your time series records the changing speeds of different vehicles as they travel through a city,
  with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion.

- Another use case involves the compression of time series data.
  Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision.
  Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data.  
  Then, when querying the data, you can scale by `0.000001` to restore the original value.

- Scaling is a part of both RQL and LINQ syntax:

  - In **LINQ**, use `.Scale(<double>)`.
  - In **RQL**, use `scale <double>` in a time series query, and input your scaling factor as a double.

#### Example:

##### LINQ

```python
var query = session.Query<User>()
  .Select(p => RavenQuery.TimeSeries(p, "HeartRates")
      .Scale(10)
      .ToList())
  .ToList();

// The value in the query results is 10 times the value stored on the server
var scaledValue = query[0].Results[0].Values[0];
```

##### RQL

```sql
from Users
select timeseries(
  from HeartRates
  scale 10
)
```

## RQL syntax

A typical time series query can start by locating the documents whose time series we want to query.  
For example, we can query for employees above 30:

```javascript
from Employees as e
where Birthday < '1994-01-01'
```

Then, you can query their time series entries using either of the following two equivalent syntaxes:

- [`select timeseries` syntax](#section)
- [`declare timeseries` syntax](#section-1)

### `select timeseries`

This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section.

```javascript
// Query for entries from time series "HeartRates" for employees above 30
// ======================================================================

// This clause locates the documents whose time series we want to query:
from Employees as e 
where Birthday < '1994-01-01'

// Query the time series that belong to the matching documents:
select timeseries (   // The `select` clause defines the time series query.  
  from HeartRates   // The `from` keyword is used to specify the time series name to query.  
)
```

### `declare timeseries`

This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query.  
It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function.

Here is a query written in both syntaxes.  
It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries.

#### With Time Series Function

```sql
// declare the time series function:
declare timeseries ts(jogger) {
    from jogger.HeartRates 
    between 
       "2020-05-27T00:00:00.0000000Z"
      and 
       "2020-06-23T00:00:00.0000000Z"
}

from Users as jogger
where Age > 30
// call the time series function
select ts(jogger)
```

#### Without Time Series Function

```sql
from Users as jogger
where Age > 30
select timeseries(
    from HeartRates 
    between 
       "2020-05-27T00:00:00.0000000Z"
      and 
       "2020-06-23T00:00:00.0000000Z")
```

## Combine time series and custom functions

- You can declare and use both time series functions and custom functions in a query.  
  The custom functions can call the time series functions, pass them arguments, and use their results.

- In the example below, a custom function (`customFunc`) is called by the query `select` clause
  to fetch and format a set of time series entries, which are then projected by the query.  
  The time series function (`tsQuery`) is called to retrieve the matching time series entries.

- The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values.

- Note the generated RQL, where the custom function is translated to a [custom JavaScript function](https://docs.ravendb.net/6.2/client-api/session/querying/what-is-rql.md#declare).

```javascript
// The time series function:
// =========================
declare timeseries tsQuery(user) {
  from user.HeartRates
  where (Values[0] > 100)
}

// The custom JavaScript function:
// ===============================
declare function customFunc(user) {
  var results = [];

  // Call the time series function to retrieve heart rate values for the user
  var r = tsQuery(user);

  // Prepare the results
  for(var i = 0 ; i < r.Results.length; i ++) {
      results.push({
          Timestamp: r.Results[i].Timestamp, 
          Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)),
          Tag: r.Results[i].Tag  ?? "none"})
  }
  return results;
}

// Query & project results:
// ========================
from "Users" as user
select
  user.Name,
  customFunc(user) as timeSeriesEntries // Call the custom JavaScript function
```

This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample:

```python
class ModifiedTimeSeriesEntry:
  def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None):
      self.timestamp = timestamp
      self.value = value
      self.tag = tag
```

## Use Studio to experiment

You can use [Studio](https://docs.ravendb.net/6.2/studio/database/document-extensions/time-series.md) to try the RQL samples provided in this article and test your own queries.

!["Time Series Query in Studio"](https://docs.ravendb.net/assets/images/time-series-query-57994e479d4285ac5371046a9ca6b647.png)

## See also

- [Time Series Overview](https://docs.ravendb.net/6.2/document-extensions/timeseries/overview.md)
- [Studio Time Series Management](https://docs.ravendb.net/6.2/studio/database/document-extensions/time-series.md)
- [Time Series Indexing](https://docs.ravendb.net/6.2/document-extensions/timeseries/indexing.python.md)
- [Range Selection](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/choosing-query-range.python.md)
- [Filtering](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/filtering.python.md)
- [Aggregation and Projection](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/aggregation-and-projections.md)
- [Indexed Time Series Queries](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/using-indexes.python.md)
- [Statistical Measures](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/statistics.md)
- [Time Series Rollup and Retention](https://docs.ravendb.net/6.2/document-extensions/timeseries/rollup-and-retention.python.md)
