Official Dgraph Go client which communicates with the server using gRPC.

Before using this client, we highly recommend that you go through dgraph.io/tour and dgraph.io/docs to understand how to run and work with Dgraph.

Use Github Issues for reporting issues about this repository.

• Supported Versions
• New APIs in v25
  • Connection Strings
  • Advanced Client Creation
  • Dropping All Data
  • Set Schema
  • Running a Mutation
  • Running a Query
  • Running a Query With Variables
  • Running a Best Effort Query
  • Running a ReadOnly Query
  • Running a Query with RDF Response
  • Running an Upsert
  • Running a Conditional Upsert
  • Creating a New Namespace
  • Dropping a Namespace
  • List All Namespaces
• Existing APIs
  • Creating a Client
  • Login into a namespace
  • Altering the database
  • Creating a transaction
  • Running a mutation
  • Running a query
  • Query with RDF response
  • Running an Upsert: Query + Mutation
  • Running Conditional Upsert
  • Committing a transaction
  • Setting Metadata Headers
• Development
  • Running tests

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

The dgo package supports connecting to a Dgraph cluster using connection strings. Dgraph connections 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 args:

Some example connection strings:

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

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

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

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

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(), sch)
// Handle error

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(), mutationDQL)
// Handle error
// Print map of blank UIDs
fmt.Printf("%+v\n", resp.Uids)

To run a query, use the same RunDQL function.

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

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(), queryDQL, vars)
// Handle error
fmt.Printf("%s\n", resp.Json)

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(), queryDQL, dgo.WithBestEffort())
// Handle error
fmt.Printf("%s\n", resp.Json)

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(), queryDQL, dgo.WithReadOnly())
// Handle error
fmt.Printf("%s\n", resp.Json)

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(), queryDQL, dgo.WithResponseFormat(api_v2.RespFormat_RDF))
// Handle error
fmt.Printf("%s\n", resp.Rdf)

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(), upsertQuery)
// Handle error
fmt.Printf("%s\n", resp.Json)
fmt.Printf("%+v\n", resp.Uids)

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(), upsertQuery)
// Handle error
fmt.Printf("%s\n", resp.Json)

Dgraph v25 supports creating namespaces using grpc API. You can create one using the dgo client.

_, err := client.CreateNamespace(context.TODO())
// Handle error

To drop a namespace:

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

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

dgraphClient object can be initialized by passing it a list of api.DgraphClient clients as variadic arguments. Connecting to multiple Dgraph servers in the same cluster allows for better distribution of workload.

The following code snippet shows just one connection.

conn, err := grpc.Dial("localhost:9080", grpc.WithInsecure())
// Check error
defer conn.Close()
dgraphClient := dgo.NewDgraphClient(api.NewDgraphClient(conn))

If your server has Access Control Lists enabled (Dgraph v1.1 or above), the client must be logged in for accessing data. If you do not use the WithACLCreds option with NewClient or a connection string with username:password, use the Login endpoint.

Calling login will obtain and remember the access and refresh JWT tokens. All subsequent operations via the logged in client will send along the stored access token.

err := dgraphClient.Login(ctx, "user", "passwd")
// Check error

If your server additionally has namespaces (Dgraph v21.03 or above), use the LoginIntoNamespace API.

err := dgraphClient.LoginIntoNamespace(ctx, "user", "passwd", 0x10)
// Check error

To set the schema, create an instance of api.Operation and use the Alter endpoint.

op := &api.Operation{
 Schema: `name: string @index(exact) .`,
}
err := dgraphClient.Alter(ctx, op)
// Check error

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

Starting Dgraph version 20.03.0, indexes can be computed in the background. You can set RunInBackground field of the api.Operation to true before passing it to the Alter function. You can find more details here.

op := &api.Operation{
 Schema: `name: string @index(exact) .`,
 RunInBackground: true
}
err := dgraphClient.Alter(ctx, op)

To create a transaction, call dgraphClient.NewTxn(), which returns a *dgo.Txn object. This operation incurs no network overhead.

It is a good practice to call txn.Discard(ctx) using a defer statement after it is initialized. Calling txn.Discard(ctx) after txn.Commit(ctx) is a no-op. Furthermore, txn.Discard(ctx) can be called multiple times with no additional side-effects.

txn := dgraphClient.NewTxn()
defer txn.Discard(ctx)

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 cannot contain mutations and trying to call txn.Commit() will result in an error. Calling txn.Discard() will be a no-op.

txn.Mutate(ctx, mu) runs a mutation. It takes in a context.Context and a *api.Mutation object. You can set the data using JSON or RDF N-Quad format.

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 DelNquads, 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 DelNquads instead if they are planning on using RDF.

We define a Person struct to represent a Person and marshal an instance of it to use with Mutation object.

