You are looking at a doc for older version of Dgraph (v0.7.6). The latest version is v0.8.2.
Report Issue Edit Page

Get Started

New to Dgraph? Here’s a 5 step tutorial to get you up and running.

logo Wiki Build Status Coverage Status Go Report Card Slack Status

Step 1: Installation

System Installation

You could simply install the binaries with

curl https://get.dgraph.io -sSf | bash

That script would automatically install Dgraph for you. Once done, you can jump straight to step 2.

Alternative: To mitigate potential security risks, you could instead do this:

curl https://get.dgraph.io > /tmp/get.sh
vim /tmp/get.sh  # Inspect the script
sh /tmp/get.sh   # Execute the script

Docker Image Installation

You may pull our Docker images from here. From terminal, just type:

docker pull dgraph/dgraph

Step 2: Run Dgraph

Using System Installation

Follow this command to run Dgraph:

dgraph

Using Docker

Tip

If you want to persist the data while you play with Dgraph, you should mount the dgraph volume, using the -v flag.

Map to default port (8080)

mkdir -p ~/dgraph
docker run -it -p 8080:8080 -v ~/dgraph:/dgraph dgraph/dgraph dgraph --bindall=true

Map to custom port

mkdir -p ~/dgraph
# Mapping port 8080 from within the container to 9090  of the instance
docker run -it -p 9090:8080 -v ~/dgraph:/dgraph dgraph/dgraph dgraph --bindall=true
Note The dgraph server listens on port 8080 (unless you have mapped to another port above) with log output to the terminal.

Step 3: Run some queries

Tip From v0.7.3, a user interface is available at http://localhost:8080 from the browser to run mutations and visualise results from the queries.

Lets do a mutation which stores information about the first three releases of the the “Star Wars” series and one of the “Star Trek” movies.

curl localhost:8080/query -XPOST -d $'
mutation {
  set {
   _:luke <name> "Luke Skywalker" .
   _:leia <name> "Princess Leia" .
   _:han <name> "Han Solo" .
   _:lucas <name> "George Lucas" .
   _:irvin <name> "Irvin Kernshner" .
   _:richard <name> "Richard Marquand" .

   _:sw1 <name> "Star Wars: Episode IV - A New Hope" .
   _:sw1 <release_date> "1977-05-25" .
   _:sw1 <revenue> "775000000" .
   _:sw1 <running_time> "121" .
   _:sw1 <starring> _:luke .
   _:sw1 <starring> _:leia .
   _:sw1 <starring> _:han .
   _:sw1 <director> _:lucas .

   _:sw2 <name> "Star Wars: Episode V - The Empire Strikes Back" .
   _:sw2 <release_date> "1980-05-21" .
   _:sw2 <revenue> "534000000" .
   _:sw2 <running_time> "124" .
   _:sw2 <starring> _:luke .
   _:sw2 <starring> _:leia .
   _:sw2 <starring> _:han .
   _:sw2 <director> _:irvin .

   _:sw3 <name> "Star Wars: Episode VI - Return of the Jedi" .
   _:sw3 <release_date> "1983-05-25" .
   _:sw3 <revenue> "572000000" .
   _:sw3 <running_time> "131" .
   _:sw3 <starring> _:luke .
   _:sw3 <starring> _:leia .
   _:sw3 <starring> _:han .
   _:sw3 <director> _:richard .

   _:st1 <name> "Star Trek: The Motion Picture" .
   _:st1 <release_date> "1979-12-07" .
   _:st1 <revenue> "139000000" .
   _:st1 <running_time> "132" .
  }
}' | python -m json.tool | less

Lets add a schema so that we can perform some interesting queries with term matching, filtering and sorting.

curl localhost:8080/query -XPOST -d $'
mutation {
  schema {
    name: string @index .
    release_date: date @index .
    revenue: float .
    running_time: int .
  }
}' | python -m json.tool | less

Now lets get the movies (and their associated information) starting with “Star Wars” and which were released after “1980”.

curl localhost:8080/query -XPOST -d $'{
  me(func:allofterms(name, "Star Wars")) @filter(ge(release_date, "1980")) {
    name
    release_date
    revenue
    running_time
    director {
     name
    }
    starring {
     name
    }
  }
}' | python -m json.tool | less

Output

{
    "me": [
        {
            "director": [
                {
                    "name": "Irvin Kernshner"
                }
            ],
            "name": "Star Wars: Episode V - The Empire Strikes Back",
            "release_date": "1980-05-21",
            "revenue": 534000000.0,
            "running_time": 124,
            "starring": [
                {
                    "name": "Han Solo"
                },
                {
                    "name": "Princess Leia"
                },
                {
                    "name": "Luke Skywalker"
                }
            ]
        },
        {
            "director": [
                {
                    "name": "Richard Marquand"
                }
            ],
            "name": "Star Wars: Episode VI - Return of the Jedi",
            "release_date": "1983-05-25",
            "revenue": 572000000.0,
            "running_time": 131,
            "starring": [
                {
                    "name": "Han Solo"
                },
                {
                    "name": "Princess Leia"
                },
                {
                    "name": "Luke Skywalker"
                }
            ]
        }
    ]
}

Step 4: Advanced Queries on a larger dataset

Note Step 4 and 5 are optional. If you’d like to experiment with a larger dataset and explore more functionality, this section is for you.

Download dataset

First, download the goldendata.rdf.gz dataset from here (download). Put it in ~/dgraph directory, creating it if necessary using mkdir ~/dgraph.

mkdir -p ~/dgraph
cd ~/dgraph
wget "https://github.com/dgraph-io/benchmarks/blob/master/data/goldendata.rdf.gz?raw=true" -O goldendata.rdf.gz -q

Load dataset

Assuming that Dgraph is running as mentioned in Step 2.

Lets add a type for initial_release_date which is a new predicate that we will be loading. Note the name predicate is already indexed from the previous step.

curl localhost:8080/query -XPOST -d '
mutation {
  schema {
    initial_release_date: date @index .
  }
}'

Now lets load the golden dataset that you previously downloaded by running the following in another terminal:

cd ~/dgraph # The directory where you downloaded the rdf.gz file.
dgraphloader -r goldendata.rdf.gz

Output

Processing goldendata.rdf.gz
Number of mutations run   : 1121
Number of RDFs processed  : 1120879
Time spent                : MMmSS.FFFFFFFFs
RDFs processed per second : XXXXX
Tip Your counts should be the same, but your statistics will vary.

Step 5: Run some queries

Tip From v0.7.3, a user interface is available at http://localhost:8080 from the browser to run mutations and visualise results from the queries.

Movies by Steven Spielberg

Let’s now find all the entities named “Steven Spielberg” and the movies directed by them.

Editing query...
{
  director(func:allofterms(name, "steven spielberg")) {
    [email protected]
    director.film (orderdesc: initial_release_date) {
      [email protected]
      initial_release_date
    }
  }
}
curl localhost:8080/query -XPOST -d '
{
  director(func:allofterms(name, "steven spielberg")) {
    [email protected]
    director.film (orderdesc: initial_release_date) {
      [email protected]
      initial_release_date
    }
  }
}' | python -m json.tool | less
package main

import (
  "context"
  "flag"
  "fmt"
  "io/ioutil"
  "log"
  "os"

  "github.com/dgraph-io/dgraph/client"
  "github.com/gogo/protobuf/proto"
  "google.golang.org/grpc"
)

var (
  dgraph = flag.String("d", "127.0.0.1:9080", "Dgraph server address")
)

func main() {
  flag.Parse()
  conn, err := grpc.Dial(*dgraph, grpc.WithInsecure())
  if err != nil {
    log.Fatal(err)
  }
  defer conn.Close()

  // The Dgraph client needs a directory in which to write its blank node maps.
  clientDir, err := ioutil.TempDir("", "client_")
  if err != nil {
    log.Fatal(err)
  }
  defer os.RemoveAll(clientDir)

  dgraphClient := client.NewDgraphClient([]*grpc.ClientConn{conn}, client.DefaultOptions, clientDir)
  defer dgraphClient.Close()

  req := client.Req{}
  req.SetQuery(`blahblah`)

  resp, err := dgraphClient.Run(context.Background(), &req)
  if err != nil {
    log.Fatalf("Error in getting response from server, %s", err)
  }
  fmt.Printf("Response %+v\n", proto.MarshalTextString(resp))
}
package main

import (
  "bytes"
  "flag"
  "io/ioutil"
  "log"
  "net/http"
)

var (
  baseURL = flag.String("d", "http://127.0.0.1:8080/query", "Dgraph server address")
)

func main() {
  client := &http.Client{}
  body := bytes.NewBufferString(`{
  director(func:allofterms(name, "steven spielberg")) {
    [email protected]
    director.film (orderdesc: initial_release_date) {
      [email protected]
      initial_release_date
    }
  }
}`)
  req, err := http.NewRequest("POST", *baseURL, body)
  if err != nil {
    log.Fatal(err)
    return
  }

  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
    return
  }
  defer resp.Body.Close()

  responseData, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
    return
  }

  log.Printf("Response %+v\n", string(responseData))
}
Response

This query will return all the movies by the popular director Steven Spielberg, sorted by release date in descending order. The query also returns two other entities which have “Steven Spielberg” in their names.

Tip You may use python or python3 equally well.

Released after August 1984

Now, let’s do some filtering. This time we’ll only retrieve the movies which were released after August 1984. We’ll sort in increasing order this time by using orderasc, instead of orderdesc.

Editing query...
{
  director(func:allofterms(name, "steven spielberg")) {
    [email protected]
    director.film (orderasc: initial_release_date) @filter(ge(initial_release_date, "1984-08")) {
      [email protected]
      initial_release_date
    }
  }
}
curl localhost:8080/query -XPOST -d '
{
  director(func:allofterms(name, "steven spielberg")) {
    [email protected]
    director.film (orderasc: initial_release_date) @filter(ge(initial_release_date, "1984-08")) {
      [email protected]
      initial_release_date
    }
  }
}' | python -m json.tool | less
package main

import (
  "context"
  "flag"
  "fmt"
  "io/ioutil"
  "log"
  "os"

  "github.com/dgraph-io/dgraph/client"
  "github.com/gogo/protobuf/proto"
  "google.golang.org/grpc"
)

var (
  dgraph = flag.String("d", "127.0.0.1:9080", "Dgraph server address")
)

func main() {
  flag.Parse()
  conn, err := grpc.Dial(*dgraph, grpc.WithInsecure())
  if err != nil {
    log.Fatal(err)
  }
  defer conn.Close()

  // The Dgraph client needs a directory in which to write its blank node maps.
  clientDir, err := ioutil.TempDir("", "client_")
  if err != nil {
    log.Fatal(err)
  }
  defer os.RemoveAll(clientDir)

  dgraphClient := client.NewDgraphClient([]*grpc.ClientConn{conn}, client.DefaultOptions, clientDir)
  defer dgraphClient.Close()

  req := client.Req{}
  req.SetQuery(`blahblah`)

  resp, err := dgraphClient.Run(context.Background(), &req)
  if err != nil {
    log.Fatalf("Error in getting response from server, %s", err)
  }
  fmt.Printf("Response %+v\n", proto.MarshalTextString(resp))
}
package main

import (
  "bytes"
  "flag"
  "io/ioutil"
  "log"
  "net/http"
)

var (
  baseURL = flag.String("d", "http://127.0.0.1:8080/query", "Dgraph server address")
)

func main() {
  client := &http.Client{}
  body := bytes.NewBufferString(`{
  director(func:allofterms(name, "steven spielberg")) {
    [email protected]
    director.film (orderasc: initial_release_date) @filter(ge(initial_release_date, "1984-08")) {
      [email protected]
      initial_release_date
    }
  }
}`)
  req, err := http.NewRequest("POST", *baseURL, body)
  if err != nil {
    log.Fatal(err)
    return
  }

  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
    return
  }
  defer resp.Body.Close()

  responseData, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
    return
  }

  log.Printf("Response %+v\n", string(responseData))
}
Response

Released in 1990s

We’ll now add an AND filter using AND and find only the movies released in the 90s.

Editing query...
{
  director(func:allofterms(name, "steven spielberg")) {
    [email protected]
    director.film (orderasc: initial_release_date) @filter(ge(initial_release_date, "1990") AND le(initial_release_date, "2000")) {
      [email protected]
      initial_release_date
    }
  }
}
curl localhost:8080/query -XPOST -d '
{
  director(func:allofterms(name, "steven spielberg")) {
    [email protected]
    director.film (orderasc: initial_release_date) @filter(ge(initial_release_date, "1990") AND le(initial_release_date, "2000")) {
      [email protected]
      initial_release_date
    }
  }
}' | python -m json.tool | less
package main

import (
  "context"
  "flag"
  "fmt"
  "io/ioutil"
  "log"
  "os"

  "github.com/dgraph-io/dgraph/client"
  "github.com/gogo/protobuf/proto"
  "google.golang.org/grpc"
)

var (
  dgraph = flag.String("d", "127.0.0.1:9080", "Dgraph server address")
)

