Time Series: JavaScript Support

• With the introduction of time series, RavenDB has extended its JavaScript support to include manipulations involving time series data when patching single or multiple documents.

• Time series capabilities can be achieved via JavaScript when using the following methods:

  • session.Advanced.Defer - perform patch via the Session
  • PatchOperation - perform patch via a Store operation
  • PatchByQueryOperation - perform query & patch via a Store operation

• The server treats timestamps passed in the scripts as UTC, no conversion is applied by the client to local time.

• In this page:

  • JavaScript time series API methods
    • timeseries - choose a time series
    • timeseries.append - append an entry
    • timeseries.delete - delete entries
    • timeseries.get - get entries
  • Examples

JavaScript time series 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	Description
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)

Parameter	Type	Description
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	Description
from (optional)	DateTime	Entries will be deleted starting at this timestamp (inclusive) Default: DateTime.Min
to (optional)	DateTime	Entries will be deleted up to this timestamp (inclusive) Default: DateTime.Max

timeseries.get (from, to)

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

Parameter	Type	Description
from (optional)	DateTime	Get time series entries starting from this timestamp (inclusive) Default: DateTime.Min
to (optional)	DateTime	Get time series entries ending at this timestamp (inclusive) 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": ...
}
...
]

Examples

• This example shows a script that appends 100 entries to time series "HeartRates" in document "Users/john".
  The script is passed to method session.Advanced.Defer.

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();

• This example shows a script that deletes time series "HeartRates" for documents that match the specified query. The script is passed to the PatchByQueryOperation operation.

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);