Explore a Real Dataset — Star Wars Tutorial

Clone a pre-populated Star Wars database to your local TerminusDB instance and explore it with queries, branches, and diffs — in 15 minutes. This tutorial focuses on querying relationships across documents — something the 10 Minute quickstart does not cover.

What you will build

You will clone a complete Star Wars database (characters, films, planets, starships, species) from a public server, run queries that traverse document relationships, create a speculative branch ("what if Anakin turned to the Dark Side?"), and see a field-level structural diff of your changes.

Step 1 — Clone the Star Wars database

Pull the entire Star Wars dataset from the public templates server to your local instance:

You just pulled a complete Star Wars database — characters, films, planets, starships — from a public TerminusDB server to your local instance. No account needed, no sign-up, no credentials. The data is now yours to query, branch, and modify.

Step 2 — Explore what you have

List the document types defined in the schema:

Loading…

The response lists 4 document types — Film, Person, Planet, and Species.

List the first few characters:

Loading…

You see 5 Person documents (limited by count=5). The database has 20 characters total, plus films, planets, and species. All of Star Wars, versioned and queryable. Let's ask it some questions.

Step 3 — Query the data

Which characters appear in "A New Hope" (Episode IV)?

In a relational database, you would write a JOIN across a junction table: SELECT c.name FROM characters c JOIN film_characters fc ON ... JOIN films f ON ... WHERE f.title = 'A New Hope'. In TerminusDB, documents link directly to other documents — a Film has a characters property that points to Person documents. You traverse the link, not a junction table:

Loading…

Expected output includes character names: Luke Skywalker, Leia Organa, Han Solo, Obi-Wan Kenobi, Chewbacca, R2-D2, C-3PO, and more (17 characters total).

Notice what happened: the query says "find a Film with this title, follow its characters link to Person documents, then get their name." Three hops through the graph — Film → characters → Person → name. No junction tables, no foreign key declarations, no JOINs. The relationships are part of the data structure itself, and traversing them is how you query.

Step 4 — Branch and modify

What if Anakin Skywalker had turned to the Dark Side? Let's update his record on a branch and see what TerminusDB tracks.

Create a branch called what-if:

Loading…

{
  "@type": "api:BranchResponse",
  "api:status": "api:success"
}

Now modify Anakin Skywalker's record on the branch — rewriting him as if he fell to the Dark Side. First, fetch his full document:

Loading…

Now change four fields to tell the Dark Side story and PUT the modified document back:

• "eye_color": "blue" → "yellow"
• "mass": 84 → 120
• "side": "Light Side" → "Dark Side"
• "faction": "Jedi Order" → "Sith Order"

Loading…

[
  "terminusdb:///data/Person/Anakin%20Skywalker"
]

You just rewrote history — on a branch. Main still has Anakin Skywalker (blue eyes, Light Side, mass 84, Jedi Order). Your what-if branch has him turned Dark (yellow eyes, Dark Side, mass 120, Sith Order). The @id stays the same (Person/Anakin%20Skywalker) — TerminusDB tracks object identity through changes, not content. Let's see exactly what changed.

Step 5 — See what changed (the diff)

This is the moment. In any other database, answering "what changed between these two versions?" means writing audit triggers, maintaining changelog tables, or exporting both states and diffing them externally. In TerminusDB, you ask the database directly:

Loading…

[
  {
    "@id": "Person/Anakin%20Skywalker",
    "eye_color": {
      "@op": "SwapValue",
      "@before": "blue",
      "@after": "yellow"
    },
    "faction": {
      "@op": "SwapValue",
      "@before": "Jedi Order",
      "@after": "Sith Order"
    },
    "mass": {
      "@op": "SwapValue",
      "@before": 84,
      "@after": 120
    },
    "quote": {
      "@op": "SwapValue",
      "@before": "This is where the fun begins.",
      "@after": "You underestimate my power!"
    },
    "side": {
      "@op": "SwapValue",
      "@before": "Light Side",
      "@after": "Dark Side"
    }
  }
]

This diff is structural, not textual. TerminusDB is not comparing strings line by line — it knows the document schema, understands which field changed, what the old value was, and what the new value is. Each change is a typed operation (SwapValue) that can be applied, reversed, or composed with other patches programmatically.

You sent a full document replacement, but TerminusDB detected only the five fields that actually changed: eye_color, faction, mass, quote, and side. Compare this to the alternative: export both database states as JSON, run a generic diff tool, then parse the text output to figure out what actually changed. Or maintain an audit table with triggers that fire on every update. Or write custom comparison logic in your application.

TerminusDB replaces all of that with one API call. The database is the version history — diffs are a native operation, not an afterthought bolted on top.

Clean up

Loading…

What you just did

In 15 minutes, you:

1. Cloned a complete Star Wars database from a public server — one command, no account
2. Queried relationships across documents (films → characters) using WOQL
3. Branched the database and made a speculative change ("what if Anakin turned to the Dark Side?")
4. Diffed the branch against main and saw field-level structural changes

These four operations — clone, query, branch, diff — are the core of TerminusDB. Every operation you just ran works at any scale: 20 documents or 2 million.

Next steps

• Merge your branch back to main — complete the git-for-data cycle
• Write your own schema — add validation and type safety
• Time-travel to previous commits — view any previous state of your database
• WOQL query language — learn the full query language
• Connect with TypeScript — use the SDK in your application