Quickstart

We’re overhauling Dgraph’s docs to make them clearer and more approachable. If you notice any issues during this transition or have suggestions, please let us know.

In this Dgraph quick start guide we walk through creating a graph, inserting data, and querying the graph using DQL.

This guide helps you to understand how to:

• Create a new Dgraph graph
• Connect your graph to the Ratel web client
• Add data using mutations
• Query the graph using DQL
• Update the graph schema to support more advanced queries

Run Dgraph and connect the Ratel web UI

The easiest way to get Dgraph up and running in the cloud is using Dgraph on Hypermode. If you prefer a local development experience with Dgraph we recommend using the official Dgraph Docker image. Both options are described below.

In this section we’ll create a new graph, then we’ll connect our new graph to Ratel, the web-based UI for Dgraph.

On Hypermode

1. Sign in to Hypermode and create your workspace

   Open hypermode.com/login in your web browser and sign in to Hypermode to create your account.

   After signing in you’ll be prompted to choose a name for your workspace.

   

   Enter a name for your workspace and then select Create workspace.

2. Create your graph

   After creating your Hypermode workspace you’ll be prompted to create your first graph.

   

   Enter a name for your graph and choose the hosting location, then select Create graph.

3. View your graph details

   Once your graph is created you’ll see the graph details including its status, connection string, and API key.

   

   We’ll use the Dgraph connection string and the API key to connect to our graph via Dgraph clients such as Ratel or language SDKs.

   Click on the copy icon next to the connection string to copy the Dgraph connection string.

4. Connect the Ratel graph client

   Ratel is a web-based Dgraph client for interacting with your graph. We’ll use Ratel to execute DQL queries and update the graph schema.

   Navigate to ratel.hypermode.com and paste the Dgraph connection string you copied in the previous step into the “Dgraph Conn String” text box in Ratel then select Connect to verify the connection and then select Continue to access the Ratel console.

   

   The Ratel console is where we can execute DQL queries and mutations and view the results of these operations, including visualizing graph data.

   

   Now we’re ready to add data to our graph.

Add data to the graph with a mutation

Graph databases like Dgraph use a data model called the property graph, which consists of nodes, relationships that connect nodes, and key-value pair properties that describe nodes and relationships.

With Dgraph, we use triples to describe each piece of our graph, which when combined together make up our property graph. Triples are composed of a subject, predicate, and object.

<subject> <predicate> <object> .

The subject always refers to a node, predicates can be a relationship or property, and the object can be a node or property value. You can read more about triples in the RDF section of the docs, but for now let’s move on to creating data in Dgraph using triples.

Let’s create data about movies, characters, and their genres. Here’s the property graph representation of the data we’ll create:

1. Add mutation in Ratel

   The create, update, and delete operations in Dgraph are called mutations.

   In the Ratel Console page, select the Mutate tab, then paste the following mutation:

   {
     set {
   
       _:scifi <dgraph.type> "Genre" .
       _:scifi <Genre.name> "Sci-Fi" .
   
       _:starwars <dgraph.type> "Movie" .
       _:starwars <Movie.title> "Star Wars: Episode IV - A New Hope" .
       _:starwars <Movie.release_date> "1977-05-25"^^<xs:dateTime> .
   
   
       _:startrek <dgraph.type> "Movie" .
       _:startrek <Movie.title> "Star Trek: The Motion Picture" .
       _:startrek <Movie.release_date> "1979-12-07"^^<xs:dateTime> .
   
       _:george <dgraph.type> "Person" .
       _:george <Person.name> "George Lucas" .
   
       _:luke <dgraph.type> "Character" .
       _:luke <Character.name> "Luke Skywalker" .
   
       _:leia <dgraph.type> "Character" .
       _:leia <Character.name> "Princess Leia" .
   
       _:han <dgraph.type> "Character" .
       _:han <Character.name> "Han Solo" .
   
       _:starwars <Movie.genre> _:scifi .
       _:startrek <Movie.genre> _:scifi .
   
       _:starwars <Movie.director> _:george .
   
       _:starwars <Movie.character> _:luke .
       _:starwars <Movie.character> _:leia .
       _:starwars <Movie.character> _:han .
   
     }
   }
   

   The preceding DQL mutation uses N-Quad RDF format to define the triples that make up the property graph we want to create.

2. View mutation results

   Select Run to execute the mutation. In the JSON tab we can see the result of this mutation.

   {
     "data": {
       "code": "Success",
       "message": "Done",
       "queries": null,
       "uids": {
         "george": "0x4",
         "han": "0x7",
         "leia": "0x6",
         "luke": "0x5",
         "scifi": "0x1",
         "startrek": "0x3",
         "starwars": "0x2"
       }
     }
   }
   

   Dgraph displays the universal identifiers (UID) of the nodes that were created.

Query the graph

