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
    • Syntax
    • Usage Flow
    • Usage Samples

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<double>	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.
  • 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.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 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();
}

• Here, we append multi-value StockPrice entries.
  Notice the clarity gained by naming the values.

• Native
• Named

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