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

# Querying Time Series Indexes

> Client language: C#. Also available for [Python](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/using-indexes.python.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.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.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](https://docs.ravendb.net/6.2/indexes/querying/projections.md)).
>
>   - 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](#project-results)).
>     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.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).

```csharp
public class TsIndex : AbstractTimeSeriesIndexCreationTask<Employee>
{
  // The index-entry:
  // ================
  public class IndexEntry
  {
      // The index-fields:
      // =================
      public double BPM { get; set; }
      public DateTime Date { get; set; }
      public string Tag { get; set; }
      public string EmployeeID { get; set; }
      public string EmployeeName { get; set; }
  }

  public TsIndex()
  {
      AddMap("HeartRates", timeSeries => 
          from segment in timeSeries
          from entry in segment.Entries
          
          let employee = LoadDocument<Employee>(segment.DocumentId)
          
          // Define the content of the index-fields:
          // =======================================
          select new IndexEntry()
          {
              BPM = entry.Values[0],
              Date = entry.Timestamp,
              Tag = entry.Tag,
              EmployeeID = segment.DocumentId,
              EmployeeName = 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

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session
       // Query the index
      .Query<TsIndex.IndexEntry, TsIndex>()
       // Query for all entries w/o any filtering
      .ToList();
  
  // Access results:
  TsIndex.IndexEntry entryResult = results[0];
  string employeeName = entryResult.EmployeeName;
  double BPM = entryResult.BPM;
}
```

##### Query\_async

```csharp
using (var asyncSession = store.OpenAsyncSession())
{
  List<TsIndex.IndexEntry> results = await asyncSession
       // Query the index
      .Query<TsIndex.IndexEntry, TsIndex>()
       // Query for all entries w/o any filtering
      .ToListAsync();
}
```

##### DocumentQuery

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session.Advanced
       // Query the index
      .DocumentQuery<TsIndex.IndexEntry, TsIndex>()
       // Query for all entries w/o any filtering
      .ToList();
}
```

##### RawQuery

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session.Advanced
       // Query the index for all entries w/o any filtering
      .RawQuery<TsIndex.IndexEntry>($@"
            from index 'TsIndex'
       ")
      .ToList();
}
```

##### 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

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session
      .Query<TsIndex.IndexEntry, TsIndex>()
       // Retrieve only time series entries with high BPM values for a specific employee
      .Where(x => x.EmployeeName == "Robert King" && x.BPM > 85)
      .ToList();
}
```

##### Query\_async

```csharp
using (var asyncSession = store.OpenAsyncSession())
{
  List<TsIndex.IndexEntry> results = await asyncSession
      .Query<TsIndex.IndexEntry, TsIndex>()
       // Retrieve only time series entries with high BPM values for a specific employee
      .Where(x => x.EmployeeName == "Robert King" && x.BPM > 85)
      .ToListAsync();
}
```

##### DocumentQuery

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session.Advanced
      .DocumentQuery<TsIndex.IndexEntry, TsIndex>()
       // Retrieve only time series entries with high BPM values for a specific employee
      .WhereEquals(x => x.EmployeeName, "Robert King")
      .AndAlso()
      .WhereGreaterThan(x => x.BPM, 85)
      .ToList();
}
```

##### RawQuery

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session.Advanced
       // Retrieve only time series entries with high BPM values for a specific employee
      .RawQuery<TsIndex.IndexEntry>($@"
            from index 'TsIndex'
            where EmployeeName == 'Robert King' and BPM > 85.0 
       ")
      .ToList();
}
```

##### 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

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session
      .Query<TsIndex.IndexEntry, TsIndex>()
       // Retrieve time series entries where employees had a low BPM value
      .Where(x => x.BPM < 58)
       // Order by the 'Date' index-field (descending order)
      .OrderByDescending(x => x.Date)
      .ToList();
}
```

##### Query\_async

```csharp
using (var asyncSession = store.OpenAsyncSession())
{
  List<TsIndex.IndexEntry> results = await asyncSession
      .Query<TsIndex.IndexEntry, TsIndex>()
       // Retrieve time series entries where employees had a low BPM value
      .Where(x => x.BPM < 58)
       // Order by the 'Date' index-field (descending order)
      .OrderByDescending(x => x.Date)
      .ToListAsync();
}
```

##### DocumentQuery

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session.Advanced
      .DocumentQuery<TsIndex.IndexEntry, TsIndex>()
       // Retrieve time series entries where employees had a low BPM value
      .WhereLessThan(x => x.BPM, 58)
       // Order by the 'Date' index-field (descending order)
      .OrderByDescending(x => x.Date)
      .ToList();
}
```

##### RawQuery

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session.Advanced
       // Retrieve entries with low BPM value and order by 'Date' descending
      .RawQuery<TsIndex.IndexEntry>($@"
            from index 'TsIndex'
            where BPM < 58.0
            order by Date desc
       ")
      .ToList();
}
```

##### 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.

- Learn more about projecting query results in [Project Index Query Results](https://docs.ravendb.net/6.2/indexes/querying/projections.md).

- 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

```csharp
using (var session = store.OpenSession())
{
  List<string> results = session
      .Query<TsIndex.IndexEntry, TsIndex>()
      .Where(x => x.BPM > 100)
       // Return only the EmployeeID index-field in the results
      .Select(x => x.EmployeeID)
       // Optionally: call 'Distinct' to remove duplicates from results
      .Distinct()
      .ToList();
}
```

##### Query\_async

```csharp
using (var asyncSession = store.OpenAsyncSession())
{
  List<string> results = await asyncSession
      .Query<TsIndex.IndexEntry, TsIndex>()
      .Where(x => x.BPM > 100)
       // Return only the EmployeeID index-field in the results
      .Select(x => x.EmployeeID)
       // Optionally: call 'Distinct' to remove duplicates from results
      .Distinct()
      .ToListAsync();
}
```

##### DocumentQuery

```csharp
var fieldsToProject = new string[] {
  "EmployeeID"
};

using (var session = store.OpenSession())
{
  List<EmployeeDetails> results = session.Advanced
      .DocumentQuery<TsIndex.IndexEntry, TsIndex>()
      .WhereGreaterThan(x => x.BPM, 100)
       // Return only the EmployeeID index-field in the results
      .SelectFields<EmployeeDetails>(fieldsToProject)
       // Optionally: call 'Distinct' to remove duplicates from results
      .Distinct()
      .ToList();
}
```

##### Projection\_class

```csharp
// This class is used when projecting index-fields via DocumentQuery
public class EmployeeDetails
{
  public string EmployeeName { get; set; }
  public string EmployeeID { get; set; }
}
```

##### RawQuery

```csharp
using (var session = store.OpenSession())
{
  List<TsIndex.IndexEntry> results = session.Advanced
       // Return only the EmployeeID index-field in the results
      .RawQuery<TsIndex.IndexEntry>($@"
            from index 'TsIndex'
            where BPM > 100.0
            select distinct EmployeeID
       ")
      .ToList();
}
```

##### RQL

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

## Syntax

- `session.Query`

```json
IRavenQueryable<T> Query<T, TIndexCreator>() where TIndexCreator 
: AbstractCommonApiForIndexes, new();
```

- `DocumentQuery`

```json
IDocumentQuery<T> DocumentQuery<T, TIndexCreator>() where TIndexCreator 
: AbstractCommonApiForIndexes, new();
```

| Parameter | Description |
| - | - |
| **T** | The results class |
| **TIndexCreator** | Index |

## 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.md)
- [Range Selection](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/choosing-query-range.md)
- [Filtering](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/filtering.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.md)
