Class: Client

Client

Extends the Client class of the DataStax Node.js Driver for Apache Cassandra to provide DSE-specific features support such as Graph, geospatial types representation and authentication, in addition to the inherited Client methods used to execute CQL queries (execute(), eachRow(), stream()).

Client instances are designed to be long-lived and usually a single instance is enough per application.

Constructor

new Client(options)

Creates a new Client instance.
Parameters:
Name Type Description
options DseClientOptions The options used to create the client instance.
Examples

Creating a new client instance

const dse = require('dse-driver');
const client = new dse.Client({
  contactPoints: [ 'host1', 'host2' ]
});

Connecting to the cluster

const client = new dse.Client({ contactPoints: [ 'host1', 'host2' ] });
client.connect().then(function () {
  console.log('Connected to cluster with %d host(s): %j', client.hosts.length, client.hosts.keys());
});

Executing a query with the promise-based API and async/await

// calling #execute() can be made without previously calling #connect(), as internally
// it will ensure it's connected before attempting to execute the query
const result = await client.execute('SELECT key FROM system.local');
const row = result.first();
console.log(row['key']);

Executing a query using callbacks

client.execute('SELECT key FROM system.local', function (err, result) {
  if (err) return console.error(err);
  const row = result.first();
  console.log(row['key']);
});

Extends

  • cassandra.Client

Members

hosts :HostMap

Gets an associative array of cluster hosts.
Type:

keyspace :String

Gets the name of the active keyspace.
Type:
  • String

metadata :Metadata

Gets the schema and cluster metadata information.
Type:
  • Metadata

Methods

batch(queries, optionsopt, callbackopt)

Executes batch of queries on an available connection to a host.

If a callback is provided, it will invoke the callback when the execution completes. Otherwise, it will return a Promise.

Parameters:
Name Type Attributes Description
queries Array.<string> | Array.<{query, params}> The queries to execute as an Array of strings or as an array of object containing the query and params
options QueryOptions <optional>
callback ResultCallback <optional>
 Executes callback(err, result) when the batch was executed

connect(callbackopt)

Tries to connect to one of the contactPoints and discovers the rest the nodes of the cluster.

If a callback is provided, it will invoke the callback when the client is connected. Otherwise, it will return a Promise.

If the Client is already connected, it invokes callback immediately (when provided) or the promise is fulfilled .

Parameters:
Name Type Attributes Description
callback function <optional>
 The callback is invoked when the pool is connected it failed to connect.
Examples

Callback-based execution

client.connect(function (err) {
  if (err) return console.error(err);
  console.log('Connected to cluster with %d host(s): %j', client.hosts.length, client.hosts.keys());
});

Promise-based execution

await client.connect();

eachRow(query, paramsopt, optionsopt, rowCallback, callbackopt)

Executes the query and calls rowCallback for each row as soon as they are received. Calls final callback after all rows have been sent, or when there is an error.

The query can be prepared (recommended) or not depending on QueryOptions.prepare flag. Retries on multiple hosts if needed.

Parameters:
Name Type Attributes Description
query String The query to execute
params Array | Object <optional>
 Array of parameter values or an associative array (object) containing parameter names as keys and its value.
options QueryOptions <optional>
rowCallback function Executes rowCallback(n, row) per each row received, where n is the row index and row is the current Row.
callback function <optional>
 Executes callback(err, result) after all rows have been received.

When dealing with paged results, ResultSet#nextPage() method can be used to retrieve the following page. In that case, rowCallback() will be again called for each row and the final callback will be invoked when all rows in the following page has been retrieved.

Examples

Using per-row callback and arrow functions

client.eachRow(query, params, { prepare: true }, (n, row) => console.log(n, row), err => console.error(err));

Overloads

client.eachRow(query, rowCallback);
client.eachRow(query, params, rowCallback);
client.eachRow(query, params, options, rowCallback);
client.eachRow(query, params, rowCallback, callback);
client.eachRow(query, params, options, rowCallback, callback);

execute(query, paramsopt, optionsopt, callbackopt)

