Append & Update Time Series


  • Use TimeSeriesFor.Append for the following actions:

    • Creating a new time series
      Appending an entry to a time series that doesn't exist yet
      will create the time series and add it the new entry.
    • Creating a new time series entry
      Appending a new entry to an existing time series
      will add the entry to the series at the specified timestamp.
    • Modifying an existing time series entry
      Use Append to update the data of an existing entry with the specified timestamp.
  • Each call to Append handles a single time series entry.

  • To append multiple entries in a single transaction you can:



Append usage

Flow:

  • Open a session.
  • Create an instance of TimeSeriesFor and pass it the following:
  • Call TimeSeriesFor.Append and pass it the time series entry details.
  • Call session.SaveChanges for the action to take effect on the server.

Note:

  • A DocumentDoesNotExistException exception is thrown if the specified document does not exist.

Examples

Append entries with a single value:

  • In this example, entries are appended with a single value.
  • Although a loop is used to append multiple entries,
    all entries are appended in a single transaction when SaveChanges is executed.

var baseline = DateTime.Today;

// Append 10 HeartRate 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();
}

Append entries with multiple values:

  • In this example, 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(baseTime.AddDays(1),
        new[] { 52, 54, 63.5, 51.4, 9824 }, "companies/kitchenAppliances");

    session.TimeSeriesFor("users/john", "StockPrices")
    .Append(baseTime.AddDays(2),
        new[] { 54, 55, 61.5, 49.4, 8400 }, "companies/kitchenAppliances");

    session.TimeSeriesFor("users/john", "StockPrices")
    .Append(baseTime.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");

    // Call 'Append' with the custom StockPrice class
    session.TimeSeriesFor<StockPrice>("users/john")
    .Append(baseTime.AddDays(1), new StockPrice
    {
        Open = 52,
        Close = 54,
        High = 63.5,
        Low = 51.4,
        Volume = 9824,
    }, "companies/kitchenAppliances");

    session.TimeSeriesFor<StockPrice>("users/john")
    .Append(baseTime.AddDays(2), new StockPrice
    {
        Open = 54,
        Close = 55,
        High = 61.5,
        Low = 49.4,
        Volume = 8400,
    }, "companies/kitchenAppliances");

    session.TimeSeriesFor<StockPrice>("users/john")
    .Append(baseTime.AddDays(3), new StockPrice
    {
        Open = 55,
        Close = 57,
        High = 65.5,
        Low = 50,
        Volume = 9020,
    }, "companies/kitchenAppliances");

    session.SaveChanges();
}

Syntax

// Append an entry with a single value (double)
void Append(DateTime timestamp, double value, string tag = null);

// Append an entry with multiple values (IEnumerable)
void Append(DateTime timestamp, IEnumerable<double> values, string tag = null);
Parameter Type Description
timestamp DateTime Time series entry's timestamp
value double Entry's value
values IEnumerable<double> Entry's values
tag string An optional tag for the entry