Append Time Series with Bulk Insert


Usage

Flow:

  • Call documentStore.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".

const baseTime = new Date();

// Create a BulkInsertOperation instance
const bulkInsert = documentStore.bulkInsert();

{
    // Call 'TimeSeriesFor', pass it:
    // * The document ID
    // * The time series name
    const timeSeriesBulkInsert = 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) 
    const nextMinute = new Date(baseTime.getTime() + 60_000 * 1);
    await timeSeriesBulkInsert.append(nextMinute, 61, "watches/fitbit");

    timeSeriesBulkInsert.dispose();
}

// Call finish to send all data to the server
await bulkInsert.finish();

Append multiple entries:

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

const baseTime = new Date();

const bulkInsert = documentStore.bulkInsert();

{
    const timeSeriesBulkInsert = bulkInsert.timeSeriesFor("users/john", "HeartRates");

    for (let i = 0; i < 100; i++) {
        let randomValue = Math.floor(Math.random() * (29)) + 60;
        let nextMinute = new Date(baseTime.getTime() + 60_000 * (i + 1));
        
        await timeSeriesBulkInsert.append(nextMinute, randomValue, "watches/fitbit");
    }

    timeSeriesBulkInsert.dispose();
}

await bulkInsert.finish();

Append multiple values per entry:

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

const baseTime = new Date();

const bulkInsert = documentStore.bulkInsert();

{
    const timeSeriesBulkInsert = bulkInsert.timeSeriesFor("users/john", "HeartRates");

    const exerciseHeartRates = [89, 82, 85];
    await timeSeriesBulkInsert.append(new Date(baseTime.getTime() + 60_000),
        exerciseHeartRates, "watches/fitbit");

    const restingHeartRates = [59, 63, 61, 64, 65];
    await timeSeriesBulkInsert.append(new Date(baseTime.getTime() + 60_000 * 2),
        restingHeartRates, "watches/fitbit");

    timeSeriesBulkInsert.dispose();
}

await bulkInsert.finish();

Append multiple time series:

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

const baseTime = new Date();

const bulkInsert = documentStore.bulkInsert();

{
    // Append first time series
    const timeSeriesBulkInsert = bulkInsert.timeSeriesFor("users/john", "HeartRates");
    await timeSeriesBulkInsert.append(new Date(baseTime.getTime() + 60_000), 61, "watches/fitbit");
    await timeSeriesBulkInsert.append(new Date(baseTime.getTime() + 60_000 * 2), 62, "watches/fitbit");
    timeSeriesBulkInsert.dispose();
}
{
    // Append another time series
    const timeSeriesBulkInsert = bulkInsert.timeSeriesFor("users/john", "ExerciseHeartRates");
    await timeSeriesBulkInsert.append(new Date(baseTime.getTime() + 60_000 * 3), 81, "watches/apple-watch");
    await timeSeriesBulkInsert.append(new Date(baseTime.getTime() + 60_000 * 4), 82, "watches/apple-watch");
    timeSeriesBulkInsert.dispose();
}
{
    // Append time series in another document
    const timeSeriesBulkInsert = bulkInsert.timeSeriesFor("users/jane", "HeartRates");
    await timeSeriesBulkInsert.append(new Date(baseTime.getTime() + 60_000), 59, "watches/fitbit");
    await timeSeriesBulkInsert.append(new Date(baseTime.getTime() + 60_000 * 2), 60, "watches/fitbit");
    timeSeriesBulkInsert.dispose();
}

await bulkInsert.finish();

Syntax

bulkInsert.timeSeriesFor

timeSeriesFor(id, name);
Parameter Type Description
id string Document ID
name string Time Series Name

timeSeriesFor.Append overloads:

append(timestamp, value);
append(timestamp, value, tag);
append(timestamp, values);
append(timestamp, values, tag);
Parameter Type Description
timestamp Date TS-entry's timestamp
value number A single value
values number[] Multiple values
tag string TS-entry's tag (optional)