Learn the GraphQL Basics for TerminusDB

This guide teaches you the basics of querying TerminusDB with GraphQL. You will learn how to write queries, select fields, and traverse document relationships — all using a Star Wars dataset as a worked example.

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"}'

You can run GraphQL queries against your local instance at http://localhost:6363/api/graphql/admin/star-wars.

Now you have two panels, one on the left for query, and one on the right for results.

Entering a query

First type query{ into the query panel. It should look like this:

query{
   █
}

If at the cursor point you type: Ctrl-c you'll get a list of options you can choose from. These options are legal GraphQL syntax according to your provided schema. Let's search for people from the Star Wars universe.

query{
   People{
      label
   }
}

The label property in this schema, supplies the name of the person we are interested in. Of course this query might give us a bit too much, so let us also limit it.

query{
   People(limit: 5){
      label
   }
}

This should result in:

{
  "data": {
    "People": [
      {
        "label": "Luke Skywalker"
      },
      {
        "label": "Obi-Wan Kenobi"
      },
      {
        "label": "Anakin Skywalker"
      },
      {
        "label": "Wilhuff Tarkin"
      },
      {
        "label": "Chewbacca"
      }
    ]
  }
}

To get more fields in our query, we can just add words, using Ctrl-c if we are stuck for names of fields.

query{
   People(limit: 5){
      label
   }
}

When following links to other objects, we have to embed a query inside our query. So, for instance, if we want to know the homeworld that each of these people come from we can write:

query{
   People(limit: 2){
      label
      homeworld{
        label
      }
   }
}

This will get us:

{
  "data": {
    "People": [
      {
        "label": "Luke Skywalker",
        "homeworld": {
          "label": "Tatooine"
        }
      },
      {
        "label": "Obi-Wan Kenobi",
        "homeworld": {
          "label": "Stewjon"
        }
      }
    ]
  }
}

Paging

If we want to page the results, we can also add an offset to our query, and we'll get the next results.

query{
   People(limit: 2, offset:2){
      label
      homeworld{
        label
      }
   }
}

And now we get two more:

{
  "data": {
    "People": [
      {
        "label": "Anakin Skywalker",
        "homeworld": {
          "label": "Tatooine"
        }
      },
      {
        "label": "Wilhuff Tarkin",
        "homeworld": {
          "label": "Eriadu"
        }
      }
    ]
  }
}

Next steps

• Filter results — use _filter arguments to narrow queries
• GraphQL mutations — insert, replace, and delete documents via GraphQL
• Path queries in GraphQL — traverse relationships across document types
• Connect with Apollo Client — integrate TerminusDB GraphQL into a JavaScript application
• GraphQL query reference — full reference for types, arguments, and fields