Merge pull request #18 from dgraph-io/readonly/besteffort

Needed for Ratel #104 - Added readOnly and bestEffort options to query

Author: Aelbannan

README.md

@@ -14,20 +14,21 @@ and understand how to run and work with Dgraph.
 
 ## Table of contents
 
-- [Install](#install)
-- [Quickstart](#quickstart)
-- [Using a client](#using-a-client)
-  - [Create a client](#create-a-client)
-  - [Alter the database](#alter-the-database)
-  - [Create a transaction](#create-a-transaction)
-  - [Run a mutation](#run-a-mutation)
-  - [Run a query](#run-a-query)
-  - [Commit a transaction](#commit-a-transaction)
-  - [Check request latency](#check-request-latency)
-  - [Debug mode](#debug-mode)
-- [Development](#development)
-  - [Building the source](#building-the-source)
-  - [Running tests](#running-tests)
+  - [Install](#install)
+  - [Quickstart](#quickstart)
+  - [Using a client](#using-a-client)
+    - [Create a client](#create-a-client)
+    - [Login into Dgraph](#login-into-dgraph)
+    - [Alter the database](#alter-the-database)
+    - [Create a transaction](#create-a-transaction)
+    - [Run a mutation](#run-a-mutation)
+    - [Run a query](#run-a-query)
+    - [Commit a transaction](#commit-a-transaction)
+    - [Check request latency](#check-request-latency)
+    - [Debug mode](#debug-mode)
+  - [Development](#development)
+    - [Building the source](#building-the-source)
+    - [Running tests](#running-tests)
 
 ## Install
 
@@ -148,6 +149,16 @@ try {
 }
 ```
 
+You can make queries read-only and best effort by passing ```options``` to ```DgraphClient#newTxn```. For example:
+
+```js
+const options = { readOnly: true, bestEffort: true };
+const res = await dgraphClient.newTxn(options).query(query);
+```
+
+Read-only transactions are useful to increase read speed because they can circumvent the usual consensus protocol. Best effort queries can also increase read speed in read bound system. Please note that best effort requires readonly.
+
+
 ### Run a mutation
 
 `Txn#mutate(Mutation)` runs a mutation. It takes in a `Mutation` object, which
@@ -182,6 +193,7 @@ mutation must be immediately committed.
 await txn.mutate({ setJson: p, commitNow: true });
 ```
 
+
 ### Run a query
 
 You can run a query by calling `Txn#query(string)`. You will need to pass in a
@@ -229,6 +241,7 @@ Number of people named "Alice": 1
 Alice
 ```
 
+
 ### Commit a transaction
 
 A transaction can be committed using the `Txn#commit()` method. If your transaction

lib/client.d.ts

@@ -1,6 +1,6 @@
 import { DgraphClientStub } from "./clientStub";
 import { Txn } from "./txn";
-import { Operation, Payload, UiKeywords } from "./types";
+import { Operation, Payload, UiKeywords, TxnOptions } from "./types";
 export declare class DgraphClient {
     private readonly clients;
     private debugMode;
@@ -11,7 +11,7 @@ export declare class DgraphClient {
     alter(op: Operation): Promise<Payload>;
     login(userid: string, password: string): Promise<boolean>;
     logout(): void;
-    newTxn(): Txn;
+    newTxn(options?: TxnOptions): Txn;
     setDebugMode(mode?: boolean): void;
     fetchUiKeywords(): Promise<UiKeywords>;
     debug(msg: string): void;

lib/client.js

@@ -1,9 +1,10 @@
 "use strict";
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
         function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
         function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : new P(function (resolve) { resolve(result.value); }).then(fulfilled, rejected); }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
@@ -82,8 +83,8 @@ var DgraphClient = (function () {
         this.debug("Logout");
         this.clients.forEach(function (c) { return c.logout(); });
     };
-    DgraphClient.prototype.newTxn = function () {
-        return new txn_1.Txn(this);
+    DgraphClient.prototype.newTxn = function (options) {
+        return new txn_1.Txn(this, options);
     };
     DgraphClient.prototype.setDebugMode = function (mode) {
         if (mode === void 0) { mode = true; }

lib/clientStub.js

@@ -11,10 +11,11 @@ var __assign = (this && this.__assign) || function () {
     return __assign.apply(this, arguments);
 };
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
         function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
         function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : new P(function (resolve) { resolve(result.value); }).then(fulfilled, rejected); }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
@@ -139,6 +140,18 @@ var DgraphClientStub = (function () {
                     value: "true",
                 });
             }
+            if (req.readOnly) {
+                params.push({
+                    key: "ro",
+                    value: "true",
+                });
+            }
+            if (req.bestEffort) {
+                params.push({
+                    key: "be",
+                    value: "true",
+                });
+            }
             if (params.length > 0) {
                 url += "?";
                 url += params.map(function (_a) {
@@ -258,7 +271,7 @@ var DgraphClientStub = (function () {
                                     version: "1.0.x",
                                 }];
                         }
-                        return [2, __assign({}, JSON.parse(text), { health: "OK" })];
+                        return [2, __assign(__assign({}, JSON.parse(text)), { health: "OK" })];
                 }
             });
         });

lib/txn.d.ts

@@ -1,11 +1,11 @@
 import { DgraphClient } from "./client";
-import { Assigned, Mutation, Response } from "./types";
+import { Assigned, Mutation, Response, TxnOptions } from "./types";
 export declare class Txn {
     private readonly dc;
     private readonly ctx;
     private finished;
     private mutated;
-    constructor(dc: DgraphClient);
+    constructor(dc: DgraphClient, options?: TxnOptions);
     query(q: string, options?: {
         debug?: boolean;
     }): Promise<Response>;

lib/txn.js

@@ -1,9 +1,10 @@
 "use strict";
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
         function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
         function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : new P(function (resolve) { resolve(result.value); }).then(fulfilled, rejected); }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
@@ -38,14 +39,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var errors_1 = require("./errors");
 var util_1 = require("./util");
 var Txn = (function () {
-    function Txn(dc) {
+    function Txn(dc, options) {
         this.finished = false;
         this.mutated = false;
         this.dc = dc;
+        if (options && options.bestEffort && !options.readOnly) {
+            this.dc.debug('Best effort only works with read-only queries.');
+            throw errors_1.ERR_ABORTED;
+        }
         this.ctx = {
             start_ts: 0,
             keys: [],
             preds: [],
+            readOnly: options && options.readOnly,
+            bestEffort: options && options.bestEffort
         };
     }
     Txn.prototype.query = function (q, options) {
@@ -67,6 +74,8 @@ var Txn = (function () {
                             startTs: this.ctx.start_ts,
                             timeout: this.dc.getQueryTimeout(),
                             debug: options.debug,
+                            readOnly: this.ctx.readOnly,
+                            bestEffort: this.ctx.bestEffort
                         };
                         if (vars !== undefined) {
                             varsObj_1 = {};

lib/types.d.ts

@@ -14,6 +14,8 @@ export interface Request {
     startTs?: number;
     timeout?: number;
     debug?: boolean;
+    readOnly?: boolean;
+    bestEffort?: boolean;
 }
 export interface Response {
     data: {};
@@ -59,9 +61,15 @@ export interface TxnContext {
     aborted?: boolean | null;
     keys?: string[] | null;
     preds?: string[] | null;
+    readOnly: boolean;
+    bestEffort: boolean;
 }
 export interface Latency {
     parsing_ns?: number | null;
     processing_ns?: number | null;
     encoding_ns?: number | null;
 }
+export interface TxnOptions {
+    readOnly?: boolean;
+    bestEffort?: boolean;
+}

src/client.ts

@@ -1,7 +1,7 @@
 import { DgraphClientStub } from "./clientStub";
 import { ERR_NO_CLIENTS } from "./errors";
 import { Txn } from "./txn";
-import { Operation, Payload, UiKeywords } from "./types";
+import { Operation, Payload, UiKeywords, TxnOptions } from "./types";
 import { stringifyMessage } from "./util";
 
 /**
@@ -76,8 +76,8 @@ export class DgraphClient {
     /**
      * newTxn creates a new transaction.
      */
-    public newTxn(): Txn {
-        return new Txn(this);
+    public newTxn(options?: TxnOptions): Txn {
+        return new Txn(this, options);
     }
 
     /**

src/clientStub.ts

@@ -109,6 +109,18 @@ export class DgraphClientStub {
               value: "true",
             });
           }
+          if (req.readOnly) {
+            params.push({
+              key: "ro",
+              value: "true",
+            });
+          }
+          if (req.bestEffort) {
+            params.push({
+              key: "be",
+              value: "true",
+            });
+          }
           if (params.length > 0) {
               url += "?";
               url += params.map(

src/errors.ts

@@ -1,6 +1,7 @@
 export const ERR_NO_CLIENTS = new Error("No clients provided in DgraphClient constructor");
 export const ERR_FINISHED = new Error("Transaction has already been committed or discarded");
 export const ERR_ABORTED = new Error("Transaction has been aborted. Please retry");
+export const ERR_BEST_EFFORT_REQUIRED_READ_ONLY = new Error("Best effort only works for read-only queries");
 
 /**
  * CustomError is base class used for defining custom error classes.