---
title: "Choosing Time Series Range"
url: "https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/choosing-query-range"
version: "6.2"
language: "nodejs"
---

# Choosing Time Series Range

> Client language: Node.js. Also available for [C#](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/choosing-query-range.md), [Python](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/choosing-query-range.python.md), [PHP](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/choosing-query-range.php.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**
>
> - Queries can retrieve data from the entire time series or from a specific range of entries,  
>   such as those collected in the last 7 days.
>
> - For an overview of the available time series queries and their syntax, please refer to [Time series querying](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/session/querying.nodejs.md).
>
> - In this page:
>   - [Choose range in a query](#choose-range-in-a-query)
>     - [Specify range](#specify-range)
>     - [Retrieve first or last entries](#retrieve-first-or-last-entries)
>   - [Choose range - RQL syntax](#choose-range---rql-syntax)
>     - [`between` and `and`](#and-)
>     - [`first` and `last`](#and--1)

## Choose range in a query

#### Specify range:

- Provide 'from' & 'to' DateTime values to the time series query to retrieve entries only from that range (inclusive).  
  Omitting these parameters will retrieve the entire series.

- The provided DateTime values are handled by the server as UTC.  
  The client does Not perform any conversion to UTC prior to sending the request to the server.

- Note: calling 'offset' will only adjust the timestamps in the returned results to your local time (optional).

- In this example, we specify a 10-minute range from which we retrieve UK employees "HeartRates" entries.

##### Query

```javascript
// Define the time series query part (expressed in RQL):
const tsQueryText = `
  from HeartRates
  between "2020-05-17T00:00:00.0000000"
  and "2020-05-17T00:10:00.0000000"
  offset "03:00"`;

// Define the query:
const query = session.query({ collection: "employees" })
  .whereEquals("Address.Country", "UK")
  .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult);

// Execute the query:
const results = await query.all();

// Access entries results:
rawResults = results[0];
assert.equal((rawResults instanceof TimeSeriesRawResult), true);

const tsEntry = rawResults.results[0];
assert.equal((tsEntry instanceof TimeSeriesEntry), true);

const tsValue = tsEntry.value;
```

##### Query\_using\_params

```javascript
const from = new Date("2020-05-17T00:00:00.0000000");
const to = new Date("2020-05-17T00:10:00.0000000");

// Define the time series query part (expressed in RQL):
const tsQueryText = `
  from HeartRates
  between $from and $to
  offset "03:00"`;

// Define the query:
const query = session.query({ collection: "employees" })
  .whereEquals("Address.Country", "UK")
  .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult)
  .addParameter("from", from)
  .addParameter("to", to);

// Execute the query:
const results = await query.all();

// Access entries results:
rawResults = results[0];
assert.equal((rawResults instanceof TimeSeriesRawResult), true);

const tsEntry = rawResults.results[0];
assert.equal((tsEntry instanceof TimeSeriesEntry), true);

const tsValue = tsEntry.value;
```

##### RawQuery

```javascript
const rql = `
  from "Employees" as employee
  where employee.Address.Country == "UK"
  select timeseries(
      from employee.HeartRates
      between "2020-05-17T00:00:00.0000000"
      and "2020-05-17T00:10:00.0000000"
      offset "03:00"
  )`;

const query = session.advanced.rawQuery(rql, TimeSeriesRawResult);

const result = await query.all();
```

##### RawQuery\_using\_params

```javascript
const rql = `
  from "Employees" as employee
  where employee.Address.Country == "UK"
  select timeseries(
      from employee.HeartRates
      between $from and $to
      offset "03:00"
  )`;

const from = new Date("2020-05-17T00:00:00.0000000");
const to = new Date("2020-05-17T00:10:00.0000000");

const query = session.advanced.rawQuery(rql, TimeSeriesRawResult)
  .addParameter("from", from)
  .addParameter("to", to);

const result = await query.all();
```

##### RQL

```sql
// RQL:
from "employees" as employee
where employee.Address.Country == "UK"
select timeseries(
  from employee.HeartRates
  between "2020-05-17T00:00:00.0000000"
  and "2020-05-17T00:10:00.0000000"
  offset "03:00"
)

// RQL with parameters:
from "employees"
where Address.Country = $p0
select timeseries(
  from HeartRates
  between $from and $to
  offset "03:00"
)
{
"p0":   "UK",
"from": "2020-05-17T00:00:00.0000000",
"to":   "2020-05-17T00:10:00.0000000"
}
```

#### Retrieve first or last entries:

- Use `first` to specify the time frame from the start of the time series.  
  Use `last` to specify the time frame from the end of the time series.  
  A query function can use either `first` or `last`, but not both.

- In this example, we select only entries in the last 30 minutes of the "HeartRates" time series.

##### Query

```javascript
// Define the time series query part (expressed in RQL):
const tsQueryText = `
  from HeartRates
  last 30 min
  offset "03:00"`;

// Define the query:
const query = session.query({ collection: "employees" })
  .selectTimeSeries(b => b.raw(tsQueryText), TimeSeriesRawResult);

// Execute the query:
const results = await query.all();
```

##### RawQuery

```javascript
const rql = `
  from "Employees" as employee
  select timeseries(
      from employee.HeartRates
      last 30 min
      offset "03:00"
  )`;

const query = session.advanced.rawQuery(rql, TimeSeriesRawResult);

const result = await query.all();
```

##### RQL

```sql
from "Employees" as e 
select timeseries(
  from e.HeartRates
  last 30 min
  offset "03:00"
)
```

## Choose range - RQL syntax

#### `between` and `and`:

- Use the `between` and `and` keywords to retrieve time series entries from the specified range (inclusive).  
  Provide the timestamps in UTC format.
  E.g.:

##### RQL\_select\_syntax

```sql
from "Employees"
where Address.Country == "UK"
select timeseries(
  from HeartRates
  between "2020-05-17T00:00:00.0000000Z" // start of range
  and "2020-05-17T01:00:00.0000000Z"     // end of range
)

// Results will include only time series entries within the specified range for employees from UK.
```

##### RQL\_declare\_syntax

```sql
declare timeseries getHeartRates(employee)
{
  from HeartRates
  between "2020-05-17T00:00:00.0000000Z" // start of range
  and "2020-05-17T01:00:00.0000000Z"     // end of range
}

from "Employees" as e
where e.Address.Country == "UK"
select getHeartRates(e) 

// Results will include only time series entries within the specified range for employees from UK.
```

- RQL queries can be executed from Studio's [query view](https://docs.ravendb.net/6.2/studio/database/queries/query-view.md).  
  Using Studio, you can apply parameters as follows for a clearer query.

```sql
$from = "2020-05-17T00:00:00.0000000Z"
$to = "2020-05-17T01:00:00.0000000Z"

from "Employees"
where Address.Country == "UK"
select timeseries(
  from HeartRates
  between $from and $to  // using parameters
)
```

#### `first` and `last`:

- Use `first` to specify the time frame from the start of the time series.  
  Use `last` to specify the time frame from the end of the time series.  
  A query function can use either `first` or `last`, but not both. E.g. -

```sql
// Retrieve all entries from the last day, starting from the end of time series "HeartRates"
from "Employees"
select timeseries(
  from HeartRates
  last 1 day
)
```

```sql
// Retrieve the first 10 minutes of entries from the beginning of time series "HeartRates"
from "Employees"
select timeseries(
  from HeartRates
  first 10 min
)
```

- The range is specified using a whole number of one of the following units.

  - **seconds**  ( seconds/ second / s )
  - **minutes**  ( minutes / minute / min )
  - **hours**    ( hours / hour / h )
  - **days**     ( days / day / d )
  - **months**   ( months / month / mon / mo )
  - **quarters** ( quarters / quarter / q )
  - **years**    ( years / year / y )
  - Note: **milliseconds** are currently not supported by 'first' and 'last' in a time series query.

## 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.nodejs.md)
- [Filtering](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/filtering.nodejs.md)
- [Aggregation and Projection](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/aggregation-and-projections.nodejs.md)
- [Indexed Time Series Queries](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/using-indexes.nodejs.md)
- [Time Series Rollup and Retention](https://docs.ravendb.net/6.2/document-extensions/timeseries/rollup-and-retention.nodejs.md)