Executes a query on an available connection.

If a callback is provided, it will invoke the callback when the execution completes. Otherwise, it will return a Promise.

The query can be prepared (recommended) or not depending on QueryOptions.prepare flag.

Some executions failures can be handled transparently by the driver, according to the RetryPolicy defined at ClientOptions or QueryOptions level.

Parameters:
Name Type Attributes Description
query String The query to execute.
params Array | Object <optional>
 Array of parameter values or an associative array (object) containing parameter names as keys and its value.
options QueryOptions <optional>
 The query options for the execution.
callback ResultCallback <optional>
 Executes callback(err, result) when execution completed. When not defined, the method will return a promise.
See:
Examples

Callback-based API

const query = 'SELECT name, email FROM users WHERE id = ?';
client.execute(query, [ id ], { prepare: true }, function (err, result) {
  assert.ifError(err);
  const row = result.first();
  console.log('%s: %s', row.name, row.email);
});

Promise-based API, using async/await

const query = 'SELECT name, email FROM users WHERE id = ?';
const result = await client.execute(query, [ id ], { prepare: true });
const row = result.first();
console.log('%s: %s', row.name, row.email);

executeGraph(query, parametersopt, optionsopt, callbackopt)

Executes a graph query.

If a callback is provided, it will invoke the callback when the execution completes. Otherwise, it will return a Promise.

Parameters:
Name Type Attributes Description
query String The gremlin query.
parameters Object | null <optional>
 An associative array containing the key and values of the parameters.
options GraphQueryOptions | null <optional>
 The graph query options.
callback function <optional>
 Function to execute when the response is retrieved, taking two arguments: err and result. When not defined, the method will return a promise.
See:
Examples

Promise-based API, using async/await

const result = await client.executeGraph('g.V()');
// Get the first item (vertex, edge, scalar value, ...)
const vertex = result.first();
console.log(vertex.label);

Callback-based API

const result = await client.executeGraph('g.V()', function (err, result) {
  const vertex = result.first();
  console.log(vertex.label);
});

Using result.forEach()

const result = await client.executeGraph('g.V().hasLabel("person")');
result.forEach(function(vertex) {
  console.log(vertex.type); // vertex
  console.log(vertex.label); // person
});

Using ES6 for...of

const result = await client.executeGraph('g.E()');
for (let edge of result) {
  console.log(edge.label); // created
});

getReplicas(keyspace, token) → {Array}

Gets the host list representing the replicas that contain such partition.
Parameters:
Name Type Description
keyspace String
token Buffer
Returns:
Type
Array

shutdown(callbackopt)

Closes all connections to all hosts.

If a callback is provided, it will invoke the callback when the client is disconnected. Otherwise, it will return a Promise.

Parameters:
Name Type Attributes Description
callback function <optional>
 Optional callback to be invoked when finished closing all connections.

stream(query, paramsopt, optionsopt, callbackopt) → {types.ResultStream}

Executes the query and pushes the rows to the result stream as soon as they received. Calls callback after all rows have been sent, or when there is an error.

The stream is a Readable Streams2 object that contains the raw bytes of the field value. It can be piped downstream and provides automatic pause/resume logic (it buffers when not read).

The query can be prepared (recommended) or not depending on QueryOptions.prepare flag. Retries on multiple hosts if needed.

Parameters:
Name Type Attributes Description
query String The query to prepare and execute
params Array | Object <optional>
 Array of parameter values or an associative array (object) containing parameter names as keys and its value
options QueryOptions <optional>
callback function <optional>
 executes callback(err) after all rows have been received or if there is an error
Returns:
Type
types.ResultStream

Events

hostAdd

Emitted when a new host is added to the cluster.
  • Host The host being added.

hostDown

Emitted when a host in the cluster changed status from up to down.
  • host The host that changed the status.

hostRemove

Emitted when a host is removed from the cluster
  • Host The host being removed.

hostUp

Emitted when a host in the cluster changed status from down to up.
  • host The host that changed the status.