Jorge Bay Gondra

We've just released version 4.0 of the DataStax Node.js Driver for Apache Cassandra and version 2.0 of the DataStax Enterprise Node.js Driver.

Let's have a look at some of the noteworthy features and changes in these releases.

<h2>Request Logging and Tracking</h2>

The driver now exposes a <a href="https://docs.datastax.com/en/developer/nodejs-driver/latest/features/logging/#tracking-query-latency-and-size">RequestLogger</a> that allows tracking requests which are considered slow and/or large based on your defined thresholds of size and time.

This feature is enabled by providing an instance of <code>RequestLogger</code> when creating the <code>Client</code>:

<code>const requestTracker = new cassandra.tracker.RequestLogger({ slowThreshold: 1000 }); 
const client = new Client({ contactPoints, localDataCenter, requestTracker }); </code>

You can subscribe to <code>'slow'</code>, <code>'large'</code>, <code>'normal'</code> and <code>'failure'</code> events using the emitter object instance:

<code>requestTracker.emitter.on('slow', message =&gt; console.log(message)); </code>

An example message would be:

<code>[10.1.1.1:9042] Slow request, took 1305 ms (request size 35 bytes / response size 1 KB): SELECT col1, col2 FROM table1 WHERE id = ? [1] </code>

Additionally, you can provide your own tracker by implementing the <code>RequestTracker</code> interface. Check out the <a href="https://docs.datastax.com/en/developer/nodejs-driver/latest/features/logging/#tracking-query-latency-and-size">documentation for more information</a>.

<h2>Object Mapper</h2>

We introduced an Object Mapper in the driver package. This new Object Mapper lets you interact with your data like you would interact with a set of documents, we've dedicated a separate <a href="https://academy.datastax.com/content/introducing-datastax-nodejs-mapper-apache-cassandra">blog post for the Mapper that goes over the features of this new driver component.</a>

<h2>New Default Load-Balancing Policy for DataStax Enterprise</h2>

The <a href="https://docs.datastax.com/en/developer/nodejs-driver-dse/latest/">DSE driver</a> used a dedicated load-balancing policy that behaved very much like the <code>TokenAwarePolicy</code>, distributing the load between replicas in a random fashion, with additional logic to route graph queries.

Using a randomized scheme has proven to successfully balance the load uniformly in a distributed system, without requiring any additional communication from components, loading server nodes almost equally.

In the case of DataStax Enterprise, as not all queries requires the same effort from the server coordinator, and a coordinator might be undergoing <a href="https://docs.datastax.com/en/dse/6.0/dse-arch/datastax_enterprise/dbInternals/dbIntHowDataMaintain.html">a task that consumes more resources</a>, we can expect for the incoming requests to take different times to complete and server-side request queues to be of different sizes.

We looked for ways to better distribute the queries from the client side to minimize completion time of the operations. After experimenting with different algorithms using different workloads and scenarios, we found that selecting the coordinator based on an internal client-level signal from two random replicas, as defined in the paper <a href="https://www.eecs.harvard.edu/~michaelm/postscripts/mythesis.pdf">The Power of Two Choices in Randomized Load Balancing</a>, proved to effectively improve overall latency behaviour and reduce long latency tail.

As a result, the driver now selects the replica with less in-flight requests from two random replicas. Additionally, the load-balancing policy detects replicas that are unresponsive and de-prioritize them from the query plan.

<h2>JavaScript primitive type BigInt Support</h2>

Node.js runtime added support for arbitrary-precision integers using the <a href="https://developers.google.com/web/updates/2018/05/bigint">new ECMAScript <code>BigInt</code> type</a> on version 10. On the driver side, you can now use JavaScript <code>BigInt</code> type <a href="https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/numerical/">to represent CQL <code>bigint</code> (64-bit signed long) and/or <code>varint</code> (arbitrary-precision integer) types</a>.

To enable it, you must specify it in the <code>ClientOptions</code>:

<code>const client = new Client({ 
&nbsp; &nbsp;contactPoints, 
&nbsp; &nbsp;localDataCenter, 
&nbsp; &nbsp;encoding: { 
&nbsp; &nbsp;&nbsp; &nbsp;useBigIntAsLong: true, 
&nbsp; &nbsp;&nbsp; &nbsp;useBigIntAsVarint: true 
&nbsp; &nbsp;} 
}); </code>

<h2>Metrics API</h2>

We exposed several internal driver metrics in the form of counters in 2 different ways: 1) A default implementation which leverages the Node.js events API to expose different counter increments and push it in your existing application metrics toolkit; and 2) a <code>ClientMetrics</code> <a href="https://docs.datastax.com/en/developer/nodejs-driver/latest/api/module.metrics/interface.ClientMetrics/">interface</a> that can be used by metrics libraries, service providers and the community to implement support for existing toolkits like <a href="https://github.com/mikejihbe/metrics">metrics</a>, <a href="https://github.com/dbader/node-datadog-metrics">datadog</a>, <a href="https://github.com/siimon/prom-client">prometheus</a>, <a href="https://github.com/yaorg/node-measured">measured</a>, …

