Get Time Series Entries


  • Use TimeSeriesFor.Get to retrieve a range of entries from a single time series.
    To retrieve a range of entries from multiple series, use the GetMultipleTimeSeriesOperation operation.

  • The retrieved data can be paged to get the time series entries gradually, one custom-size page at a time.

  • By default, the session will track the retrieved time series data. See disable tracking to learn how to disable.

  • When getting the time series entries,
    you can also include the series' parent document and/or documents referred to by the entry tag.
    Learn more below.

  • Calling TimeSeriesFor.Get will result in a trip to the server unless the series' parent document was loaded
    (or queried for) with the time series included beforehand.
    Learn more in: Including time series.

  • In this page:


Get usage

  • Open a session.
  • Create an instance of TimeSeriesFor and pass it the following:
  • Call TimeSeriesFor.Get.

Examples

In this example, we retrieve all entries of the "Heartrate" time series.
The ID of the parent document is explicitly specified.

// Get all time series entries
TimeSeriesEntry[] val = session.TimeSeriesFor("users/john", "HeartRates")
    .Get(DateTime.MinValue, DateTime.MaxValue);

In this example, we query for a document and get its "Heartrate" time series data.

// Query for a document with the Name property "John" 
// and get its HeartRates time-series values
using (var session = store.OpenSession())
{
    var baseline = DateTime.Today;

    IRavenQueryable<User> query = session.Query<User>()
        .Where(u => u.Name == "John");

    var result = query.ToList();

    TimeSeriesEntry[] val = session.TimeSeriesFor(result[0], "HeartRates")
        .Get(DateTime.MinValue, DateTime.MaxValue);

    session.SaveChanges();
}

  • Here, we check whether a stock's closing-time price is rising from day to day (over three days).
    This example is based on the sample entries that were entered in this example.

  • Since each time series entry contains multiple StockPrice values,
    we include a sample that uses named time series values to make the code easier to read.

// Use Get without a named type
// Is the stock's closing-price rising?
bool goingUp = false;

using (var session = store.OpenSession())
{
    TimeSeriesEntry[] val = session.TimeSeriesFor("users/john", "StockPrices")
        .Get();

    var closePriceDay1 = val[0].Values[1];
    var closePriceDay2 = val[1].Values[1];
    var closePriceDay3 = val[2].Values[1];

    if ((closePriceDay2 > closePriceDay1)
        &&
        (closePriceDay3 > closePriceDay2))
        goingUp = true;
}
goingUp = false;

using (var session = store.OpenSession())
{
    // Call 'Get' with the custom StockPrice class type
    TimeSeriesEntry<StockPrice>[] val = session.TimeSeriesFor<StockPrice>("users/john")
        .Get();

    var closePriceDay1 = val[0].Value.Close;
    var closePriceDay2 = val[1].Value.Close;
    var closePriceDay3 = val[2].Value.Close;

    if ((closePriceDay2 > closePriceDay1)
        &&
        (closePriceDay3 > closePriceDay2))
        goingUp = true;
}

Include parent and tagged documents

  • When retrieving time series entries using TimeSeriesFor.Get,
    you can include the series' parent document and/or documents referred to by the entries tags.

  • The included documents will be cached in the session, and instantly retrieved from memory if loaded by the user.

  • Use the following syntax to include the parent or tagged documents:

// Get all time series entries
TimeSeriesEntry[] entries =
    session.TimeSeriesFor("users/john", "HeartRates")
        .Get(DateTime.MinValue, DateTime.MaxValue,
            includes: builder => builder
        // Include documents referred-to by entry tags
        .IncludeTags()
        // Include Parent Document
        .IncludeDocument());

Syntax

TimeSeriesEntry[] Get(DateTime? from = null, DateTime? to = null,
    int start = 0, int pageSize = int.MaxValue);

//The stongly-typed API is used, to address time series values by name.
TimeSeriesEntry<TValues>[] Get(DateTime? from = null, DateTime? to = null,
int start = 0, int pageSize = int.MaxValue);
Parameter Type Description
from DateTime? Get the range of time series entries starting from this timestamp (inclusive).
Default: DateTime.MinValue
to DateTime? Get the range of time series entries ending at this timestamp (inclusive).
Default: DateTime.MaxValue
start int Paging first entry.
E.g. 50 means the first page would start at the 50th time series entry.
Default: 0, for the first time-series entry.
pageSize int Paging page-size.
E.g. set pageSize to 10 to retrieve pages of 10 entries.
Default: int.MaxValue, for all time series entries.

Return Values

  • TimeSeriesEntry[] - an array of time series entry classes.

public class TimeSeriesEntry
{
    public DateTime Timestamp { get; set; }
    public double[] Values { get; set; }
    public string Tag { get; set; }
    public bool IsRollup { get; set; }

    public double Value;

    //..
}
  • TimeSeriesEntry<TValues>[] - Time series values that can be referred to by name.