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.
curl
and
jq
are used. However, the real intention
here is to show other programmers how they could implement a client in their
language on top of the HTTP API.
For an example of how to build a client on top of gRPC, refer to the
implementation of the Go client.
Similar to the Go client example, we use a bank account transfer example.
Create the client
A client built on top of the HTTP API needs to track three pieces of state for each transaction.-
A start timestamp (
start_ts
). This uniquely identifies a transaction, and doesn’t change over the transaction lifecycle. -
The set of keys modified by the transaction (
keys
). This aids in transaction conflict detection. Every mutation would send back a new set of keys. The client must merge them with the existing set. Optionally, a client can de-dup these keys while merging. -
The set of predicates modified by the transaction (
preds
). This aids in predicate move detection. Every mutation would send back a new set of predicates. The client must merge them with the existing set. Optionally, a client can de-dup these keys while merging.
Alter the DQL schema
You may need to alter the DQL schema to declare predicate types, to add predicate search indexes and to declare the predicates expected in entities of specific type. Update the DQL schema is done by posting schema data to the/alter
endpoint:
The request updates or creates the predicates and types present in the
request. It doesn’t modify or delete other schema information that may be
present.
Query current DQL schema
Obtain the DQL schema by issuing a DQL query on/query
endpoint.
Start a transaction
Assume some initial accounts with balances have been populated. We now want to transfer money from one account to the other. This is done in four steps:- Create a new transaction.
- Inside the transaction, run a query to determine the current balances.
- Perform a mutation to update the balances.
- Commit the transaction.
start_ts
can
initially be set to 0. keys
can start as an empty set.
For both query and mutation if the start_ts
is provided as a path parameter,
then the operation is performed as part of the ongoing transaction. Otherwise, a
new transaction is initiated.
Run a query
To query the database, the/query
endpoint is used. Remember to set the
Content-Type
header to application/dql
to ensure that the body of the
request is parsed correctly.
To get the balances for both accounts:
data
field is additional
data in the extensions -> txn
field. This data has to be tracked by the
client.
For queries, there is a start_ts
in the response. This start_ts
needs to be
used in all subsequent interactions with Dgraph for this transaction, and so
should become part of the transaction state.
Run a mutation
Mutations can be done over HTTP by making aPOST
request to an Alpha’s
/mutate
endpoint. We need to send a mutation to Dgraph with the updated
balances. If Bob transfers $10 to Alice, then the RDF triples to send are:
/mutate
endpoint. We need to provide our
transaction start timestamp as a path parameter, so that Dgraph knows which
transaction the mutation should be part of. We also need to set Content-Type
header to application/rdf
to specify that mutation is written in RDF format.
keys
and predicates
which should be added to the
transaction state.
Committing the transaction
It is possible to commit immediately after a mutation is made (without
requiring to use the
/commit
endpoint as explained in this section). To do
this, add the parameter commitNow
in the URL /mutate?commitNow=true
./commit
endpoint. We need the
start_ts
we’ve been using for the transaction along with the list of keys
and the list of predicates. If we had performed multiple mutations in the
transaction instead of just one, then the keys and predicates provided during
the commit would be the union of all keys and predicates returned in the
responses from the /mutate
endpoint.
The preds
field is used to cancel the transaction in cases where some of the
predicates are moved. This field isn’t required and the /commit
endpoint also
accepts the old format, which was a single array of keys.
Cancelling the transaction
To cancel a transaction, use the same/commit
endpoint with the abort=true
parameter while specifying the startTs
value for the transaction.
Running read-only queries
You can set the query parameterro=true
to /query
to set it as a
read-only query.
Running best-effort queries
Compression via HTTP
Dgraph supports gzip-compressed requests to and from Dgraph Alphas for/query
,
/mutate
, and /alter
.
Compressed requests: to send compressed requests, set the HTTP request header
Content-Encoding: gzip
along with the gzip-compressed payload.
Compressed responses: to receive compressed responses, set the HTTP request
header Accept-Encoding: gzip
.
Example of a compressed request via curl:
Curl has a
--compressed
option that automatically
requests for a compressed response (Accept-Encoding
header) and decompresses
the compressed response.Run a query in JSON format
The HTTP API also accepts requests in JSON format. For queries you have the keysquery
and variables
. The JSON format is required to set
GraphQL Variables with the HTTP API.
This query: