see on GitHub

Session: Get Time Series Entries


To get a range of time series entries, use one of the TimeSeriesFor.Get methods.

  • Include time series data while loading or querying documents, to keep the data locally in the client's session and refrain from unnecessary additional trips to the server.
  • When caching is enabled, time series data is kept in the session cache as well.


TimeSeriesFor.Get

TimeSeriesFor.Get retrieves a range of entries from a single time series.

  • To retrieve multiple series' data, use the GetMultipleTimeSeriesOperation document-store operation.
  • Retrieved data can be sliced to pages to get time series entries gradually, one custom-size page at a time.

Syntax

  • There are two TimeSeriesFor.Get methods:

    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);
  • Parameters

    Parameters Type Description
    from DateTime? Range Start
    to DateTime? Range End
    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.

Usage Flow

  • Open a session.
  • Create an instance of TimeSeriesFor.
  • Call TimeSeriesFor.Get.

Usage Samples

  • In this sample we retrieve all the entries of a time series, using its parent-document's ID explicitly.

    // Get all time series entries
    TimeSeriesEntry[] val = session.TimeSeriesFor("users/john", "HeartRate")
        .Get(DateTime.MinValue, DateTime.MaxValue);
  • In this sample we query for a document and get its "Heartrate" time series data.

    // Query for a document with the Name property "John" 
    // and get its HeartRate 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], "HeartRate")
            .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).
    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;
    
    // Use Get with a Named type
    using (var session = store.OpenSession())
    {
        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;
    }