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.
go get
:
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 250.X.Y | github.com/dgraph-io/dgo/v250 |
Use the new v2 APIs with Dgraph v25. See the v2
APIs
Create the client
To create a client, dial a connection to Dgraph’s external gRPC port (typically9080
). The following code snippet shows just one connection. You can connect
to multiple Dgraph Alphas to distribute the workload evenly.
Multi-tenancy
In multi-tenancy environments, Dgraph provides a new methodLoginIntoNamespace()
, 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
:
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 aapi.Operation
object, and pass it down to the
Alter
method.
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.
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.
Create a transaction
Dgraph supports running distributed ACID transactions. To create a transaction, just callc.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.
Read-only transactions
Read-only transactions can be created by callingc.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 callingtxn.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 with RDF response
You can get query result as a RDF response by callingtxn.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.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.
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.Complete example
This is an example from the GoDoc. It shows how to create aNode
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.