Go - Dgraph

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.

The Go client communicates with the server on the gRPC port (default value 9080).

The client can be obtained in the usual way via go get:

# Requires at least Go 1.23
go get -u -v github.com/dgraph-io/dgo/v250

The full GoDoc contains documentation for the client API along with examples showing how to use it.

Supported versions

Depending on the version of Dgraph that you are connecting to, you should use a compatible version of this client and their corresponding import paths.

Dgraph version	dgo version	dgo import path
dgraph 23.X.Y	dgo 230.X.Y	”github.com/dgraph-io/dgo/v230”
dgraph 24.X.Y	dgo 240.X.Y	”github.com/dgraph-io/dgo/v240”
dgraph 25.X.Y	dgo 240.X.Y	”github.com/dgraph-io/dgo/v240”
dgraph 25.X.Y	dgo 250.X.Y	”github.com/dgraph-io/dgo/v250”

v25 APIs

These are experimental APIs that we’re still making changes to. If you have any feedback, please let us know either on Discord or GitHub.

Connection strings

The dgo package supports connecting to a Dgraph cluster using connection strings. Dgraph connection strings take the form dgraph://{username:password@}host:port?args.

username and password are optional. If username is provided, a password must also be present. If supplied, these credentials are used to log into a Dgraph cluster through the ACL mechanism.

Valid connection string arguments:

Arg	Value	Description
apikey	<key>	a Dgraph Cloud API Key
bearertoken	<token>	an access token
sslmode	disable \| require \| verify-ca	TLS option, the default is `disable`. If `verify-ca` is set, the TLS certificate configured in the Dgraph cluster must be from a valid certificate authority.

Some example connection strings:

Value	Explanation
dgraph://localhost:9080	Connect to localhost, no ACL, no TLS
dgraph://sally:supersecret@dg.example.com:443?sslmode=verify-ca	Connect to remote server, use ACL and require TLS and a valid certificate from a CA
dgraph://foo-bar.grpc.us-west-2.aws.cloud.dgraph.io:443?sslmode=verify-ca&apikey=<your-api-connection-key>	Connect to a Dgraph Cloud cluster
dgraph://foo-bar.grpc.hypermode.com?sslmode=verify-ca&bearertoken=<some access token>	Connect to a Dgraph cluster protected by a secure gateway

Using the Open function with a connection string:

// open a connection to an ACL-enabled, non-TLS cluster and login as groot
client, err := dgo.Open("dgraph://groot:password@localhost:8090")
// Check error
defer client.Close()
// Use the clients

Advanced client creation

For more control, you can create a client using the NewClient function.

client, err := dgo.NewClient("localhost:9181",
  // add Dgraph ACL credentials
  dgo.WithACLCreds("groot", "password"),
  // add insecure transport credentials
  dgo.WithGrpcOption(grpc.WithTransportCredentials(insecure.NewCredentials())),
)
// Check error
defer client.Close()
// Use the client

You can connect to multiple alphas using NewRoundRobinClient.

client, err := dgo.NewRoundRobinClient([]string{"localhost:9181", "localhost:9182", "localhost:9183"},
  // add Dgraph ACL credentials
  dgo.WithACLCreds("groot", "password"),
  // add insecure transport credentials
  dgo.WithGrpcOption(grpc.WithTransportCredentials(insecure.NewCredentials())),
)
// Check error
defer client.Close()
// Use the client

Connecting to Dgraph cloud

You can use either Open or NewClient to connect to Dgraph Cloud. Note DialCloud is marked deprecated and will be removed in later versions.

Using Open with a connection string:

client, err := dgo.Open("dgraph://foo-bar.grpc.cloud.dgraph.io:443?sslmode=verify-ca&apikey=AValidKeYFromDgrAPHCloud=")
// Check error
defer client.Close()

Using NewClient:

client, err := dgo.NewClient("foo-bar.grpc.cloud.dgraph.io:443",
  dgo.WithDgraphAPIKey("AValidKeYFromDgrAPHCloud="),
  dgo.WithSystemCertPool(),
)
// Check error
defer client.Close()

Dropping all data

In order to drop all data in the Dgraph cluster and start fresh, use the DropAllNamespaces function.

err := client.DropAllNamespaces(context.TODO())
// Handle error

Set schema

To set the schema, use the SetSchema function.

sch := `
  name: string @index(exact) .
  email: string @index(exact) @unique .
  age: int .
`
err := client.SetSchema(context.TODO(), dgo.RootNamespace, sch)
// Handle error

