Time Series: JavaScript Support

With the introduction of time series, RavenDB's support for the execution of JavaScript-based operations over single and multiple documents has been extended to allow manipulations involving time series.

• Methods that gain time series functionality this way are:

  • session.Advanced.Defer - session patching method
  • PatchOperation - store patching operation
  • PatchByQueryOperation - store patch-by-query operation

• In this page:

  • JavaScript API methods
    • timeseries - Choose a Time Series
    • timeseries.append - Append an Entry
    • timeseries.delete - Delete Entries Range
    • timeseries.get - Get Entries Range
  • Usage Samples

JavaScript API methods

The JavaScript time series API includes these methods:

timeseries (doc, name)

Choose a time series by the ID of its owner document and by the series name.

Parameter	Type	Explanation
doc	string or document instance	Document ID, e.g. timeseries('users/1-A', 'StockPrice') e.g. timeseries(this, 'StockPrice')
name	string	Time Series Name

timeseries.append

• You can use two overloads, to append tagged or untagged time series entries.

  • timeseries.append (timestamp, values)
  • timeseries.append (timestamp, values, tag)

• Parameters:

  Parameter	Type	Explanation
  timestamp	DateTime	Timestamp
  values	double[]	Values
  tag	string	Tag

timeseries.delete (from, to)

Use this method to delete a range of entries from a document.

Parameter	Type	Explanation
from (optional)	DateTime	Range Start Default: DateTime.Min
to (optional)	DateTime	Range End Default: DateTime.Max

timeseries.get (from, to)

Use this method to retrieve a range of time series entries.

• Parameters:

  Parameter	Type	Explanation
  from (optional)	DateTime	Range Start Default: DateTime.Min
  to (optional)	DateTime	Range End Default: DateTime.Max

• Return Type:
  Values are returned in an array of time series entries, i.e. -

[
{
"Timestamp" : ...
"Tag": ...
"Values": ...
"IsRollup": ...
},
{
"Timestamp" : ...
"Tag": ...
"Values": ...
"IsRollup": ...
}
..
]

Usage Samples

• In this sample, we pass session.Advanced.Defer a script that appends a document 100 time series entries.

var baseTime = DateTime.UtcNow;

// Create arrays of timestamps and random values to patch
var values = new List<double>();
var timeStamps = new List<DateTime>();

for (var i = 0; i < 100; i++)
{
  values.Add(68 + Math.Round(19 * new Random().NextDouble()));
  timeStamps.Add(baseTime.AddMinutes(i));
}

session.Advanced.Defer(new PatchCommandData("users/john", null,
  new PatchRequest
  {
      Script = @"
          var i = 0;
          for(i = 0; i < $values.length; i++)
          {
              timeseries(id(this), $timeseries)
              .append (
                  new Date($timeStamps[i]), 
                  $values[i], 
                  $tag);
          }",

      Values =
      {
          { "timeseries", "HeartRates" },
          { "timeStamps", timeStamps },
          { "values", values },
          { "tag", "watches/fitbit" }
      }
  }, null));

session.SaveChanges();

• In this sample, we pass PatchByQueryOperation a script that runs a document query and deletes the HeartRate time series from matching documents.

PatchByQueryOperation deleteByQueryOp = new PatchByQueryOperation(new IndexQuery
{
  Query = @"from Users as u
            where u.Age < 30
            update
            {
                timeseries(u, $name).delete($from, $to)
            }",
  
  QueryParameters = new Parameters
  {
      { "name", "HeartRates" },
      { "from", DateTime.MinValue },
      { "to", DateTime.MaxValue }
  }
});

// Execute the operation: 
// Time series "HeartRates" will be deleted for all users with age < 30
store.Operations.Send(deleteByQueryOp);