To use the event-based implementation, you can subscribe to <code>DefaultMetrics</code> 'increment' events, for example:

<code>client.metrics.responses.success.on('increment', () =&gt; driverResponsesCounter.inc()); </code>

<code>client.metrics.errors.clientTimeout.on('increment', () =&gt; driverClientTimeoutCounter.inc()); </code>

<code>client.metrics.speculativeExecutions.on('increment', () =&gt; driverSpecExecsCounter.inc()); </code>

You can check out the available <a href="https://docs.datastax.com/en/developer/nodejs-driver/latest/api/module.metrics/class.DefaultMetrics/">metrics on the API docs</a>.

<h2>Local Data Center Name Is Now a Required Setting</h2>

Previously, when a local data center (DC) was not provided a DC-aware load-balancing policy, the driver used to infer the local data center used from the provided contact points. In the case the user provided contact points from multiple DCs the driver defined one of the them as local, depending on which contact point was attempted first. This behaviour can lead to unexpected connections and traffic to a remote data center.

In this new version of the driver, we took the opportunity to make the local data center an explicit setting. The driver will not attempt to infer it when it was not defined, throwing an error instead.

To specify the local data center, you set it at <code>ClientOptions</code> level alongside your contact points:

<code>const client = new Client({ contactPoints, localDataCenter: 'datacenter1' }) </code>

If you are using a single DC setup for testing/staging environment, the default DC name for Apache Cassandra deployments is <code>'datacenter1'</code> and <code>'Cassandra'</code> for DSE default single DC installs.

If you already specify the local DC at the load-balancing policy level, it will continue to work the same way.

<h2>Retry Policy and Query Idempotency</h2>

The <code>RetryPolicy</code> is not engaged anymore when a query errors with a <code>WriteTimeoutException</code> or request error and the <a href="https://docs.datastax.com/en/dse/6.7/dse-dev/datastax_enterprise/appDevGuide/driversQueryIdempotence.html">query was not idempotent</a>.

In order to control the possibility of retrying when a timeout/error is encountered, you must mark the query as idempotent. You can define it at <code>QueryOptions</code> level when calling the execution methods.

<code>client.execute(query, params, { prepare: true, isIdempotent: true }) </code>

Additionally, you can define the default idempotence for all executions when creating the <code>Client</code> instance:

<code>const client = new Client({ contactPoints, localDataCenter, queryOptions: { 
&nbsp; &nbsp;isIdempotent: true 
}}) </code>

<h2>Upgrade Information and Conclusion</h2>

Releasing a major version allowed us to improve the API and remove misfeatures. As a result we made some breaking changes.

You can visit the <a href="https://github.com/datastax/nodejs-driver/blob/master/CHANGELOG.md">upgrade guide for the Apache Cassandra Driver</a> and the <a href="https://docs.datastax.com/en/developer/nodejs-driver-dse/latest/changelog/">upgrade guide for the DSE Driver</a> for the full list of breaking changes. As a rule of thumb, if you are not using custom policies you only have to consider the two changes mentioned above:

<ul>
	<li>Specifying the local data center name is now required.</li>
	<li>You should mark your idempotent queries as such, if you want to enable query retrying.</li>
</ul>

We hope you enjoy the new features in this new major version of the driver. Thanks again to all who contributed code to the driver, wrote documentation, made feature requests and reported bugs. We encourage you to stay involved:

<ul>
	<li>Mailing List: <a href="https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user">https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user</a></li>
	<li>Review and contribute source code: <a href="https://github.com/datastax/nodejs-driver">https://github.com/datastax/nodejs-driver</a></li>
	<li>Report issues and discuss new features on JIRA: <a href="https://datastax-oss.atlassian.net/projects/NODEJS/issues">https://datastax-oss.atlassian.net/projects/NODEJS/issues</a></li>
</ul>

New Major Versions of the DataStax Node.js Drivers

Jorge Bay Gondra

Discover more

Share

Share

Request Logging and Tracking

Object Mapper

New Default Load-Balancing Policy for DataStax Enterprise

JavaScript primitive type BigInt Support

Metrics API

Local Data Center Name Is Now a Required Setting

Retry Policy and Query Idempotency

Upgrade Information and Conclusion

More Company

DataStax Acquires Langflow to Accelerate Generative AI Development

The Top 5 DataStax Stories from 2023

2023 Recap: Data = AI

DataStax Astra DB Nabs Three Prestigious 2023 TrustRadius “Best of” Awards, Dominates the Vector Databases Category

One-stop Data API for Production GenAI