Running a mutation

To run a mutation, use the RunDQL function.

mutationDQL := `{
  set {
    _:alice <name> "Alice" .
    _:alice <email> "alice@example.com" .
    _:alice <age> "29" .
  }
}`
resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, mutationDQL)
// Handle error
// Print map of blank UIDs
fmt.Printf("%+v\n", resp.BlankUids)

Running a query

To run a query, use the same RunDQL function.

queryDQL := `{
  alice(func: eq(name, "Alice")) {
    name
    email
    age
  }
}`
resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, queryDQL)
// Handle error
fmt.Printf("%s\n", resp.QueryResult)

Running a query with variables

To run a query with variables, using RunDQLWithVars.

queryDQL = `query Alice($name: string) {
  alice(func: eq(name, $name)) {
    name
    email
    age
  }
}`
vars := map[string]string{"$name": "Alice"}
resp, err := client.RunDQLWithVars(context.TODO(), dgo.RootNamespace, queryDQL, vars)
// Handle error
fmt.Printf("%s\n", resp.QueryResult)

Running a best effort query

To run a BestEffort query, use the same RunDQL function with TxnOption.

queryDQL := `{
  alice(func: eq(name, "Alice")) {
    name
    email
    age
  }
}`
resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, queryDQL, dgo.WithBestEffort())
// Handle error
fmt.Printf("%s\n", resp.QueryResult)

Running a read-only query

To run a ReadOnly query, use the same RunDQL function with TxnOption.

queryDQL := `{
  alice(func: eq(name, "Alice")) {
    name
    email
    age
  }
}`
resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, queryDQL, dgo.WithReadOnly())
// Handle error
fmt.Printf("%s\n", resp.QueryResult)

Running a query with rdf response

To get the query response in RDF format instead of JSON format, use the following TxnOption.

queryDQL := `{
  alice(func: eq(name, "Alice")) {
    name
    email
    age
  }
}`
resp, err = client.RunDQL(context.TODO(), dgo.RootNamespace, queryDQL, dgo.WithResponseFormat(api_v25.RespFormat_RDF))
// Handle error
fmt.Printf("%s\n", resp.QueryResult)

Running an Upsert

The RunDQL function also allows you to run upserts as well.

upsertQuery := `upsert {
  query {
    user as var(func: eq(email, "alice@example.com"))
  }
  mutation {
    set {
      uid(user) <age> "30" .
      uid(user) <name> "Alice Sayum" .
    }
  }
}`
resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, upsertQuery)
// Handle error
fmt.Printf("%s\n", resp.QueryResult)
fmt.Printf("%+v\n", resp.BlankUids)

Running a conditional upsert

upsertQuery := `upsert {
  query {
    user as var(func: eq(email, "alice@example.com"))
  }
  mutation @if(eq(len(user), 1)) {
    set {
      uid(user) <age> "30" .
      uid(user) <name> "Alice Sayum" .
    }
  }
}`
resp, err := client.RunDQL(context.TODO(), dgo.RootNamespace, upsertQuery)
// Handle error
fmt.Printf("%s\n", resp.QueryResult)

Creating a new namespace

Dgraph v25 supports namespaces that have names. You can create one using the dgo client.

err := client.CreateNamespace(context.TODO(), "finance-graph")
// Handle error

You can now pass this name to SetSchema, RunDQL or similar functions.

Dropping a Namespace

To drop a namespace:

err := client.DropNamespace(context.TODO(), "finance-graph")
// Handle error

Rename a Namespace

A namespace can be renamed as follows.

err := client.RenameNamespace(context.TODO(), "finance-graph", "new-finance-graph")
// Handle error

List all namespaces

namespaces, err := client.ListNamespaces(context.TODO())
// Handle error
fmt.Printf("%+v\n", namespaces)

v1 APIs

Create the client

To create a client, dial a connection to Dgraph’s external gRPC port (typically 9080). The following code snippet shows just one connection. You can connect to multiple Dgraph Alphas to distribute the workload evenly.

func newClient() *dgo.Dgraph {
  // Dial a gRPC connection. The address to dial to can be configured when
  // setting up the dgraph cluster.
  d, err := grpc.Dial("localhost:9080", grpc.WithInsecure())
  if err != nil {
    log.Fatal(err)
  }

  return dgo.NewDgraphClient(
    api.NewDgraphClient(d),
  )
}

The client can be configured to use gRPC compression:

func newClient() *dgo.Dgraph {
  // Dial a gRPC connection. The address to dial to can be configured when
  // setting up the dgraph cluster.
  dialOpts := append([]grpc.DialOption{},
    grpc.WithInsecure(),
    grpc.WithDefaultCallOptions(grpc.UseCompressor(gzip.Name)))
  d, err := grpc.Dial("localhost:9080", dialOpts...)

  if err != nil {
    log.Fatal(err)
  }

  return dgo.NewDgraphClient(
    api.NewDgraphClient(d),
  )
}

Multi-tenancy

In multi-tenancy environments, Dgraph provides a new method LoginIntoNamespace(), which allows the users to login to a specific namespace.

In order to create a dgo client, and make the client login into namespace 123:

conn, err := grpc.Dial("127.0.0.1:9080", grpc.WithInsecure())
if err != nil {
  glog.Error("While trying to dial gRPC, got error", err)
}
dc := dgo.NewDgraphClient(api.NewDgraphClient(conn))
ctx := context.Background()
// Login to namespace 123
if err := dc.LoginIntoNamespace(ctx, "groot", "password", 123); err != nil {
  glog.Error("Failed to login: ",err)
}

In this example, the client logs into namespace 123 using username groot and password password. Once logged in, the client can perform all the operations allowed to the groot user of namespace 123.

Alter the database

To set the schema, set it on a api.Operation object, and pass it down to the Alter method.

func setup(c *dgo.Dgraph) {
  // Install a schema into dgraph. Accounts have a `name` and a `balance`.
  err := c.Alter(context.Background(), &api.Operation{
    Schema: `
      name: string @index(term) .
      balance: int .
    `,
  })
}

api.Operation contains other fields as well, including drop predicate and drop all. Drop all is useful if you wish to discard all the data, and start from a clean slate, without bringing the instance down.

  // Drop all data including schema from the dgraph instance. This is useful
  // for small examples such as this, since it puts dgraph into a clean
  // state.
  err := c.Alter(context.Background(), &api.Operation{DropOp: api.Operation_ALL})

api.Operation also supports a drop data operation. This operation drops all the data but preserves the schema. This is useful when the schema is large and needs to be reused, such as in between unit tests.

  // Drop all data including schema from the dgraph instance. This is useful
  // for small examples such as this, since it puts dgraph into a clean
  // state.
  err := c.Alter(context.Background(), &api.Operation{DropOp: api.Operation_DATA})

Create a transaction

Dgraph supports running distributed ACID transactions. To create a transaction, just call c.NewTxn(). This operation doesn’t incur in network calls. Typically, you’d also want to call a defer txn.Discard(ctx) to let it automatically rollback in case of errors. Calling Discard after Commit would be a no-op.

func runTxn(c *dgo.Dgraph) {
  txn := c.NewTxn()
  defer txn.Discard(ctx)
  ...
}

Read-only transactions

Read-only transactions can be created by calling c.NewReadOnlyTxn(). Read-only transactions are useful to increase read speed because they can circumvent the usual consensus protocol. Read-only transactions can’t contain mutations and trying to call txn.Commit() results in an error. Calling txn.Discard() is a no-op.

Read-only queries can optionally be set as best-effort. Using this flag requests the Dgraph Alpha to try to get timestamps from memory on a best-effort basis to reduce the number of outbound requests to Zero. This may yield improved latencies in read-bound workloads where linearizable reads are not strictly needed.

Run a query

You can run a query by calling txn.Query. The response would contain a JSON field, which has the JSON encoded result. You can unmarshal it into Go struct via json.Unmarshal.

  // Query the balance for Alice and Bob.
  const q = `
    {
      all(func: anyofterms(name, "Alice Bob")) {
        uid
        balance
      }
    }
  `
  resp, err := txn.Query(context.Background(), q)
  if err != nil {
    log.Fatal(err)
  }

  // After we get the balances, we have to decode them into structs so that
  // we can manipulate the data.
  var decode struct {
    All []struct {
      Uid     string
      Balance int
    }
  }
  if err := json.Unmarshal(resp.GetJson(), &decode); err != nil {
    log.Fatal(err)
  }

Query with RDF response

You can get query result as a RDF response by calling txn.QueryRDF. The response would contain a Rdf field, which has the RDF encoded result.

