Skip to main content

Patching Documents Overview

What is document patching?​

Applications often update a document by loading it from RavenDB, modifying it in client code, and saving the updated document back to the database.

Patching avoids this load-modify-save cycle.
The client sends instructions describing the required change, and RavenDB applies them directly on the server.

Depending on the patching interface, those instructions can:

  • Set or remove fields and modify arrays or dictionaries.
  • Run conditional or computed update logic.
  • Modify metadata or work with related documents.
  • Update counters, time series, and attachments.
  • Apply the same transformation to multiple documents selected by an RQL query.

Patching is therefore useful for targeted changes to a known document and for bulk transformations,
especially when loading every affected document would add unnecessary network traffic and client-side work.

Choose a patching approach​

First decide whether to patch one document or multiple documents, and then choose how to express the update:

  • Goal:
    Queue common changes to one document together with other session work

  • Use:
    Session patch methods such as Patch, Increment, AddOrPatch, and AddOrIncrement.

  • How it works:
    The patch is queued in the session and sent with the rest of the session's changes when SaveChanges() is called.

  • Learn more:
    Patch a Single Document: API Overview,
    Examples: Fields and Arrays

  • Goal:
    Run flexible or custom logic on one document

  • Use:
    A JavaScript PatchRequest, sent as PatchCommandData through Session.Advanced.Defer or as a PatchOperation.

  • How it works:
    The script can use conditionals, loops, calculations, and RavenDB's predefined JavaScript functions.

  • Learn more:
    Patch a Single Document: API Overview,
    Examples: Advanced Scripts

  • Goal:
    Send an RFC 6902 JSON Patch to one document from the .NET client

  • Use:
    JsonPatchOperation.

  • How it works:
    A JSON Patch document contains an ordered list of add, remove, replace, copy, move, and test operations.

  • Learn more:
    Patch a Single Document Using JSON Patch

  • Goal:
    Update multiple documents selected by a collection, query, or index

  • Use:
    PatchByQueryOperation.

  • How it works:
    An RQL query selects the documents and a JavaScript update clause defines the change.

  • Learn more:
    Patch Multiple Documents Using the Client API

  • Goal:
    Build, test, and run a set-based patch interactively

  • Use:
    The Studio Patch View.

  • How it works:
    Studio previews the effect on a selected document before running the set-based patch operation.

  • Learn more:
    Patch Multiple Documents Using Studio

JSON Patch behavior in the .NET session API​

JSON Patch is currently supported only by the .NET client.

With the default SessionPatchBehavior.JsonPatch convention, the client generates JSON Patch commands for supported typed Session.Advanced.Patch calls. If a change cannot be represented as JSON Patch, the client uses a JavaScript patch instead.

To make all .NET session patch methods use JavaScript, set the SessionPatchBehavior convention to SessionPatchBehavior.JavaScript.

See Patch a Single Document: API Overview for the supported operations, fallback behavior, and removal semantics.

Execution and transaction boundaries​

The transaction boundary depends on how the patch is sent:

Session batch​

Session patch methods and PatchCommandData registered through Session.Advanced.Defer are sent when SaveChanges() is called.

They execute with all other changes in the session batch in one ACID transaction.
Either the entire batch succeeds or none of its changes are persisted.

Direct single-document operation​

PatchOperation and JsonPatchOperation are sent immediately through the Operations API.

Each request executes in one write transaction.
The operations in a JsonPatchDocument are applied in order and all-or-nothing.

Set-based patch operation​

PatchByQueryOperation and Studio patches run as background server operations.

Matching documents are processed in batches of 1,024, with each batch committed in a separate write transaction.
The complete operation is therefore not one all-or-nothing transaction.

Do not rely on documents created after the operation starts being included.
The operation does not hold a snapshot of document contents for its entire duration.
RavenDB performs no per-document concurrency checks, so a selected document can be modified or deleted before its batch is processed.
If the document still exists, the patch is applied to its current version.

By default, a query-based patch will not run against stale index results.
Set AllowStale to patch stale results, or set StaleTimeout to wait for the index to become non-stale.

Where to go next​

In this article