class Client

A Client holds connections to a Cassandra cluster, allowing it to be queried. Each Client instance maintains multiple connections to the cluster nodes, provides policies to choose which node to use for each query, and handles retries for failed query (when it makes sense), etc…

Client instances are designed to be long-lived and usually a single instance is enough per application. As a given Client can only be “logged” into one keyspace at a time (where the “logged” keyspace is the one used by query if the query doesn’t explicitly use a fully qualified table name), it can make sense to create one client per keyspace used. This is however not necessary to query multiple keyspaces since it is always possible to use a single session with fully qualified table name in queries.

Global
This class is global

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.

Members

HostMap

hosts

Gets an associative array of cluster hosts.

String

keyspace

Gets the name of the active keyspace.

Metadata

metadata

Gets the schema and cluster metadata information.

Constructor

new

Client

(ClientOptions options)

Creates a new instance of Client.

Parameters:
Name Type Description
options ClientOptions

The options for this instance.

Methods

batch

(Array<string> or Array<{query, params}> queries, [QueryOptions options], ResultCallback callback)

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

Parameters:
Name Type Description
queries Array<string> or Array<{query, params}>

The queries to execute as an Array of strings or as an array of object containing the query and params
options optional QueryOptions
callback ResultCallback

Executes callback(err, result) when the batch was executed

connect

(function callback)

Tries to connect to one of the contactPoints and discover the nodes of the cluster.

If the Client is already connected, it immediately invokes callback.

Parameters:
Name Type Description
callback function

The callback is invoked when the pool is connected (or at least 1 connected and the rest failed to connect) or it is not possible to connect

eachRow

(String query, [Array or Object params], [QueryOptions options], function rowCallback, [function callback])

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 Description
query String

The query to execute
params optional Array or Object

Array of parameter values or an associative array (object) containing parameter names as keys and its value
options optional QueryOptions
rowCallback function

Executes rowCallback(n, row) per each row received, where n is the row index and row is the current Row.
callback optional function

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 this callback will be invoked when all rows in the following page has been retrieved.

execute

(String query, [Array or Object params], [QueryOptions options], ResultCallback callback)

Executes a query on an available connection.

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

Parameters:
Name Type Description
query String

The query to execute
params optional Array or Object

Array of parameter values or an associative array (object) containing parameter names as keys and its value
options optional QueryOptions
callback ResultCallback

Executes callback(err, result) when finished

getReplicas

(String keyspace, Buffer token)

Gets the host list representing the replicas that contain such partition.

Parameters:
Name Type Description
keyspace String
token Buffer
Returns:
Type Description
Array

shutdown

([function callback])

Closes all connections to all hosts

Parameters:
Name Type Description
callback optional function

stream

(String query, [Array or Object params], [QueryOptions options], [function callback])

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 Description
query String

The query to prepare and execute
params optional Array or Object

Array of parameter values or an associative array (object) containing parameter names as keys and its value
options optional QueryOptions
callback optional function

executes callback(err) after all rows have been received or if there is an error
Returns:
Type Description
types.ResultStream