If you are querying only for uid values, use a JSON format response.

  // Query the balance for Alice and Bob.
  const q = `
    {
      all(func: anyofterms(name, "Alice Bob")) {
        name
        balance
      }
    }
  `
  resp, err := txn.QueryRDF(context.Background(), q)
  if err != nil {
    log.Fatal(err)
  }

  // <0x17> <name> "Alice" .
  // <0x17> <balance> 100 .
  fmt.Println(resp.Rdf)

Run a mutation

txn.Mutate would run the mutation. It takes in a api.Mutation object, which provides two main ways to set data: JSON and RDF N-Quad. You can choose whichever way is convenient.

To use JSON, use the fields SetJson and DeleteJson, which accept a string representing the nodes to be added or removed respectively (either as a JSON map or a list). To use RDF, use the fields SetNquads and DeleteNquads, which accept a string representing the valid RDF triples (one per line) to added or removed respectively. This protobuf object also contains the Set and Del fields which accept a list of RDF triples that have already been parsed into our internal format. As such, these fields are mainly used internally and users should use the SetNquads and DeleteNquads instead if planning on using RDF.

We’re going to continue using JSON. You could modify the Go structs parsed from the query, and marshal them back into JSON.

  // Move $5 between the two accounts.
  decode.All[0].Bal += 5
  decode.All[1].Bal -= 5

  out, err := json.Marshal(decode.All)
  if err != nil {
    log.Fatal(err)
  }

  _, err := txn.Mutate(context.Background(), &api.Mutation{SetJson: out})

Sometimes, you only want to commit mutation, without querying anything further. In such cases, you can use a CommitNow field in api.Mutation to indicate that the mutation must be immediately committed.

Commit the transaction

Once all the queries and mutations are done, you can commit the transaction. It returns an error in case the transaction couldn’t be committed.

  // Finally, we can commit the transactions. An error will be returned if
  // other transactions running concurrently modify the same data that was
  // modified in this transaction. It is up to the library user to retry
  // transactions when they fail.

  err := txn.Commit(context.Background())

Complete example

This is an example from the GoDoc. It shows how to create a Node with name Alice, while also creating her relationships with other nodes.

loc predicate is of type geo and can be easily marshaled and unmarshaled into a Go struct. More such examples are present as part of the GoDoc.

You can also download this complete example file from our GitHub repository.

package dgo_test

import (
  "context"
  "encoding/json"
  "fmt"
  "log"
  "time"

  "github.com/dgraph-io/dgo/v200/protos/api"
)

type School struct {
  Name  string   `json:"name,omitempty"`
  DType []string `json:"dgraph.type,omitempty"`
}

type loc struct {
  Type   string    `json:"type,omitempty"`
  Coords []float64 `json:"coordinates,omitempty"`
}

// If omitempty is not set, then edges with empty values (0 for int/float, "" for string, false
// for bool) would be created for values not specified explicitly.

type Person struct {
  Uid      string     `json:"uid,omitempty"`
  Name     string     `json:"name,omitempty"`
  Age      int        `json:"age,omitempty"`
  Dob      *time.Time `json:"dob,omitempty"`
  Married  bool       `json:"married,omitempty"`
  Raw      []byte     `json:"raw_bytes,omitempty"`
  Friends  []Person   `json:"friend,omitempty"`
  Location loc        `json:"loc,omitempty"`
  School   []School   `json:"school,omitempty"`
  DType    []string   `json:"dgraph.type,omitempty"`
}

