Patch Endpoint — Apply Structural Patches to Documents

The endpoint at data.terminusdb.org is for non-production and exploratory use only. It is deployed with very limited memory to prevent abuse and is provided without any guarantees whatsoever. Do not rely on it for production applications. Availability is not guaranteed.

Example database

Connect to TerminusDB first.

TerminusDB provides two patch operations for applying structural changes to documents:

patch — Apply a patch to a specific document you supply (client-side before + patch)
patchResource — Apply patches to documents already stored in a branch (server-side, by @id)

Both use the same patch format produced by TerminusDB's diff operations.

Patch a single document

Use client.patch(before, patch) when you have the original document and a patch object. TerminusDB applies the patch and returns the result — no database write occurs.

Example: JavaScript

const before = {
  "@id": "Person/Jane",
  "@type": "Person",
  name: "Jane",
}

const patch = {
  name: { "@op": "SwapValue", "@before": "Jane", "@after": "Janine" },
}

const result = await client.patch(before, patch)
console.log(result)
// { "@id": "Person/Jane", "@type": "Person", "name": "Janine" }

This is useful for previewing what a patch would produce before committing it to a branch.

Patch documents in a branch

Use client.patchResource(patch, message) to apply patches directly to documents stored in the current branch. Each patch object must include an @id field identifying the target document.

Patch format

Supply an array of patch objects, each with @id set to the document to modify:

Example: JSON

[
  {
    "@id": "Obj/id1",
    "name": {
      "@op": "SwapValue",
      "@before": "foo",
      "@after": "bar"
    }
  },
  {
    "@id": "Obj/id2",
    "name": {
      "@op": "SwapValue",
      "@before": "foo",
      "@after": "bar"
    }
  }
]

Apply the patch

Example: JavaScript

client.db("tdb-example-mydb")
client.checkout("mybranch")

const patch = [
  {
    "@id": "Obj/id1",
    "name": { "@op": "SwapValue", "@before": "foo", "@after": "bar" },
  },
  {
    "@id": "Obj/id2",
    "name": { "@op": "SwapValue", "@before": "foo", "@after": "bar" },
  },
]

const patchResult = await client.patchResource(patch, "apply patch to mybranch")
console.log(patchResult)
// ["Obj/id1", "Obj/id2"]

Conflict errors

If a patch cannot be applied (for example, the @before value does not match the current document state), TerminusDB returns a 409 Conflict response: