Dgraphium Client (gRPC)

Dgraph client compatible with Dgraphium Core (QueryBuilder). It's simply a customized version of dgraph-js which simply adds support for Query object.

docs bellow are copied from dgraph-js:

Table of contents

• Install
• Supported Versions
• Quickstart
• Using a Client
  • Creating a Client
  • Altering the Database
  • Creating a Transaction
  • Running a Mutation
  • Running a Query
  • Running an Upsert: Query + Mutation
  • Running a Conditional Upsert
  • Committing a Transaction
  • Cleanup Resources
  • Debug mode
• Examples
• Development
  • Building the source
  • Running tests

Install

Install using npm:

npm install @dgraphium/client @dgraphium/core grpc

or yarn:

yarn add @dgraphium/client @dgraphium/core grpc
# If you are using Typescript, you might also need:
# yarn add @types/google-protobuf @types/protobufjs --dev

Using a Client

Creating a Client

A DgraphClient object can be initialised by passing it a list of DgraphClientStub 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.

const dgraph = require("@dgraphium/client");
const grpc = require("grpc");

const clientStub = new dgraph.DgraphClientStub(
  // addr: optional, default: "localhost:9080"
  "localhost:9080",
  // credentials: optional, default: grpc.credentials.createInsecure()
  grpc.credentials.createInsecure(),
);
const dgraphClient = new dgraph.DgraphClient(clientStub);

To facilitate debugging, debug mode can be enabled for a client.

Altering the Database

To set the schema, create an Operation object, set the schema and pass it to DgraphClient#alter(Operation) method.

const schema = "name: string @index(exact) .";
const op = new dgraph.Operation();
op.setSchema(schema);
await dgraphClient.alter(op);

Starting Dgraph version 20.03.0, indexes can be computed in the background. You can set setRunInBackground field of the Operation object to true before passing it to the DgraphClient#alter(Operation) method. You can find more details here.

const schema = "name: string @index(exact) .";
const op = new dgraph.Operation();
op.setSchema(schema);
op.setRunInBackground(true);
await dgraphClient.alter(op);

NOTE: Many of the examples here use the await keyword which requires async/await support which is available on Node.js >= v7.6.0. For prior versions, the expressions following await can be used just like normal Promise:

dgraphClient.alter(op)
    .then(function(result) { ... }, function(err) { ... })

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.

// Drop all data including schema from the Dgraph instance. This is useful
// for small examples such as this, since it puts Dgraph into a clean
// state.
const op = new dgraph.Operation();
op.setDropAll(true);
await dgraphClient.alter(op);

Creating a Transaction

To create a transaction, call DgraphClient#newTxn() method, which returns a new Txn object. This operation incurs no network overhead.

It is good practise to call Txn#discard() in a finally block after running the transaction. Calling Txn#discard() after Txn#commit() is a no-op and you can call Txn#discard() multiple times with no additional side-effects.

const txn = dgraphClient.newTxn();
try {
  // Do something here
  // ...
} finally {
  await txn.discard();
  // ...
}

To create a read-only transaction, set readOnly boolean to true while calling DgraphClient#newTxn() method. Read-only transactions cannot contain mutations and trying to call Txn#mutate() or Txn#commit() will result in an error. Calling Txn.Discard() will be a no-op.

You can optionally set the bestEffort boolean to true. This may yield improved latencies in read-bound workloads where linearizable reads are not strictly needed.

const txn = dgraphClient.newTxn({
  readOnly: true,
  bestEffort: false
});
// ...
const res = await txn.queryWithVars(query, vars);

Running a Mutation

Txn#mutate(Mutation) runs a mutation. It takes in a Mutation object, which provides two main ways to set data: JSON and RDF N-Quad. You can choose whichever way is convenient.

We define a person object to represent a person and use it in a Mutation object.

// Create data.
const p = {
    name: "Alice",
};

// Run mutation.
const mu = new dgraph.Mutation();
mu.setSetJson(p);
await txn.mutate(mu);

For a more complete example with multiple fields and relationships, look at the [simple] project in the examples folder.

Sometimes, you only want to commit a mutation, without querying anything further. In such cases, you can use Mutation#setCommitNow(true) to indicate that the mutation must be immediately committed.

Mutation#setIgnoreIndexConflict(true) can be applied on a Mutation object to not run conflict detection over the index, which would decrease the number of transaction conflicts and aborts. However, this would come at the cost of potentially inconsistent upsert operations.

Mutation can be run using txn.doRequest as well.

const mu = new dgraph.Mutation();
mu.setSetJson(p);

const req = new dgraph.Request();
req.setCommitNow(true);
req.setMutationsList([mu]);

await txn.doRequest(req);

Running a Query

