Skip to Navigation
Append & Update Time Series
-
Use
TimeSeriesFor.Appendfor the following actions:-
Create 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. -
Create 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. -
Modify an existing time series entry:
Use Append to update the data of an existing entry with the specified timestamp.
-
-
Each call to
Appendhandles a single time series entry. -
To append multiple entries in a single transaction:
- Call
Appendas many times as needed before callingsession.SaveChanges, or - - Use patching to update the time series. Learn more in Patch time series entries.
- Call
Append usage
Flow:
- Open a session.
-
Create an instance of
TimeSeriesForand pass it the following:- Provide an explicit document ID, -or-
pass an entity tracked by the session, e.g. a document object returned from session.Query or from session.Load. - Specify the time series name.
- Provide an explicit document ID, -or-
- Call
TimeSeriesFor.Appendand pass it the time series entry details. - Call
session.SaveChangesfor the action to take effect on the server.
Note:
- A
DocumentDoesNotExistExceptionexception is thrown if the specified document does not exist.
Examples
Append entries with 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 whenSaveChangesis 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(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();
}
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 |
Related Articles