Official Dgraph Go client
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.
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.
| 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" |
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:
| Arg | Value | Description |
|---|---|---|
| apikey | \ | a Dgraph Cloud API Key |
| bearertoken | \ | 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:[email protected]: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=\ | Connect to a Dgraph Cloud cluster |
| dgraph://foo-bar.grpc.example.com?sslmode=verify-ca&bearertoken=\ | 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 clientsFor 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 clientYou 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 clientIn order to drop all data in the Dgraph Cluster and start fresh, use the DropAll function.
err := client.DropAll(context.TODO())
// Handle errorTo 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 errorTo run a mutation, use the RunDQL function.
mutationDQL := `{
set {
_:alice "Alice" .
_:alice "[email protected]" .
_:alice "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, "[email protected]"))
}
mutation {
set {
uid(user) "30" .
uid(user) "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, "[email protected]"))
}
mutation @if(eq(len(user), 1)) {
set {
uid(user) "30" .
uid(user) "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 errorTo drop a namespace:
err := client.DropNamespace(context.TODO())
// Handle errornamespaces, 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 errorIf your server additionally has namespaces (Dgraph v21.03 or above), use the LoginIntoNamespace
API.
err := dgraphClient.LoginIntoNamespace(ctx, "user", "passwd", 0x10)
// Check errorTo 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 errorOperation 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 m
No open issues yet, or sync has not completed.