Session: Create & Modify Incremental Time Series


  • Create and modify incremental time series and their entries using IncrementalTimeSeriesFor.Increment.

  • There is no need to explicitly create or delete a time series.

    • A time series is created when its first entry is incremented.
    • A time series is deleted when all entries are deleted from it.
  • You can add a single incremental time series entry at a time.
    Note, however, that you can Increment as many times as you need to before calling session.SaveChanges, to create multiple entries in a single transaction.

  • In this page:


IncrementalTimeSeriesFor.Increment

  • IncrementalTimeSeriesFor.Increment is used for the creation of incremental time series and their entries, and for the modification of entry values.
    • Creating a new Incremental Time Series
      Incrementing entry values for an incremental time series that doesn't exist yet will create the new incremental time series with this entry.
    • Creating an Incremental Time Series Entry
      Incrementing an entry value for an entry that doesn't exist yet will add the entry to this series at the specified timestamp.
    • Modifying Entry Values
      Increment a value for an existing entry by a number of your choice.

Syntax

  • There are four IncrementalTimeSeriesFor.Increment methods:

    • Increment a time series entry's array of values at the provided timestamp.
      // Increment a time series entry's array of values at the provided timestamp
      void Increment(DateTime timestamp, IEnumerable<double> values);
    • Increment a time series entry's array of values at the current time.
      // Increment a time series entry's array of values at the current time
      void Increment(IEnumerable<double> values);
    • Increment an entry value at the provided timestamp.
      (If the entry exists and has more than one value, only the first value in its list will be incremented by the passed value.)
      // Increment an entry value at the provided timestamp
      void Increment(DateTime timestamp, double value);
    • Increment an entry value at the current time.
      (If the entry exists and has more than one value, only the first value in its list will be incremented by the passed value.)
      // Increment an entry value at the current time
      void Increment(double value);
  • Parameters

    Parameters Type Description
    timestamp DateTime Time series entry's timestamp
    values IEnumerable A list of delta values to increment the entry values by
    value double The delta to increment the entry value by
  • Exceptions
    If the document doesn't exist, a DocumentDoesNotExistException exception is thrown.

Usage Flow

  • Open a session
  • Create an instance of IncrementalTimeSeriesFor and pass it:
  • Call IncrementalTimeSeriesFor.Increment.
  • Call session.SaveChanges for the action to take effect on the server.

Code Samples

  • Increment an array of values in an incremental time series entry.
    var ts = session.IncrementalTimeSeriesFor("companies/webstore", "INC:Downloads");
    ts.Increment(baseline.AddMinutes(1), new double[] { 10, -10, 0, 0 });
    session.SaveChanges();
    • If the time series doesn't exist, it will be created with this first entry.
    • If the entry doesn't exist, it will be created with the provided values.
    • If the entry exists, its values will be increased by the provided values.
      • a negative number will decrease the current value.