Official Dgraph Go client which communicates with the server using gRPC.
Before using this client, we highly recommend that you go through tour.dgraph.io and docs.dgraph.io to understand how to run and work with Dgraph.
go get -u -v github.com/dgraph-io/dgo
dgraphClient
object can be initialised 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())
if err != nil {
log.Fatal(err)
}
defer conn.Close()
dgraphClient := dgo.NewDgraphClient(api.NewDgraphClient(conn))
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.
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()
using a defer
statement after it is initialized.
Calling txn.Discard()
after txn.Commit()
is a no-op and you can call txn.Discard()
multiple
times with no additional side-effects.
txn := dgraphClient.NewTxn()
defer txn.Discard(ctx)
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.
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"`
}
p := Person{
Uid: "_:alice",
Name: "Alice",
}
pb, err := json.Marshal(p)
if err != nil {
log.Fatal(err)
}
mu := &api.Mutation{
SetJson: pb,
}
assigned, err := txn.Mutate(ctx, mu)
if err != nil {
log.Fatal(err)
}
For a more complete example, see GoDoc.
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.
You can run a query by calling txn.Query(ctx, q)
. You will need to pass in a GraphQL+- 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.Println(string(resp.Json))
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
}
Make sure you have dgraph
installed before you run the tests. This script will run the unit and
integration tests.
./contrib/scripts/run_tests.sh