---
title: "Querying Time Series Indexes"
url: "https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/using-indexes"
version: "6.2"
language: "python"
---

# Querying Time Series Indexes

> Client language: Python. Also available for [C#](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/using-indexes.md), [PHP](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/using-indexes.php.md), [Node.js](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/using-indexes.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**
>
> - **Time series index**:
>
>   - STATIC-time-series-indexes can be defined from the [Client API](https://docs.ravendb.net/6.2/document-extensions/timeseries/indexing.python.md)
>     or using [Studio](https://docs.ravendb.net/6.2/studio/database/indexes/create-map-index.md).  
>     Such an index can be queried in the same way as a regular index that indexes documents.  
>     (See [Querying an index](https://docs.ravendb.net/6.2/indexes/querying/query-index.python.md)).
>
>   - AUTO-time-series-indexes are Not generated automatically by the server when making a time series query.
>
> - **The contents of the query results**:
>
>   - Unlike a document index, where the source data are your JSON documents,  
>     the source data for a time series index are the time series entries within the documents.
>
>   - When querying a **document index**:  
>     the resulting objects are the document entities (unless results are projected).
>
>   - When querying a **time series index**:  
>     each item in the results is of the type defined by the **index-entry** in the index definition,  
>     (unless results are projected).
>     The documents themselves are not returned.
>
> - In this page:
>   - [Sample index](#sample-index)
>   - [Querying the index](#querying-the-index)
>     - [Query all time series entries](#query-all-time-series-entries)
>     - [Filter query results](#filter-query-results)
>     - [Order query results](#order-query-results)
>     - [Project results](#project-results)
>   - [Syntax](#syntax)

## Sample Index

- The following is a time series map-index that will be used in the query examples throughout this article.

- Each **index-entry** consists of:
  - Three index-fields obtained from the "HeartRates" time series entries: `BPM`, `Date`, and `Tag`.
  - One index-field obtained from the time series [segment](https://docs.ravendb.net/6.2/document-extensions/timeseries/indexing.python.md#timeseriessegment-object) header: `EmployeeID`.
  - One index-field obtained from the loaded employee document: `EmployeeName`.

- When querying this time series index:
  - The resulting items correspond to the time series entries that match the query predicate.
  - Each item in the results will be of type `TsIndex.IndexEntry`, which is the index-entry.  
    Different result types may be returned when the query [projects the results](#project-results).

```python
class TsIndex(AbstractTimeSeriesIndexCreationTask):
  # The index-entry:
  # ===============
  class IndexEntry:
      def __init__(
          self,
          bpm: float = None,
          date: datetime = None,
          tag: str = None,
          employee_id: str = None,
          employee_name: str = None,
      ):
          # The index-fields:
          # =================
          self.bpm = bpm
          self.date = date
          self.tag = tag
          self.employee_id = employee_id
          self.employee_name = employee_name

  def __init__(self):
      super().__init__()
      self.map = """
      from ts in timeSeries.Employees.HeartRates
      from entry in ts.Entries
      let employee = LoadDocument(ts.DocumentId, "Employees")
      select new 
      {
          bpm = entry.Values[0],
          date = entry.Timestamp.Date,
          tag = entry.Tag,
          employee_id = ts.DocumentId,
          employee_name = employee.FirstName + ' ' + employee.LastName
      }
      """
```

## Querying the index

#### Query all time series entries:

No filtering is applied in this query.  
Results will include ALL entries from time series "HeartRates".

##### Query

```python
with store.open_session() as session:
  results = list(session.query_index_type(self.TsIndex, self.TsIndex.IndexEntry))

  # Access results:
  entry_result = results[0]
  employee_name = entry_result.employee_name
  bmp = entry_result.bpm
```

##### RawQuery

```python
with store.open_session() as session:
  results = list(session.advanced.raw_query("from index 'TsIndex'", self.TsIndex.IndexEntry))
```

##### RQL

```sql
from index "TsIndex"
```

#### Filter query results:

In this example, time series entries are filtered by the query.  
The query predicate is applied to the index-fields.

##### Query

```python
with store.open_session() as session:
  results = list(
      session.query_index_type(self.TsIndex, self.TsIndex.IndexEntry)
      .where_equals("employee_name", "Robert King")
      .and_also()
      .where_greater_than("bpm", 85)
  )
```

##### RawQuery

```python
with store.open_session() as session:
  results = list(
      session.advanced.raw_query(
          "from index 'TsIndex' where employee_name == 'Robert King' and bpm > 85.0",
          self.TsIndex.IndexEntry,
      )
  )
```

##### RQL

```sql
from index "TsIndex"
where EmployeeName == "Robert King" and BPM > 85.0
```

#### Order query results:

Results can be ordered by any of the index-fields.

##### Query

```python
with store.open_session() as session:
  results = list(
      session.query_index_type(self.TsIndex, self.TsIndex.IndexEntry)
      .where_less_than("bpm", 58)
      .order_by_descending("date")
  )
```

##### RawQuery

```python
with store.open_session() as session:
  results = list(
      session.advanced.raw_query(
          "from index 'TsIndex' where bpm < 58.0 order by date desc",
          self.TsIndex.IndexEntry,
      )
  )
```

##### RQL

```sql
from index "TsIndex"
where BPM < 58.0
order by Date desc
```

#### Project results:

- Instead of returning the entire `TsIndex.IndexEntry` object for each result item,  
  you can return only partial fields.

- In this example, we query for time series entries with a very high BPM value.  
  We retrieve entries with BPM value > 100 but return only the *EmployeeID* for each entry.

##### Query

```python
with store.open_session() as session:
  results = list(
      session.query_index_type(self.TsIndex, self.TsIndex.IndexEntry)
      .where_greater_than("bpm", 100)
      .select_fields(self.EmployeeDetails, "employee_id")
      .distinct()
  )
```

##### Projection\_class

```python
# This class is used when projecting index-fields via DocumentQuery
class EmployeeDetails:
  def __init__(self, employee_name: str = None, employee_id: str = None):
      self.employee_name = employee_name
      self.employee_id = employee_id
```

##### RawQuery

```python
with store.open_session() as session:
  results = list(
      session.advanced.raw_query(
          "from index 'TsIndex' where bpm > 100.0 select distinct employee_id",
          self.TsIndex.IndexEntry,
      )
  )
```

##### RQL

```sql
from index "TsIndex"
where BPM > 100.0
select distinct EmployeeID
```

## Syntax

- [query](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.python.md#query-overview)

```json
def query(
self, source: Optional[Query] = None, object_type: Optional[Type[_T]] = None
) -> DocumentQuery[_T]:
...
```

- [document\_query](https://docs.ravendb.net/6.2/client-api/session/querying/document-query/query-vs-document-query.python.md)

```json
def document_query(
self,
index_name: str = None,
collection_name: str = None,
object_type: Type[_T] = None,
is_map_reduce: bool = False,
) -> DocumentQuery[_T]:
...
```

## 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)
- [Time Series Rollup and Retention](https://docs.ravendb.net/6.2/document-extensions/timeseries/rollup-and-retention.python.md)
