Patch Time Series Operations

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 calling store.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.

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

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.

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 the IndexQuery object, or the defined string.

Execute the PatchByQueryOperation by calling store.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.

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

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.