See on GitHub

    Choosing Time Series Range

    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.

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

    var baseTime = new DateTime(2020, 5, 17, 00, 00, 00);
var from = baseTime;
var to = baseTime.AddMinutes(10);

var query = session
    .Query<Employee>()
    .Where(employee => employee.Address.Country == "UK")
    .Select(employee => RavenQuery
         // Specify the range:
         // pass a 'from' and a 'to' DateTime values to the 'TimeSeries' method
        .TimeSeries(employee, "HeartRates", from, to)
         // Call 'Offset' to adjust the timestamps in the returned results to your local time (optional)
        .Offset(TimeSpan.FromHours(3))
        .ToList());

// Execute the query
List<TimeSeriesRawResult> result = query.ToList();
    var baseTime = new DateTime(2020, 5, 17, 00, 00, 00);
var from = baseTime;
var to = baseTime.AddMinutes(10);

var query = session.Advanced
    .DocumentQuery<Employee>()
    .WhereEquals(employee => employee.Address.Country, "UK")
    .SelectTimeSeries(builder => builder.From("HeartRates")
         // Specify the range:
         // pass a 'from' and a 'to' DateTime values to the 'Between' method
        .Between(from, to)
         // Call 'Offset' to adjust the timestamps in the returned results to your local time (optional)
        .Offset(TimeSpan.FromHours(3))
        .ToList());

// Execute the query
List<TimeSeriesRawResult> result = query.ToList();
    var baseTime = new DateTime(2020, 5, 17, 00, 00, 00);

var query = session.Advanced
    .RawQuery<TimeSeriesRawResult>(@"
        from Employees
        where Address.Country == 'UK'
        select timeseries (
            from HeartRates
            between $from and $to
            offset '03:00'
        )")
    .AddParameter("from", baseTime)
    .AddParameter("to", baseTime.AddMinutes(10));

// Execute the query
List<TimeSeriesRawResult> results = query.ToList();
    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"
)

    Retrieve first or last entries:

    • Use FromFirst() to specify the time frame from the start of the time series.
      Use FromLast() to specify the time frame from the end of the time series.
      A query function can use either FromFirst or FromLast, but not both.

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

    var query = session
    .Query<Employee>()
    .Select(p => RavenQuery
        .TimeSeries(p, "HeartRates")
         // Call 'FromLast'
         // specify the time frame from the end of the time series
        .FromLast(x => x.Minutes(30))
        .Offset(TimeSpan.FromHours(3))
        .ToList());

// Execute the query
List<TimeSeriesRawResult> result = query.ToList();
    var query = session.Advanced
    .DocumentQuery<Employee>()
    .SelectTimeSeries(builder => builder.From("HeartRates")
         // Call 'FromLast'
         // specify the time frame from the end of the time series
        .FromLast(x => x.Minutes(30))
        .Offset(TimeSpan.FromHours(3))
        .ToList());

// Execute the query
List<TimeSeriesRawResult> result = query.ToList();
    var query = session.Advanced
     // Provide the raw RQL to the RawQuery method:
    .RawQuery<TimeSeriesRawResult>(@"
        from Employees
        select timeseries (
            from HeartRates
            last 30 min
            offset '03:00'
        )");

// Execute the query
List<TimeSeriesRawResult> results = query.ToList();
    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.:

      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.
      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.
      Using Studio, you can apply parameters as follows for a clearer query.

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

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

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

    related articlesRelated Articles

    Time Series Overview
    Time Series Overview

    Studio Articles
    Studio Time Series Management

    Time Series Indexing
    Time Series Indexing

    Time Series Queries
    Filtering
    Aggregation and Projection
    Indexed Time Series Queries

    Policies
    Time Series Rollup and Retention

    Home / Docs / Document Extensions / Timeseries / Querying / Choosing Query Range