1. Query for all movies

   In the Console page, select the Query tab and run this query:

   {
     movies(func: type(Movie)) {
       Movie.title
       Movie.genre {
         Genre.name
       }
       Movie.director {
         Person.name
       }
       Movie.character {
         Character.name
       }
     }
   }
   

   This query searches for all Movie nodes as the start of the traversal using the type(Movie) function to define the starting point of our query traversal, then finds any genres, directors, and characters connected to each movie.

2. View results in JSON and graph visualization

   In Ratel’s JSON tab we can view the results of this query as JSON:

   {
     "data": {
       "movies": [
         {
           "Movie.title": "Star Wars: Episode IV - A New Hope",
           "Movie.genre": [
             {
               "Genre.name": "Sci-Fi"
             }
           ],
           "Movie.director": [
             {
               "Person.name": "George Lucas"
             }
           ],
           "Movie.character": [
             {
               "Character.name": "Luke Skywalker"
             },
             {
               "Character.name": "Princess Leia"
             },
             {
               "Character.name": "Han Solo"
             }
           ]
         },
         {
           "Movie.title": "Star Trek: The Motion Picture",
           "Movie.genre": [
             {
               "Genre.name": "Sci-Fi"
             }
           ]
         }
       ]
     }
   }
   

   In the response panel, Select Graph to view a graph visualization of the results of our query:

   

Update the graph schema and query using an index

The previous query used the type() function to find the starting point of our graph traversal. We can use more complex functions to filter by string comparison operator, and others, however to use these function we must first update the graph schema to create an index on the predicates we want to use in these functions.

The function documentation specifies which kind of index is needed for each function.

We’ll use Ratel to alter the schema to add indexes on some of the data so queries can use term matching, filtering, and sorting.

1. Create an index for movie title

   In Ratel’s Schema page, select Predicates. Here we can see all the predicates used in the graph. A predicate is Dgraph’s internal representation of a node, property, or relationship.

   Select the Movie.title predicate. Ratel displays details about the predicate type and indexes.

   Change the type to string then select index and select term for the Movie.title predicate, then select Update to apply the index.

   

2. Create an index for movie release date

   Next, we’ll create an index for the Movie.release_date predicate.

   Select the Movie.release_date predicate. Change the type to dateTime. Select index and choose year for the index tokenizer. Click Update to apply the index on the release-date predicate.

   

3. Query using indexes

   Now let’s find all movies with the term “Star” in their title and released before 1979.

   In the Console page select the Query tab and run this query:

   {
     movieSearch(func: allofterms(Movie.title, "Star"), orderasc: Movie.release_date) @filter(lt(Movie.release_date, "1979")) {
       Movie.title
       Movie.release_date
       Movie.director {
       Person.name
       }
       Movie.character (orderasc: Character.name) {
       Character.name
       }
     }
   }
   

   We can see the JSON result in the JSON tab:

   {
     "data": {
       "movieSearch": [
         {
           "Movie.title": "Star Wars: Episode IV - A New Hope",
           "Movie.release_date": "1977-05-25T00:00:00Z",
           "Movie.director": [
             {
               "Person.name": "George Lucas"
             }
           ],
           "Movie.character": [
             {
               "Character.name": "Han Solo"
             },
             {
               "Character.name": "Luke Skywalker"
             },
             {
               "Character.name": "Princess Leia"
             }
           ]
         }
       ]
     }
   }
   

   And also view the graph visualization of the result in the Graph tab:

   

   Try changing the release date and the search terms conditions to see Dgraph search and filtering in action.

Reverse relationship query

1. Add reverse relationship

   In the previous queries we traversed from the movie node to its connected genre node, but what if we want to find all movies connected to a genre node? In order to traverse from a genre node to a movie node we need to explicitly define the Movie.genre predicate as a reverse relationship.

   To define a reverse relationship for the Movie.genre predicate we’ll return to the Schema page in Ratel, select the Movie.genre predicate and toggle the reverse checkbox. Then select Update to apply this schema change.

   

2. Query using the reverse relationship

   In a DQL query the ~ operator is used to specify a reverse relationship. To traverse from a genre node to a movie node we use the syntax ~Movie.genre.

   In this query we find all movies connected to the “Sci-Fi” genre:

   {
     genreSearch(func: type(Genre)) {
       Genre.name
       movies: ~Movie.genre {
         Movie.title
       }
     }
   }
   

   Note that we can also alias the field name to “movies” in our result JSON using the syntax movies: ~Movie.genre.

   {
     "data": {
       "genreSearch": [
         {
           "Genre.name": "Sci-Fi",
           "movies": [
             {
               "Movie.title": "Star Wars: Episode IV - A New Hope"
             },
             {
               "Movie.title": "Star Trek: The Motion Picture"
             }
           ]
         }
       ]
     }
   

In this quick start we created a new graph instance using Dgraph on Hypermode, added data, queried the graph, visualized the results, and updated the schema of our graph.

Where to go from here

• Learn more about using DQL to query your graph.
• Go to Clients to see how to communicate with Dgraph from your app.
• Learn how to build intelligent applications using Dgraph and Modus such as natural language search.

Need help

• Join the Hypermode Discord server for questions, issues, feature requests, and discussions.