Append Time Series with Bulk Insert


Usage

Flow:

  • Call store.BulkInsert to create a BulkInsertOperation instance.
  • Call TimeSeriesFor on that instance and pass it:
    • The document ID
      (An exception will be thrown if the specified document does Not exist).
    • The time series name
      (Appending entries to a time series that doesn't yet exist yet will create the time series).
  • To append an entry, call Append and pass it:
    • The entry's Timestamp
    • The entry's Value or Values
    • The entry's Tag (optional)

Note:

  • To append multiple entries, call Append as many times as needed.
  • Ensure there is at least a 1-millisecond interval between each timestamp.
  • The client converts all timestamps to UTC before sending the batch to the server.
  • Multiple time series can be appended in the same BulkInsertOperation. See this example below.

Examples

Append single entry:


In this example, we append a single entry with a single value to time series "HeartRates".

var baseTime = DateTime.Today;

// Create a BulkInsertOperation instance
using (BulkInsertOperation bulkInsert = store.BulkInsert())
{
    // Create a TimeSeriesBulkInsert instance
    using (TimeSeriesBulkInsert timeSeriesBulkInsert =
           // Call 'TimeSeriesFor', pass it:
           // * The document ID
           // * The time series name
           bulkInsert.TimeSeriesFor("users/john", "HeartRates"))
    {
        // Call 'Append' to add an entry, pass it:
        // * The entry's Timestamp 
        // * The entry's Value or Values 
        // * The entry's Tag (optional) 
        timeSeriesBulkInsert.Append(baseTime.AddMinutes(1), 61d, "watches/fitbit");
    }
}

Append multiple entries:


In this example, we append 100 entries with a single value to time series "HeartRates".

using (BulkInsertOperation bulkInsert = store.BulkInsert())
{
    using (TimeSeriesBulkInsert timeSeriesBulkInsert =
           bulkInsert.TimeSeriesFor("users/john", "HeartRates"))
    {
        Random rand = new Random();
        
        for (int i = 0; i < 100; i++)
        {
            double randomValue = rand.Next(60, 91); 
            timeSeriesBulkInsert.Append(baseTime.AddMinutes(i), randomValue, "watches/fitbit");
        }
    }
}

Append multiple values per entry:


In this example, we append multiple values per entry in time series "HeartRates".

using (BulkInsertOperation bulkInsert = store.BulkInsert())
{
    using (TimeSeriesBulkInsert timeSeriesBulkInsert =
           bulkInsert.TimeSeriesFor("users/john", "HeartRates"))
    {
        var exerciseHeartRates = new List<double> { 89d, 82d, 85d };
        timeSeriesBulkInsert.Append(baseline.AddMinutes(1), exerciseHeartRates, "watches/fitbit");
        
        var restingHeartRates = new List<double> { 59d, 63d, 61d, 64d, 65d };
        timeSeriesBulkInsert.Append(baseline.AddMinutes(2), restingHeartRates, "watches/apple-watch");
    }
}

Append multiple time series:


In this example, we append multiple time series in different documents in the same batch.

using (BulkInsertOperation bulkInsert = store.BulkInsert())
{
    // Append first time series
    using (TimeSeriesBulkInsert timeSeriesBulkInsert =
           bulkInsert.TimeSeriesFor("users/john", "HeartRates"))
    {
        timeSeriesBulkInsert.Append(baseTime.AddMinutes(1), 61d, "watches/fitbit");
        timeSeriesBulkInsert.Append(baseTime.AddMinutes(2), 62d, "watches/fitbit");
    }
    
    // Append another time series
    using (TimeSeriesBulkInsert timeSeriesBulkInsert =
           bulkInsert.TimeSeriesFor("users/john", "ExerciseHeartRates"))
    {
        timeSeriesBulkInsert.Append(baseTime.AddMinutes(3), 81d, "watches/apple-watch");
        timeSeriesBulkInsert.Append(baseTime.AddMinutes(4), 82d, "watches/apple-watch");
    }
    
    // Append time series in another document
    using (TimeSeriesBulkInsert timeSeriesBulkInsert =
           bulkInsert.TimeSeriesFor("users/jane", "HeartRates"))
    {
        timeSeriesBulkInsert.Append(baseTime.AddMinutes(1), 59d, "watches/fitbit");
        timeSeriesBulkInsert.Append(baseTime.AddMinutes(2), 60d, "watches/fitbit");
    }
}

Syntax

BulkInsert.TimeSeriesFor

public TimeSeriesBulkInsert TimeSeriesFor(string id, string name)
Parameter Type Description
id string Document ID
name string Time Series Name

TimeSeriesFor.Append overloads:

// Append a single value
public void Append(DateTime timestamp, double value, string tag = null)
// Append multiple values
public void Append(DateTime timestamp, ICollection<double> values, string tag = null)
Parameter Type Description
timestamp DateTime TS-entry's timestamp
value double A single value
values ICollection<double> Multiple values
tag string TS-entry's tag (optional)