You can run a query by calling Txn#query(string | Query). You will need to pass in a GraphQL+- query string or Query object. If you want to pass an additional map of any variables that you might want to set in the query, call Txn#queryWithVars(string | Query, object) with the variables object as the second argument.

If you pass in Query object that has graphql variables(Param), those variables will be automatically included. To override them, run Txn#queryWithVars(Query, overridesObject).

The response would contain the method Response#getJSON(), which returns the response JSON.

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

• With QueryBuilder:

  const { query, params } = require('@dgraphium/core');
  const { eq } = require('@dgraphium/core/operators');
  
  const allQuery = query()
    .name('all')
    .func(eq('name', params.string('Alice').name('a')))
    .project({ name: 1 })
    .build();
  
  const res = await dgraphClient.newTxn().query(allQuery);

  to override '$a' and change it from 'Alice' to 'Bob' (this way query can be reused):

  const res = await dgraphClient.newTxn().queryWithVars(
    allQuery,
    { '$a': 'Bob' }
  );

• Without QueryBuilder:

  // Run query.
  const query = `query all($a: string) {
    all(func: eq(name, $a))
    {
      name
    }
  }`;
  const vars = { $a: "Alice" };
  const res = await dgraphClient.newTxn().queryWithVars(query, vars);

This is same for both methods

const ppl = res.getJson();

// Print results.
console.log(`Number of people named "Alice": ${ppl.all.length}`);
ppl.all.forEach((person) => console.log(person.name));

This should print:

Number of people named "Alice": 1
Alice

You can also use txn.doRequest function to run the query.

const req = new dgraph.Request();
req.setQueryWithVars(allQuery, { '$a': 'Alice' }); // query can be (string | Query)

const res = await txn.doRequest(req);
console.log(JSON.stringify(res.getJson()));

Running an Upsert: Query + Mutation

The txn.doRequest function allows you to run upserts consisting of one query and one mutation. Query variables could be defined and can then be used in the mutation. You can also use the txn.doRequest function to perform just a query or a mutation.

To know more about upsert, we highly recommend going through the docs at https://docs.dgraph.io/mutations/#upsert-block.

const query = `
  query {
      user as var(func: eq(email, "[email protected]"))
  }`

const mu = new dgraph.Mutation();
mu.setSetNquads(`uid(user) <email> "[email protected]" .`);

const req = new dgraph.Request();
req.setQuery(query);
req.setMutationsList([mu]);
req.setCommitNow(true);

// Upsert: If wrong_email found, update the existing data
// or else perform a new mutation.
await dgraphClient.newTxn().doRequest(req);

Running a Conditional Upsert

The upsert block 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.

const query = `
  query {
      user as var(func: eq(email, "[email protected]"))
  }`

const mu = new dgraph.Mutation();
mu.setSetNquads(`uid(user) <email> "[email protected]" .`);
mu.setCond(`@if(eq(len(user), 1))`);

const req = new dgraph.Request();
req.setQuery(query);
req.addMutations(mu);
req.setCommitNow(true);

await dgraphClient.newTxn().doRequest(req);

Committing a Transaction

A transaction can be committed using the Txn#commit() 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.

const txn = dgraphClient.newTxn();
try {
  // ...
  // Perform any number of queries and mutations
  // ...
  // and finally...
  await txn.commit();
} catch (e) {
  if (e === dgraph.ERR_ABORTED) {
    // Retry or handle exception.
  } else {
    throw e;
  }
} finally {
  // Clean up. Calling this after txn.commit() is a no-op
  // and hence safe.
  await txn.discard();
}

Cleanup Resources

To cleanup resources, you have to call DgraphClientStub#close() individually for all the instances of DgraphClientStub.

const SERVER_ADDR = "localhost:9080";
const SERVER_CREDENTIALS = grpc.credentials.createInsecure();

// Create instances of DgraphClientStub.
const stub1 = new dgraph.DgraphClientStub(SERVER_ADDR, SERVER_CREDENTIALS);
const stub2 = new dgraph.DgraphClientStub(SERVER_ADDR, SERVER_CREDENTIALS);

// Create an instance of DgraphClient.
const dgraphClient = new dgraph.DgraphClient(stub1, stub2);

// ...
// Use dgraphClient
// ...

// Cleanup resources by closing all client stubs.
stub1.close();
stub2.close();

Debug mode

Debug mode can be used to print helpful debug messages while performing alters, queries and mutations. It can be set using theDgraphClient#setDebugMode(boolean?) method.

// Create a client.
const dgraphClient = new dgraph.DgraphClient(...);

// Enable debug mode.
dgraphClient.setDebugMode(true);
// OR simply dgraphClient.setDebugMode();

// Disable debug mode.
dgraphClient.setDebugMode(false);