How to add and delete documents and subdocuments using WOQL

Prerequisites: TerminusDB running on localhost:6363 with the Star Wars dataset cloned. If you haven't done this yet, follow the Explore a Real Dataset tutorial (Steps 1–2), or run:

curlHTTP

RunCopy

curl -u admin:root -X POST http://localhost:6363/api/clone/admin/star-wars \
  -H "Content-Type: application/json" \
  -H "Authorization-Remote: Basic cHVibGljOnB1YmxpYw==" \
  -d '{"remote_url": "https://data.terminusdb.org/public/star-wars", "label": "Star Wars", "comment": "Star Wars dataset"}'

Add a document in WOQL

You can add a document in WOQL using the insert_document keyword.

let v = Vars("id");
insert_document(doc({'@type' : 'Planet', label: 'Planet-X'}), v.id)

We can also add documents by using a variable. For instance, we can create a new planet for each individual in the star wars universe as follows:

let v = Vars("person", "name");
and(isa(v.person, "People"),
    triple(v.person,"label",v.name),
    insert_document(doc({'@type' : 'Planet', label: v.name})))

Create and link a subdocument in WOQL

Subdocuments are linked to their parent document using the @linked-by annotation in insert_document. This tells TerminusDB which parent document owns the subdocument and which property links them.

Simple example for adding a subdocument:

insert_document(
  new doc({
    "@type": "PersonRole",
    "@linked-by": { "@id": "Person/John", "@property": "role" }
  }),
  "v:SubdocumentId"
)

The @linked-by annotation specifies that this subdocument is owned by Person/John via its role property. TerminusDB automatically creates the linking triple when the document is inserted.