func main() {
  flag.Parse()
  conn, err := grpc.Dial(*dgraph, grpc.WithInsecure())
  if err != nil {
    log.Fatal(err)
  }
  defer conn.Close()

  // The Dgraph client needs a directory in which to write its blank node maps.
  clientDir, err := ioutil.TempDir("", "client_")
  if err != nil {
    log.Fatal(err)
  }
  defer os.RemoveAll(clientDir)

  dgraphClient := client.NewDgraphClient([]*grpc.ClientConn{conn}, client.DefaultOptions, clientDir)
  defer dgraphClient.Close()

  req := client.Req{}
  req.SetQuery(`blahblah`)

  resp, err := dgraphClient.Run(context.Background(), &req)
  if err != nil {
    log.Fatalf("Error in getting response from server, %s", err)
  }
  fmt.Printf("Response %+v\n", proto.MarshalTextString(resp))
}
package main

import (
  "bytes"
  "flag"
  "io/ioutil"
  "log"
  "net/http"
)

var (
  baseURL = flag.String("d", "http://127.0.0.1:8080/query", "Dgraph server address")
)

func main() {
  client := &http.Client{}
  body := bytes.NewBufferString(`{
  director(func:allofterms(name, "steven spielberg")) {
    [email protected]
    director.film (orderasc: initial_release_date) @filter(ge(initial_release_date, "1990") AND le(initial_release_date, "2000")) {
      [email protected]
      initial_release_date
    }
  }
}`)
  req, err := http.NewRequest("POST", *baseURL, body)
  if err != nil {
    log.Fatal(err)
    return
  }

  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
    return
  }
  defer resp.Body.Close()

  responseData, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
    return
  }

  log.Printf("Response %+v\n", string(responseData))
}
Response

Released since 2016

So far, we’ve been retrieving film titles using the name of the director. Now, we’ll start with films released since 2016, and their directors. To make things interesting, we’ll only retrieve the director name, if it matches any of “travis” or “knight”. In addition, we’ll also alias initial_release_date to release. This will make the result look better.

Editing query...
{
  films(func:ge(initial_release_date, "2016")) {
    [email protected]
    release: initial_release_date
    directed_by @filter(anyofterms(name, "travis knight")) {
      [email protected]
    }
  }
}
curl localhost:8080/query -XPOST -d '
{
  films(func:ge(initial_release_date, "2016")) {
    [email protected]
    release: initial_release_date
    directed_by @filter(anyofterms(name, "travis knight")) {
      [email protected]
    }
  }
}' | python -m json.tool | less
package main

import (
  "context"
  "flag"
  "fmt"
  "io/ioutil"
  "log"
  "os"

  "github.com/dgraph-io/dgraph/client"
  "github.com/gogo/protobuf/proto"
  "google.golang.org/grpc"
)

var (
  dgraph = flag.String("d", "127.0.0.1:9080", "Dgraph server address")
)

func main() {
  flag.Parse()
  conn, err := grpc.Dial(*dgraph, grpc.WithInsecure())
  if err != nil {
    log.Fatal(err)
  }
  defer conn.Close()

  // The Dgraph client needs a directory in which to write its blank node maps.
  clientDir, err := ioutil.TempDir("", "client_")
  if err != nil {
    log.Fatal(err)
  }
  defer os.RemoveAll(clientDir)

  dgraphClient := client.NewDgraphClient([]*grpc.ClientConn{conn}, client.DefaultOptions, clientDir)
  defer dgraphClient.Close()

  req := client.Req{}
  req.SetQuery(`blahblah`)

  resp, err := dgraphClient.Run(context.Background(), &req)
  if err != nil {
    log.Fatalf("Error in getting response from server, %s", err)
  }
  fmt.Printf("Response %+v\n", proto.MarshalTextString(resp))
}
package main

import (
  "bytes"
  "flag"
  "io/ioutil"
  "log"
  "net/http"
)

var (
  baseURL = flag.String("d", "http://127.0.0.1:8080/query", "Dgraph server address")
)

func main() {
  client := &http.Client{}
  body := bytes.NewBufferString(`{
  films(func:ge(initial_release_date, "2016")) {
    [email protected]
    release: initial_release_date
    directed_by @filter(anyofterms(name, "travis knight")) {
      [email protected]
    }
  }
}`)
  req, err := http.NewRequest("POST", *baseURL, body)
  if err != nil {
    log.Fatal(err)
    return
  }

  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
    return
  }
  defer resp.Body.Close()

  responseData, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
    return
  }

  log.Printf("Response %+v\n", string(responseData))
}
Response

This should give you an idea of some of the queries Dgraph is capable of. A wider range of queries can been found in the Query Language section.

Need Help

Troubleshooting

1. Docker: Error initialising postings store

One of the things to try would be to open bash in the container and try to run Dgraph from within it.

docker run -it dgraph/dgraph bash
# Now that you are within the container, run Dgraph.
dgraph

If Dgraph runs for you that indicates there could be something wrong with mounting volumes.