Skip to main content

Single-Document Patching Examples: Counters, Time Series, and Attachments

C#JavaPythonNode.js

Patching examples​

Increment counter​

Use incrementCounter to add a value to a counter.
If the counter does not exist, RavenDB creates it with the supplied value.

// Add 20 to Likes on orders/1-A.
// If Likes does not exist, RavenDB creates it with the value 20.
session.Advanced.Defer(new PatchCommandData(
    id: "orders/1-A",
    changeVector: null,
    patch: new PatchRequest
    {
        Script = "incrementCounter(this, args.name, args.value);",
        Values =
        {
            { "name", "Likes" },
            { "value", 20 }
        }
    },
    patchIfMissing: null));

session.SaveChanges();

incrementCounter accepts either a document ID or a document object in the patch script.
Omit the value to increment by 1; pass a negative value to decrement the counter.

Delete counter​

Use deleteCounter to delete a counter from a document.

// Delete the Likes counter from products/1-A.
session.Advanced.Defer(new PatchCommandData(
    id: "products/1-A",
    changeVector: null,
    patch: new PatchRequest
    {
        Script = "deleteCounter(this, args.name);",
        Values =
        {
            { "name", "Likes" }
        }
    },
    patchIfMissing: null));

session.SaveChanges();

deleteCounter accepts either a document ID or a document object in the patch script.

Get counter​

Use counter to read a counter value while a patch script is running.
The following example stores the current Likes value in a regular document field named LikesSnapshot.

// Read Likes from orders/1-A and store its current value in LikesSnapshot.
session.Advanced.Defer(new PatchCommandData(
    id: "orders/1-A",
    changeVector: null,
    patch: new PatchRequest
    {
        Script = "this.LikesSnapshot = counter(this, args.name);",
        Values =
        {
            { "name", "Likes" }
        }
    },
    patchIfMissing: null));

session.SaveChanges();

counter accepts either a document ID or a document object in the patch script.
It returns null if the specified counter does not exist.

Append time series entry​

Use timeseries(...).append to append an entry to a time series.

// Append a one-value HeartRates entry to users/1-A.
// RavenDB treats timestamps passed to patch scripts as UTC.
session.Advanced.Defer(new PatchCommandData(
    id: "users/1-A",
    changeVector: null,
    patch: new PatchRequest
    {
        Script = "timeseries(this, args.name).append(new Date(args.timestamp), args.values, args.tag);",
        Values =
        {
            { "name", "HeartRates" },
            { "timestamp", DateTime.UtcNow },
            // Pass an array instead when the entry contains multiple values.
            { "values", 78 },
            { "tag", "watches/fitbit" }
        }
    },
    patchIfMissing: null));

session.SaveChanges();

Provide the entry's timestamp, one numeric value or an array of numeric values, and an optional tag.
Learn more about appending time series entries via patching in Patch time series entries,
and see the available time series patch methods in Time series: JavaScript support.

Delete time series entries​

Use timeseries(...).delete to delete a range of time series entries.

// Delete HeartRates entries from the last hour, including both boundaries.
var to = DateTime.UtcNow;
var from = to.AddHours(-1);

session.Advanced.Defer(new PatchCommandData(
    id: "users/1-A",
    changeVector: null,
    patch: new PatchRequest
    {
        Script = "timeseries(this, args.name).delete(args.from, args.to);",
        Values =
        {
            { "name", "HeartRates" },
            { "from", from },
            { "to", to }
        }
    },
    patchIfMissing: null));

session.SaveChanges();

All entries within the specified range, including entries at the from and to timestamps, are removed.
Learn more about deleting time series entries via patching in Patch time series entries.

Delete attachment​

Use attachments(...).delete to delete an attachment from the document being patched.

// Delete invoice.pdf from orders/1-A.
session.Advanced.Defer(new PatchCommandData(
    id: "orders/1-A",
    changeVector: null,
    patch: new PatchRequest
    {
        Script = "attachments(this, args.name).delete();",
        Values =
        {
            { "name", "invoice.pdf" }
        }
    },
    patchIfMissing: null));

session.SaveChanges();

Learn more about deleting attachments in Delete an attachment,
and see the full patch method syntax in JavaScript engine - Attachment operations.

Copy attachment​

Use attachments(...).copyFrom to copy an attachment from a source document to the document being patched.
The copy is performed entirely on the server, without downloading and re-uploading the attachment through the client.

// Copy orders/2-A/invoice.pdf to orders/1-A as invoice-copy.pdf.
session.Advanced.Defer(new PatchCommandData(
    id: "orders/1-A",
    changeVector: null,
    patch: new PatchRequest
    {
        Script = "attachments(this, args.targetName).copyFrom(args.sourceDocId, args.sourceName);",
        Values =
        {
            { "sourceDocId", "orders/2-A" },
            { "sourceName", "invoice.pdf" },
            { "targetName", "invoice-copy.pdf" }
        }
    },
    patchIfMissing: null));

session.SaveChanges();

The copyFrom method returns true on success and false if the source document, target document, or source attachment was not found.

Learn more about copying attachments in Copy attachments - via patching,
and see the full patch method syntax in JavaScript engine - Attachment operations.

Mark attachment as remote​

Use attachments(...).remote to schedule an existing local attachment for upload to a configured remote storage destination.
Provide the attachment name, destination identifier, and scheduled upload time.

// Schedule orders/1-A/invoice.pdf for remote upload in one day.
session.Advanced.Defer(new PatchCommandData(
    id: "orders/1-A",
    changeVector: null,
    patch: new PatchRequest
    {
        Script = "attachments(this, args.name).remote(args.identifier, args.at);",
        Values =
        {
            { "name", "invoice.pdf" },
            // Must match a configured remote destination identifier.
            { "identifier", "my-amazon-storage" },
            { "at", DateTime.UtcNow.AddDays(1) }
        }
    },
    patchIfMissing: null));

session.SaveChanges();

This schedules the attachment for remote upload; it does not upload the attachment immediately.
If the Remote Attachments feature and the selected destination are enabled, a background task uploads the attachment during a scan after the scheduled time has passed.

Learn more in Schedule existing attachments for remote upload,
and see how to define destinations in Configure remote attachments.

In this article