type Person struct {
 Uid string `json:"uid,omitempty"`
 Name string `json:"name,omitempty"`
 DType []string `json:"dgraph.type,omitempty"`
}
p := Person{
 Uid: "_:alice",
 Name: "Alice",
 DType: []string{"Person"},
}
pb, err := json.Marshal(p)
// Check error
mu := &api.Mutation{
 SetJson: pb,
}
res, err := txn.Mutate(ctx, mu)
// Check error

For a more complete example, see Example.

Sometimes, you only want to commit a mutation, without querying anything further. In such cases, you can use mu.CommitNow = true to indicate that the mutation must be immediately committed.

Mutation can be run using txn.Do as well.

mu := &api.Mutation{
 SetJson: pb,
}
req := &api.Request{CommitNow:true, Mutations: []*api.Mutation{mu}}
res, err := txn.Do(ctx, req)
// Check error

You can run a query by calling txn.Query(ctx, q). You will need to pass in a DQL query string. If you want to pass an additional map of any variables that you might want to set in the query, call txn.QueryWithVars(ctx, q, vars) with the variables map as third argument.

Let's run the following query with a variable $a:

q := `query all($a: string) {
 all(func: eq(name, $a)) {
 name
 }
 }`
resp, err := txn.QueryWithVars(ctx, q, map[string]string{"$a": "Alice"})
fmt.Printf("%s\n", resp.Json)

You can also use txn.Do function to run a query.

req := &api.Request{
 Query: q,
 Vars: map[string]string{"$a": "Alice"},
}
resp, err := txn.Do(ctx, req)
// Check error
fmt.Printf("%s\n", resp.Json)

When running a schema query for predicate name, the schema response is found in the Json field of api.Response as shown below:

q := `schema(pred: [name]) {
 type
 index
 reverse
 tokenizer
 list
 count
 upsert
 lang
}`
resp, err := txn.Query(ctx, q)
// Check error
fmt.Printf("%s\n", resp.Json)

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

Note: 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)
// check error
// <0x17> <name> "Alice" .
// <0x17> <balance> 100 .
fmt.Println(resp.Rdf)

txn.QueryRDFWithVars is also available when you need to pass values for variables used in the query.

The txn.Do function allows you to run upserts consisting of one query and one mutation. Variables can be defined in the query and used in the mutation. You could also use txn.Do to perform a query followed by a mutation.

To know more about upsert, we highly recommend going through the docs at Upsert Block.

query = `
 query {
 user as var(func: eq(email, "wrong_email@dgraph.io"))
 }`
mu := &api.Mutation{
 SetNquads: []byte(`uid(user) <email> "correct_email@dgraph.io" .`),
}
req := &api.Request{
 Query: query,
 Mutations: []*api.Mutation{mu},
 CommitNow:true,
}
// Update email only if matching uid found.
_, err := dg.NewTxn().Do(ctx, req)
// Check error

The upsert block also allows specifying a conditional mutation block using an @if directive. The mutation is executed only when the specified condition is true. If the condition is false, the mutation is silently ignored.

See more about Conditional Upsert Here.

query = `
 query {
 user as var(func: eq(email, "wrong_email@dgraph.io"))
 }`
mu := &api.Mutation{
 Cond: `@if(eq(len(user), 1))`, // Only mutate if "wrong_email@dgraph.io" belongs to single user.
 SetNquads: []byte(`uid(user) <email> "correct_email@dgraph.io" .`),
}
req := &api.Request{
 Query: query,
 Mutations: []*api.Mutation{mu},
 CommitNow:true,
}
// Update email only if exactly one matching uid is found.
_, err := dg.NewTxn().Do(ctx, req)
// Check error

A transaction can be committed using the txn.Commit(ctx) method. If your transaction consisted solely of calls to txn.Query or txn.QueryWithVars, and no calls to txn.Mutate, then calling txn.Commit is not necessary.

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 user to retry transactions when they fail.

txn := dgraphClient.NewTxn()
// Perform some queries and mutations.
err := txn.Commit(ctx)
if err == y.ErrAborted {
 // Retry or handle error
}

Metadata headers such as authentication tokens can be set through the context of gRPC methods. Below is an example of how to set a header named "auth-token".

// The following piece of code shows how one can set metadata with
// auth-token, to allow Alter operation, if the server requires it.
md := metadata.New(nil)
md.Append("auth-token", "the-auth-token-value")
ctx := metadata.NewOutgoingContext(context.Background(), md)
dg.Alter(ctx, &op)

Make sure you have dgraph installed in your GOPATH before you run the tests. The dgo test suite requires that a Dgraph cluster with ACL enabled be running locally. To start such a cluster, you may use the docker compose file located in the testing directory t.

docker compose -f t/docker-compose.yml up -d
# wait for cluster to be healthy
go test -v ./...
docker compose -f t/docker-compose.yml down