Patch Time Series Operations
-
Patching time series data (Append or Delete entries) can be performed via Operations.
- Use PatchOperation to patch data on a single document.
- Use PatchByQueryOperation to patch data on multiple documents.
-
Patching time series entries on a single document can also be performed via the session.
-
In this page:
Patch time series data - single document
Usage
-
Create a
PatchRequest
instance:- Define the Append or Delete action using the JavaScript time series API.
-
Create a
PatchOperation
instance and pass it:- The ID of the document to patch
- The document change vector (or
null
) - The
PatchRequest
object
-
Execute the
PatchOperation
operation by callingstore.operations.send
-
NOTE:
- The server treats timestamps passed in the patch request script as UTC, no conversion is applied by the client to local time.
- Appending entries to a time series that doesn't yet exist yet will create the time series.
- No exception is thrown if the specified document does not exist.
Examples
-
In this example, we append a single entry to time series "HeartRates" on the specified document.
const baseTime = new Date(); const patchRequest = new PatchRequest(); // Define the patch request using JavaScript: patchRequest.script = "timeseries(this, $timeseries).append($timestamp, $values, $tag);"; // Provide values for the parameters in the script: patchRequest.values = { timeseries: "HeartRates", timestamp: baseTime.toISOString(), values: 59, tag: "watches/fitbit" }; // Define the patch operation: const patchOp = new PatchOperation("users/john", null, patchRequest); // Execute the operation: await documentStore.operations.send(patchOp);
-
In this example, we append 100 entries to time series "HeartRates" on the specified document.
Timestamps and values are drawn from an array and other arguments are provided in the "values" property.
const baseTime = new Date(); // Create arrays of timestamps and random values to patch const values = []; const timeStamps = []; for (let i = 0; i < 100; i++) { const randomValue = 68 + Math.round(19 * Math.random()); values.push(randomValue); const timeStamp = baseTime.getTime() + 60_000 * i; timeStamps.push(new Date(timeStamp).toISOString()); } const patchRequest = new PatchRequest(); patchRequest.script = ` for (let i = 0; i < $values.length; i++) { timeseries(id(this), $timeseries).append( $timeStamps[i], $values[i], $tag); }`; patchRequest.values = { timeseries: "HeartRates", timeStamps: timeStamps, values: values, tag: "watches/fitbit" }; const patchOp = new PatchOperation("users/john", null, patchRequest); await documentStore.operations.send(patchOp);
-
In this example, we delete a range of 50 entries from time series "HeartRates" on the specified document.
const baseTime = new Date(); const patchRequest = new PatchRequest(); patchRequest.script = "timeseries(this, $timeseries).delete($from, $to);"; patchRequest.values = { timeseries: "HeartRates", from: baseTime.toISOString(), to: new Date(baseTime.getTime() + 60_000 * 49).toISOString() }; const patchOp = new PatchOperation("users/john", null, patchRequest); await documentStore.operations.send(patchOp);
Syntax
-
The detailed syntax of
PatchOperation
is listed under this syntax section. -
The detailed syntax of
PatchRequest
is listed under this syntax section. -
The available JavaScript API methods are detailed in the time series JavaScript support article.
Patch time series data - multiple documents
Usage
-
In order to patch time series data on multiple documents, you need to:
- Define a query that retrieves the set of documents to be patched (can be a dynamic or an index query).
- Define the patching action that will be executed on the matching documents.
-
This is achieved by defining a string, or creating an instance of
IndexQuery
that contains such string,
with the following two parts:- The query: provide an RQL code snippet to filter the documents you want to patch.
- The patching script: use the JavaScript time series API to define the patching action.
-
Create a
PatchByQueryOperation
instance and pass it theIndexQuery
object, or the defined string. -
Execute the
PatchByQueryOperation
by callingstore.operations.send
.- The patch operation will be executed only on documents that match the query.
- This type of operation can be awaited for completion. Learn more in Manage length operations.
-
NOTE:
- The server treats timestamps passed in the patch request script as UTC, no conversion is applied.
- No exception is thrown if any of the documents no longer exist during patching.
Examples
-
In this example, we append an entry to time series "HeartRates" on ALL documents in the "Users" collection.
const indexQuery = new IndexQuery(); // Define the query & patch string: indexQuery.query = ` from users as u update { timeseries(u, $name).append($time, $values, $tag) }`; // Provide values for the parameters in the script: indexQuery.queryParameters = { name: "HeartRates", time: new Date(baseTime.getTime() + 60_000).toISOString(), values: 59, tag: "watches/fitbit" } // Define the patch operation: const patchByQueryOp = new PatchByQueryOperation(indexQuery); // Execute the operation: await documentStore.operations.send(patchByQueryOp);
-
In this example, we delete the "HeartRates" time series from documents that match the query criteria.
const indexQuery = new IndexQuery(); indexQuery.query = ` from users as u where u.age < 30 update { timeseries(u, "HeartRates").delete() }`; const deleteByQueryOp = new PatchByQueryOperation(indexQuery); // Execute the operation: // Time series "HeartRates" will be deleted for all users with age < 30 await documentStore.operations.send(deleteByQueryOp);
-
In this example, for each document in the "Users" collection, we patch a document field with data retrieved from its time series entries.
The document's time series data itself is Not patched.
The documentnumberOfUniqueTagsInTS
field will be updated with the number of unique tags in the user's "HeartRates" time series.
To do this, we use the JavaScript get method to get all the time series entries for each document
and extract each entry's tag.
const indexQuery = new IndexQuery(); indexQuery.query = ` declare function patchDocumentField(doc) { var differentTags = []; var entries = timeseries(doc, $name).get(); for (var i = 0; i < entries.length; i++) { var e = entries[i]; if (e.Tag !== null) { if (!differentTags.includes(e.Tag)) { differentTags.push(e.Tag); } } } doc.numberOfUniqueTagsInTS = differentTags.length; return doc; } from users as u update { put(id(u), patchDocumentField(u)) } `; indexQuery.queryParameters = { name: "HeartRates" } const patchByQueryOp = new PatchByQueryOperation(indexQuery); // Execute the operation and wait for completion: const asyncOp = await documentStore.operations.send(patchByQueryOp); await asyncOp.waitForCompletion();
Syntax
-
The detailed syntax of
PatchByQueryOperation
is listed under this syntax section. -
The available JavaScript API methods are detailed in the time series JavaScript support article.