Session: Get Time Series Entries

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.

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

• Open a session.
• Create an instance of TimeSeriesFor.
  • Either pass TimeSeriesFor an explicit document ID,
    -or-
    Pass it an entity tracked by the session, e.g. a document object returned from session.Query or from session.Load.
  • Pass TimeSeriesFor the time series name.
• Call TimeSeriesFor.Get.

• 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", "HeartRates")
      .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 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).
  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.
  

  • Native
  • Named

  // 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;
  }

While retrieving time series data using TimeSeriesFor.Get, you can Include the series' parent document and/or documents referred to by entry tags.
The included documents will be cached in the session, and instantly retrieved from memory if loaded by the user.

To include parent or tagged documents, use this syntax:

// 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());