func Example_setObject() {
  dg, cancel := getDgraphClient()
  defer cancel()

  dob := time.Date(1980, 01, 01, 23, 0, 0, 0, time.UTC)
  // While setting an object if a struct has a Uid then its properties in the graph are updated
  // else a new node is created.
  // In the example below new nodes for Alice, Bob and Charlie and school are created (since they
  // don't have a Uid).
  p := Person{
    Uid:     "_:alice",
    Name:    "Alice",
    Age:     26,
    Married: true,
    DType:   []string{"Person"},
    Location: loc{
      Type:   "Point",
      Coords: []float64{1.1, 2},
    },
    Dob: &dob,
    Raw: []byte("raw_bytes"),
    Friends: []Person{{
      Name:  "Bob",
      Age:   24,
      DType: []string{"Person"},
    }, {
      Name:  "Charlie",
      Age:   29,
      DType: []string{"Person"},
    }},
    School: []School{{
      Name:  "Crown Public School",
      DType: []string{"Institution"},
    }},
  }

  op := &api.Operation{}
  op.Schema = `
    name: string @index(exact) .
    age: int .
    married: bool .
    loc: geo .
    dob: datetime .
    Friend: [uid] .
    type: string .
    coords: float .
    type Person {
      name: string
      age: int
      married: bool
      Friend: [Person]
      loc: Loc
    }
    type Institution {
      name: string
    }
    type Loc {
      type: string
      coords: float
    }
  `

  ctx := context.Background()
  if err := dg.Alter(ctx, op); err != nil {
    log.Fatal(err)
  }

  mu := &api.Mutation{
    CommitNow: true,
  }
  pb, err := json.Marshal(p)
  if err != nil {
    log.Fatal(err)
  }

  mu.SetJson = pb
  response, err := dg.NewTxn().Mutate(ctx, mu)
  if err != nil {
    log.Fatal(err)
  }

  // Assigned uids for nodes which were created would be returned in the response.Uids map.
  variables := map[string]string{"$id1": response.Uids["alice"]}
  q := `query Me($id1: string){
    me(func: uid($id1)) {
      name
      dob
      age
      loc
      raw_bytes
      married
      dgraph.type
      friend @filter(eq(name, "Bob")){
        name
        age
        dgraph.type
      }
      school {
        name
        dgraph.type
      }
    }
  }`

  resp, err := dg.NewTxn().QueryWithVars(ctx, q, variables)
  if err != nil {
    log.Fatal(err)
  }

  type Root struct {
    Me []Person `json:"me"`
  }

  var r Root
  err = json.Unmarshal(resp.Json, &r)
  if err != nil {
    log.Fatal(err)
  }

  out, _ := json.MarshalIndent(r, "", "\t")
  fmt.Printf("%s\n", out)
}

Example output result:

 Output: {
   "me": [
     {
       "name": "Alice",
       "age": 26,
       "dob": "1980-01-01T23:00:00Z",
       "married": true,
       "raw_bytes": "cmF3X2J5dGVz",
       "friend": [
         {
           "name": "Bob",
           "age": 24,
           "loc": {},
           "dgraph.type": [
             "Person"
           ]
         }
       ],
       "loc": {
         "type": "Point",
         "coordinates": [
           1.1,
           2
         ]
       },
       "school": [
         {
           "name": "Crown Public School",
           "dgraph.type": [
             "Institution"
           ]
         }
       ],
       "dgraph.type": [
         "Person"
       ]
     }
   ]
 }

Getting Started

Connecting

Query Language

GraphQL-based Development

Administration

Tools

Resources

Go

Supported versions

v25 APIs

Connection strings

Advanced client creation

Connecting to Dgraph cloud

Dropping all data

Set schema

Running a mutation

Running a query

Running a query with variables

Running a best effort query

Running a read-only query

Running a query with rdf response

Running an Upsert

Running a conditional upsert

Creating a new namespace

Dropping a Namespace

Rename a Namespace

List all namespaces

v1 APIs

Create the client

Multi-tenancy

Alter the database

Create a transaction

Read-only transactions

Run a query

Query with RDF response

Run a mutation

Commit the transaction

Complete example

Getting Started

Connecting

Query Language

GraphQL-based Development

Administration

Tools

Resources

​Supported versions

​v25 APIs

​Connection strings

​Advanced client creation

​Connecting to Dgraph cloud

​Dropping all data

​Set schema

​Running a mutation

​Running a query

​Running a query with variables

​Running a best effort query

​Running a read-only query

​Running a query with rdf response

​Running an Upsert

​Running a conditional upsert

​Creating a new namespace

​Dropping a Namespace

​Rename a Namespace

​List all namespaces

​v1 APIs

​Create the client

​Multi-tenancy

​Alter the database

​Create a transaction

​Read-only transactions

​Run a query

​Query with RDF response

​Run a mutation

​Commit the transaction

​Complete example

Supported versions

v25 APIs

Connection strings

Advanced client creation

Connecting to Dgraph cloud

Dropping all data

Set schema

Running a mutation

Running a query

Running a query with variables

Running a best effort query

Running a read-only query

Running a query with rdf response

Running an Upsert

Running a conditional upsert

Creating a new namespace

Dropping a Namespace

Rename a Namespace

List all namespaces

v1 APIs

Create the client

Multi-tenancy

Alter the database

Create a transaction

Read-only transactions

Run a query

Query with RDF response

Run a mutation

Commit the transaction

Complete example