see on GitHub

Session: Appending & Updating Time Series


  • Create and update time series and their entries using TimeSeriesFor.Append.

  • You can append a single time series entry at a time.
    Note, however, that you can Append as many times as you need to before calling session.SaveChanges, to append multiple entries in a single transaction.

  • In this page:


TimeSeriesFor.Append

  • TimeSeriesFor.Append is used for the creation of time series and time series entries, and for the modification of entries values.
    • Creating a Time Series
      Append an entry to a time series that doesn't exist yet,
      to create the time series and add it the new entry.
    • Creating a Time Series Entry
      Append an existing time series a new entry,
      to add the entry to this series at the specified timestamp.
    • Modifying Entry Values
      Append a time series an entry it already has,
      to update the existing entry with the new data.

Syntax

  • There are two TimeSeriesFor.Append methods:

    • Append an entry with a single value.
      // Append an entry with a single value (double)
      void Append(DateTime timestamp, double value, string tag = null);
    • Append an entry with multiple values.
      // Append an entry with multiple values (IEnumerable)
      void Append(DateTime timestamp, IEnumerable<double> values, string tag = null);
  • Parameters

    Parameters Type Description
    timestamp DateTime Time series entry's timestamp
    value double Entry's value
    values IEnumerable Entry's values
    tag string Entry's tag
    The tag is optional.
  • Exceptions
    If the document doesn't exist, a DocumentDoesNotExistException exception is thrown.

Usage Flow

  • Open a session.
  • Create an instance of TimeSeriesFor.
  • Call TimeSeriesFor.Append.
  • Call session.SaveChanges for the action to take effect on the server.

Usage Samples

  • In this sample, we append an entry with a single value.
    Though We run a loop to append multiple entries, all entries are appended in a single transaction when SaveChanges is executed.

    var baseline = DateTime.Today;
    
    // Append 10 heart rate values
    using (var session = store.OpenSession())
    {
        session.Store(new User { Name = "John" }, "users/john");
    
        ISessionDocumentTimeSeries tsf = session.TimeSeriesFor("users/john", "HeartRates");
    
        for (int i = 0; i < 10; i++)
        {
            tsf.Append(baseline.AddSeconds(i), new[] { 67d }, "watches/fitbit");
        }
    
        session.SaveChanges();
    }
  • Here, we append multi-value StockPrice entries.
    Notice the clarity gained by naming the values.

    using (var session = store.OpenSession())
    {
        session.Store(new User { Name = "John" }, "users/john");
    
        session.TimeSeriesFor("users/john", "StockPrices")
        .Append(baseline.AddDays(1),
            new[] { 52, 54, 63.5, 51.4, 9824 }, "companies/kitchenAppliances");
    
        session.TimeSeriesFor("users/john", "StockPrices")
        .Append(baseline.AddDays(2),
            new[] { 54, 55, 61.5, 49.4, 8400 }, "companies/kitchenAppliances");
    
        session.TimeSeriesFor("users/john", "StockPrices")
        .Append(baseline.AddDays(3),
            new[] { 55, 57, 65.5, 50, 9020 }, "companies/kitchenAppliances");
    
        session.SaveChanges();
    }
    using (var session = store.OpenSession())
    {
        session.Store(new User { Name = "John" }, "users/john");
    
        session.TimeSeriesFor<StockPrice>("users/john")
        .Append(baseline.AddDays(1), new StockPrice
        {
            Open = 52,
            Close = 54,
            High = 63.5,
            Low = 51.4,
            Volume = 9824,
        }, "companies/kitchenAppliances");
    
        session.TimeSeriesFor<StockPrice>("users/john")
        .Append(baseline.AddDays(2), new StockPrice
        {
            Open = 54,
            Close = 55,
            High = 61.5,
            Low = 49.4,
            Volume = 8400,
        }, "companies/kitchenAppliances");
    
        session.TimeSeriesFor<StockPrice>("users/john")
        .Append(baseline.AddDays(3), new StockPrice
        {
            Open = 55,
            Close = 57,
            High = 65.5,
            Low = 50,
            Volume = 9020,
        }, "companies/kitchenAppliances");
    
        session.SaveChanges();
    }