# Table of Contents - [DataStax Enterprise Ruby Driver - Home](#datastax-enterprise-ruby-driver-home) - [DataStax Enterprise Ruby Driver - Features](#datastax-enterprise-ruby-driver-features) - [DataStax Enterprise Ruby Driver - Authentication](#datastax-enterprise-ruby-driver-authentication) - [DataStax Enterprise Ruby Driver - Geospatial Types](#datastax-enterprise-ruby-driver-geospatial-types) - [DataStax Enterprise Ruby Driver - Graph](#datastax-enterprise-ruby-driver-graph) - [DataStax Enterprise Ruby Driver - Dse](#datastax-enterprise-ruby-driver-dse) - [DataStax Enterprise Ruby Driver - API docs](#datastax-enterprise-ruby-driver-api-docs) - [DataStax Enterprise Ruby Driver - Changelog](#datastax-enterprise-ruby-driver-changelog) - [DataStax Enterprise Ruby Driver - Authentication](#datastax-enterprise-ruby-driver-authentication) - [DataStax Enterprise Ruby Driver - Home](#datastax-enterprise-ruby-driver-home) - [DataStax Enterprise Ruby Driver - Features](#datastax-enterprise-ruby-driver-features) - [DataStax Enterprise Ruby Driver - Geospatial Types](#datastax-enterprise-ruby-driver-geospatial-types) - [DataStax Enterprise Ruby Driver - Dse](#datastax-enterprise-ruby-driver-dse) - [DataStax Enterprise Ruby Driver - Graph](#datastax-enterprise-ruby-driver-graph) - [DataStax Enterprise Ruby Driver - API docs](#datastax-enterprise-ruby-driver-api-docs) - [DataStax Enterprise Ruby Driver - Authentication](#datastax-enterprise-ruby-driver-authentication) - [DataStax Enterprise Ruby Driver - Features](#datastax-enterprise-ruby-driver-features) - [DataStax Enterprise Ruby Driver - Geospatial Types](#datastax-enterprise-ruby-driver-geospatial-types) - [DataStax Enterprise Ruby Driver - Graph](#datastax-enterprise-ruby-driver-graph) - [DataStax Enterprise Ruby Driver - Home](#datastax-enterprise-ruby-driver-home) - [DataStax Enterprise Ruby Driver - Dse](#datastax-enterprise-ruby-driver-dse) - [DataStax Enterprise Ruby Driver - API docs](#datastax-enterprise-ruby-driver-api-docs) - [DataStax Enterprise PHP Driver - Building PHP Extension](#datastax-enterprise-php-driver-building-php-extension) - [DataStax Enterprise PHP Driver - Authentication](#datastax-enterprise-php-driver-authentication) - [DataStax Enterprise PHP Driver - Home](#datastax-enterprise-php-driver-home) - [DataStax Enterprise PHP Driver - Features](#datastax-enterprise-php-driver-features) - [DataStax Enterprise PHP Driver - Geospatial types](#datastax-enterprise-php-driver-geospatial-types) - [DataStax Enterprise PHP Driver - Graph](#datastax-enterprise-php-driver-graph) - [DataStax Enterprise PHP Driver - Core](#datastax-enterprise-php-driver-core) - [DataStax Enterprise PHP Driver - DateRange](#datastax-enterprise-php-driver-daterange) - [DataStax Enterprise PHP Driver - Sessions](#datastax-enterprise-php-driver-sessions) - [DataStax Enterprise PHP Driver - Migration](#datastax-enterprise-php-driver-migration) - [DataStax Enterprise PHP Driver - Dse](#datastax-enterprise-php-driver-dse) - [DataStax Enterprise PHP Driver - API docs](#datastax-enterprise-php-driver-api-docs) - [DataStax Enterprise PHP Driver - Home](#datastax-enterprise-php-driver-home) - [DataStax Enterprise PHP Driver - Dse](#datastax-enterprise-php-driver-dse) - [DataStax Enterprise PHP Driver - Building PHP Extension](#datastax-enterprise-php-driver-building-php-extension) - [DataStax Enterprise PHP Driver - Authentication](#datastax-enterprise-php-driver-authentication) - [DataStax Enterprise PHP Driver - Features](#datastax-enterprise-php-driver-features) - [DataStax Enterprise PHP Driver - Sessions](#datastax-enterprise-php-driver-sessions) - [DataStax Enterprise PHP Driver - Graph](#datastax-enterprise-php-driver-graph) - [DataStax Enterprise PHP Driver - Geospatial types](#datastax-enterprise-php-driver-geospatial-types) - [DataStax Enterprise PHP Driver - Migration](#datastax-enterprise-php-driver-migration) - [DataStax Enterprise PHP Driver - Dse](#datastax-enterprise-php-driver-dse) - [DataStax Enterprise PHP Driver - API docs](#datastax-enterprise-php-driver-api-docs) - [DataStax Enterprise PHP Driver - Core](#datastax-enterprise-php-driver-core) - [DataStax Enterprise PHP Driver - Dse](#datastax-enterprise-php-driver-dse) - [Page Not Found | DataStax Docs](#page-not-found-datastax-docs) - [DataStax Node.js Driver - Batch statements](#datastax-node-js-driver-batch-statements) - [DataStax Node.js Driver - Authentication](#datastax-node-js-driver-authentication) - [DataStax Node.js Driver - Home](#datastax-node-js-driver-home) - [DataStax Node.js Driver - CQL data types to JavaScript types](#datastax-node-js-driver-cql-data-types-to-javascript-types) - [DataStax Node.js Driver - Address resolution](#datastax-node-js-driver-address-resolution) - [DataStax Node.js Driver - Features](#datastax-node-js-driver-features) - [DataStax Node.js Driver - Cluster and schema metadata](#datastax-node-js-driver-cluster-and-schema-metadata) - [DataStax Node.js Driver - Native protocol](#datastax-node-js-driver-native-protocol) - [DataStax Node.js Driver - Parameterized queries](#datastax-node-js-driver-parameterized-queries) - [DataStax Node.js Driver - Connection pooling](#datastax-node-js-driver-connection-pooling) - [DataStax Node.js Driver - Execution Profiles](#datastax-node-js-driver-execution-profiles) - [DataStax Node.js Driver - Graph support](#datastax-node-js-driver-graph-support) - [DataStax Node.js Driver - Mapper](#datastax-node-js-driver-mapper) - [DataStax Node.js Driver - Concurrent Execution API](#datastax-node-js-driver-concurrent-execution-api) - [DataStax Node.js Driver - Query timestamps](#datastax-node-js-driver-query-timestamps) - [DataStax Node.js Driver - Promise and callback-based API](#datastax-node-js-driver-promise-and-callback-based-api) - [DataStax Node.js Driver - Fetching large result sets](#datastax-node-js-driver-fetching-large-result-sets) - [DataStax Node.js Driver - Connecting to your DataStax Astra database using a secure connection bundle](#datastax-node-js-driver-connecting-to-your-datastax-astra-database-using-a-secure-connection-bundle) - [DataStax Node.js Driver - User-defined functions and aggregates](#datastax-node-js-driver-user-defined-functions-and-aggregates) - [DataStax Node.js Driver - Logging](#datastax-node-js-driver-logging) - [DataStax Node.js Driver - Geospatial types](#datastax-node-js-driver-geospatial-types) - [DataStax Node.js Driver - TLS/SSL](#datastax-node-js-driver-tls-ssl) - [DataStax Node.js Driver - Query warnings](#datastax-node-js-driver-query-warnings) - [DataStax Node.js Driver - auth](#datastax-node-js-driver-auth) - [DataStax Node.js Driver - types](#datastax-node-js-driver-types) - [DataStax Node.js Driver - Speculative query execution](#datastax-node-js-driver-speculative-query-execution) - [DataStax Node.js Driver - Tuning policies](#datastax-node-js-driver-tuning-policies) - [DataStax Node.js Driver - policies](#datastax-node-js-driver-policies) - [DataStax Node.js Driver - Frequently Asked Questions](#datastax-node-js-driver-frequently-asked-questions) - [DataStax Node.js Driver - Getting Started](#datastax-node-js-driver-getting-started) - [DataStax Node.js Driver - Upgrade Guide](#datastax-node-js-driver-upgrade-guide) - [DataStax Node.js Driver - Three simple rules for coding with the driver](#datastax-node-js-driver-three-simple-rules-for-coding-with-the-driver) - [DataStax Node.js Driver - Upgrading from the DSE Driver](#datastax-node-js-driver-upgrading-from-the-dse-driver) - [DataStax Node.js Driver - metadata](#datastax-node-js-driver-metadata) - [DataStax Node.js Driver - geometry](#datastax-node-js-driver-geometry) - [DataStax Node.js Driver - mapping](#datastax-node-js-driver-mapping) - [DataStax Node.js Driver - QueryOptions](#datastax-node-js-driver-queryoptions) - [DataStax Node.js Driver - ClientOptions](#datastax-node-js-driver-clientoptions) - [DataStax Node.js Driver - ResultCallback](#datastax-node-js-driver-resultcallback) - [DataStax Node.js Driver - errors](#datastax-node-js-driver-errors) - [DataStax Node.js Driver - concurrent](#datastax-node-js-driver-concurrent) - [DataStax Node.js Driver - datastax](#datastax-node-js-driver-datastax) - [DataStax Node.js Driver - Encoder](#datastax-node-js-driver-encoder) - [DataStax Node.js Driver - HostMap](#datastax-node-js-driver-hostmap) - [DataStax Node.js Driver - Host](#datastax-node-js-driver-host) - [DataStax Node.js Driver - TransitionalModePlainTextAuthenticator](#datastax-node-js-driver-transitionalmodeplaintextauthenticator) - [DataStax Node.js Driver - Address resolution](#datastax-node-js-driver-address-resolution) - [DataStax Node.js Driver - Connection pooling](#datastax-node-js-driver-connection-pooling) - [DataStax Node.js Driver - Batch statements](#datastax-node-js-driver-batch-statements) - [DataStax Node.js Driver - Client](#datastax-node-js-driver-client) - [DataStax Node.js Driver - ExecutionProfile](#datastax-node-js-driver-executionprofile) - [DataStax Node.js Driver - Parameterized queries](#datastax-node-js-driver-parameterized-queries) - [DataStax Node.js Driver - Native protocol](#datastax-node-js-driver-native-protocol) - [DataStax Node.js Driver - CQL data types to JavaScript types](#datastax-node-js-driver-cql-data-types-to-javascript-types) - [DataStax Node.js Driver - tracker](#datastax-node-js-driver-tracker) - [DataStax Node.js Driver - Query timestamps](#datastax-node-js-driver-query-timestamps) - [DataStax Node.js Driver - Cluster and schema metadata](#datastax-node-js-driver-cluster-and-schema-metadata) - [DataStax Node.js Driver - Fetching large result sets](#datastax-node-js-driver-fetching-large-result-sets) - [DataStax Node.js Driver - metrics](#datastax-node-js-driver-metrics) - [DataStax Node.js Driver - ExecutionOptions](#datastax-node-js-driver-executionoptions) - [DataStax Node.js Driver - Execution Profiles](#datastax-node-js-driver-execution-profiles) - [DataStax Node.js Driver - Query warnings](#datastax-node-js-driver-query-warnings) - [DataStax Node.js Driver - Promise and callback-based API](#datastax-node-js-driver-promise-and-callback-based-api) - [DataStax Node.js Driver - User-defined functions and aggregates](#datastax-node-js-driver-user-defined-functions-and-aggregates) - [DataStax Node.js Driver - auth](#datastax-node-js-driver-auth) - [DataStax Node.js Driver - Tuning policies](#datastax-node-js-driver-tuning-policies) - [DataStax Node.js Driver - policies](#datastax-node-js-driver-policies) - [DataStax Node.js Driver - Features](#datastax-node-js-driver-features) - [DataStax Node.js Driver - Concurrent Execution API](#datastax-node-js-driver-concurrent-execution-api) - [DataStax Node.js Driver - metadata](#datastax-node-js-driver-metadata) - [DataStax Node.js Driver - types](#datastax-node-js-driver-types) - [DataStax Node.js Driver - Address resolution](#datastax-node-js-driver-address-resolution) - [DataStax Node.js Driver - Authentication](#datastax-node-js-driver-authentication) - [DataStax Node.js Driver - Connecting to your DataStax Astra database using a secure connection bundle](#datastax-node-js-driver-connecting-to-your-datastax-astra-database-using-a-secure-connection-bundle) - [DataStax Node.js Driver - TLS/SSL](#datastax-node-js-driver-tls-ssl) - [DataStax Node.js Driver - Execution Profiles](#datastax-node-js-driver-execution-profiles) - [DataStax Node.js Driver - Home](#datastax-node-js-driver-home) - [DataStax Node.js Driver - Mapper](#datastax-node-js-driver-mapper) - [DataStax Node.js Driver - Logging](#datastax-node-js-driver-logging) - [DataStax Node.js Driver - ClientOptions](#datastax-node-js-driver-clientoptions) - [DataStax Node.js Driver - HostMap](#datastax-node-js-driver-hostmap) - [DataStax Node.js Driver - ResultCallback](#datastax-node-js-driver-resultcallback) - [DataStax Node.js Driver - errors](#datastax-node-js-driver-errors) - [DataStax Node.js Driver - QueryOptions](#datastax-node-js-driver-queryoptions) - [DataStax Node.js Driver - Encoder](#datastax-node-js-driver-encoder) - [DataStax Node.js Driver - Fetching large result sets](#datastax-node-js-driver-fetching-large-result-sets) - [DataStax Node.js Driver - Batch statements](#datastax-node-js-driver-batch-statements) - [DataStax Node.js Driver - CQL data types to JavaScript types](#datastax-node-js-driver-cql-data-types-to-javascript-types) - [DataStax Node.js Driver - Client](#datastax-node-js-driver-client) - [DataStax Node.js Driver - Host](#datastax-node-js-driver-host) - [DataStax Node.js Driver - ExecutionProfile](#datastax-node-js-driver-executionprofile) - [DataStax Node.js Driver - Query warnings](#datastax-node-js-driver-query-warnings) - [DataStax Node.js Driver - mapping](#datastax-node-js-driver-mapping) - [DataStax Node.js Driver - Query timestamps](#datastax-node-js-driver-query-timestamps) - [DataStax Node.js Driver - API docs](#datastax-node-js-driver-api-docs) - [DataStax Node.js Driver - Geospatial types](#datastax-node-js-driver-geospatial-types) - [DataStax Node.js Driver - Speculative query execution](#datastax-node-js-driver-speculative-query-execution) - [DataStax Node.js Driver - Connection pooling](#datastax-node-js-driver-connection-pooling) - [DataStax Node.js Driver - Native protocol](#datastax-node-js-driver-native-protocol) - [DataStax Node.js Driver - Parameterized queries](#datastax-node-js-driver-parameterized-queries) - [DataStax Node.js Driver - policies](#datastax-node-js-driver-policies) - [DataStax Node.js Driver - Graph support](#datastax-node-js-driver-graph-support) - [DataStax Node.js Driver - Upgrading from the DSE Driver](#datastax-node-js-driver-upgrading-from-the-dse-driver) - [DataStax Node.js Driver - Cluster and schema metadata](#datastax-node-js-driver-cluster-and-schema-metadata) - [DataStax Node.js Driver - Tuning policies](#datastax-node-js-driver-tuning-policies) - [DataStax Node.js Driver - auth](#datastax-node-js-driver-auth) - [DataStax Node.js Driver - ResultCallback](#datastax-node-js-driver-resultcallback) - [DataStax Node.js Driver - User-defined functions and aggregates](#datastax-node-js-driver-user-defined-functions-and-aggregates) - [DataStax Node.js Driver - datastax](#datastax-node-js-driver-datastax) - [DataStax Node.js Driver - geometry](#datastax-node-js-driver-geometry) - [DataStax Node.js Driver - Promise and callback-based API](#datastax-node-js-driver-promise-and-callback-based-api) - [DataStax Node.js Driver - metrics](#datastax-node-js-driver-metrics) - [DataStax Node.js Driver - tracker](#datastax-node-js-driver-tracker) - [DataStax Node.js Driver - ExecutionOptions](#datastax-node-js-driver-executionoptions) - [DataStax Node.js Driver - metadata](#datastax-node-js-driver-metadata) - [DataStax Node.js Driver - concurrent](#datastax-node-js-driver-concurrent) - [DataStax Node.js Driver - Frequently Asked Questions](#datastax-node-js-driver-frequently-asked-questions) - [DataStax Node.js Driver - TransitionalModePlainTextAuthenticator](#datastax-node-js-driver-transitionalmodeplaintextauthenticator) - [DataStax Node.js Driver - ClientOptions](#datastax-node-js-driver-clientoptions) - [DataStax Node.js Driver - Address resolution](#datastax-node-js-driver-address-resolution) - [DataStax Node.js Driver - types](#datastax-node-js-driver-types) - [DataStax Node.js Driver - Batch statements](#datastax-node-js-driver-batch-statements) - [DataStax Node.js Driver - Client](#datastax-node-js-driver-client) - [DataStax Node.js Driver - Connection pooling](#datastax-node-js-driver-connection-pooling) - [DataStax Node.js Driver - Three simple rules for coding with the driver](#datastax-node-js-driver-three-simple-rules-for-coding-with-the-driver) - [DataStax Node.js Driver - Upgrade Guide](#datastax-node-js-driver-upgrade-guide) - [DataStax Node.js Driver - Concurrent Execution API](#datastax-node-js-driver-concurrent-execution-api) - [DataStax Node.js Driver - Authentication](#datastax-node-js-driver-authentication) - [DataStax Node.js Driver - Native protocol](#datastax-node-js-driver-native-protocol) - [DataStax Node.js Driver - Encoder](#datastax-node-js-driver-encoder) - [DataStax Node.js Driver - QueryOptions](#datastax-node-js-driver-queryoptions) - [DataStax Node.js Driver - Host](#datastax-node-js-driver-host) - [DataStax Node.js Driver - Query warnings](#datastax-node-js-driver-query-warnings) - [DataStax Node.js Driver - errors](#datastax-node-js-driver-errors) - [DataStax Node.js Driver - Getting Started](#datastax-node-js-driver-getting-started) - [DataStax Node.js Driver - API docs](#datastax-node-js-driver-api-docs) - [DataStax Node.js Driver - Features](#datastax-node-js-driver-features) - [DataStax Node.js Driver - Connecting to your DataStax Astra database using a secure connection bundle](#datastax-node-js-driver-connecting-to-your-datastax-astra-database-using-a-secure-connection-bundle) - [DataStax Node.js Driver - Logging](#datastax-node-js-driver-logging) - [DataStax Node.js Driver - Mapper](#datastax-node-js-driver-mapper) - [DataStax Node.js Driver - TLS/SSL](#datastax-node-js-driver-tls-ssl) - [DataStax Node.js Driver - HostMap](#datastax-node-js-driver-hostmap) - [DataStax Node.js Driver - Fetching large result sets](#datastax-node-js-driver-fetching-large-result-sets) - [DataStax Node.js Driver - CQL data types to JavaScript types](#datastax-node-js-driver-cql-data-types-to-javascript-types) - [DataStax Node.js Driver - Tuning policies](#datastax-node-js-driver-tuning-policies) - [DataStax Node.js Driver - mapping](#datastax-node-js-driver-mapping) - [DataStax Node.js Driver - ExecutionProfile](#datastax-node-js-driver-executionprofile) - [DataStax Node.js Driver - Execution Profiles](#datastax-node-js-driver-execution-profiles) - [DataStax Node.js Driver - Speculative query execution](#datastax-node-js-driver-speculative-query-execution) - [DataStax Node.js Driver - Geospatial types](#datastax-node-js-driver-geospatial-types) - [DataStax Node.js Driver - datastax](#datastax-node-js-driver-datastax) - [DataStax Node.js Driver - Graph support](#datastax-node-js-driver-graph-support) - [DataStax Node.js Driver - Parameterized queries](#datastax-node-js-driver-parameterized-queries) - [DataStax Node.js Driver - Cluster and schema metadata](#datastax-node-js-driver-cluster-and-schema-metadata) - [DataStax Node.js Driver - User-defined functions and aggregates](#datastax-node-js-driver-user-defined-functions-and-aggregates) - [DataStax Node.js Driver - Upgrading from the DSE Driver](#datastax-node-js-driver-upgrading-from-the-dse-driver) - [DataStax Node.js Driver - geometry](#datastax-node-js-driver-geometry) - [DataStax Node.js Driver - concurrent](#datastax-node-js-driver-concurrent) - [DataStax Node.js Driver - TransitionalModePlainTextAuthenticator](#datastax-node-js-driver-transitionalmodeplaintextauthenticator) - [DataStax Node.js Driver - tracker](#datastax-node-js-driver-tracker) - [DataStax Node.js Driver - metrics](#datastax-node-js-driver-metrics) - [DataStax Node.js Driver - Query timestamps](#datastax-node-js-driver-query-timestamps) - [DataStax Node.js Driver - Promise and callback-based API](#datastax-node-js-driver-promise-and-callback-based-api) - [DataStax Node.js Driver - Concurrent Execution API](#datastax-node-js-driver-concurrent-execution-api) - [DataStax Node.js Driver - Home](#datastax-node-js-driver-home) - [DataStax Node.js Driver - Getting Started](#datastax-node-js-driver-getting-started) - [DataStax Node.js Driver - ExecutionOptions](#datastax-node-js-driver-executionoptions) - [DataStax Node.js Driver - Mapper](#datastax-node-js-driver-mapper) - [DataStax Node.js Driver - Logging](#datastax-node-js-driver-logging) - [DataStax Node.js Driver - Three simple rules for coding with the driver](#datastax-node-js-driver-three-simple-rules-for-coding-with-the-driver) - [DataStax Node.js Driver - Geospatial types](#datastax-node-js-driver-geospatial-types) - [DataStax Node.js Driver - Upgrade Guide](#datastax-node-js-driver-upgrade-guide) - [DataStax Node.js Driver - Frequently Asked Questions](#datastax-node-js-driver-frequently-asked-questions) - [DataStax Node.js Driver - Features](#datastax-node-js-driver-features) - [DataStax Node.js Driver - TLS/SSL](#datastax-node-js-driver-tls-ssl) - [DataStax Node.js Driver - Connecting to your DataStax Apollo database using a secure connection bundle](#datastax-node-js-driver-connecting-to-your-datastax-apollo-database-using-a-secure-connection-bundle) - [DataStax Node.js Driver - Authentication](#datastax-node-js-driver-authentication) - [DataStax Node.js Driver - Upgrading from the DSE Driver](#datastax-node-js-driver-upgrading-from-the-dse-driver) - [DataStax Node.js Driver - geometry](#datastax-node-js-driver-geometry) - [DataStax Node.js Driver - Speculative query execution](#datastax-node-js-driver-speculative-query-execution) - [DataStax Node.js Driver - API docs](#datastax-node-js-driver-api-docs) - [DataStax Node.js Driver - Three simple rules for coding with the driver](#datastax-node-js-driver-three-simple-rules-for-coding-with-the-driver) - [DataStax Node.js Driver - Graph support](#datastax-node-js-driver-graph-support) - [DataStax Node.js Driver - datastax](#datastax-node-js-driver-datastax) - [DataStax Node.js Driver - Upgrade Guide](#datastax-node-js-driver-upgrade-guide) - [DataStax Node.js Driver - Frequently Asked Questions](#datastax-node-js-driver-frequently-asked-questions) - [DataStax Node.js Driver - Getting Started](#datastax-node-js-driver-getting-started) - [DataStax Node.js Driver - Home](#datastax-node-js-driver-home) --- # DataStax Enterprise Ruby Driver - Home [DataStax Enterprise Ruby Driver 2.1 (Latest version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.1 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/) * Ruby DataStax Enterprise Driver[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#ruby-data-stax-enterprise-driver) ========================================================================================================================================== _NOTE: The Ruby DataStax Enterprise Driver can be used solely with DataStax Enterprise. Please consult [the license](http://www.datastax.com/terms/datastax-dse-driver-license-terms) ._ This driver is built on top of the [DataStax Ruby driver for Apache Cassandra](http://docs.datastax.com/en/developer/ruby-driver/3.0) and enhanced for the adaptive data management and mixed workload capabilities provided by DSE. Therefore a lot of the underlying concepts are the same. Documentation[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#documentation) ----------------------------------------------------------------------------------------------------- Driver documentation can be found [here](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/) . In particular, you’ll find our [Features](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features) and [API](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api) sections very enlightening. Compatibility[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#compatibility) ----------------------------------------------------------------------------------------------------- This driver works exclusively with the Cassandra Query Language v3 (CQL3), Cassandra’s native protocol, and DataStax Enterprise extensions to that protocol. The current version works with: * DataStax Enterprise 4.8 and above. * Ruby (MRI) 2.2, 2.3, 2.4 * JRuby 9k **Note**: DataStax products do not support big-endian systems. Feedback Requested[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#feedback-requested) --------------------------------------------------------------------------------------------------------------- _Help us focus our efforts!_ [Provide your input](http://goo.gl/forms/pCs8PTpHLf) on the Ruby Driver Platform and Runtime Survey (we kept it short). If you find an issue, please file an issue in our [public JIRA](https://datastax-oss.atlassian.net/browse/RUBY) . _Please be sure to specify the affects-version (DSE-X.Y.Z)._ You can also post questions in [our forum](https://groups.google.com/a/lists.datastax.com/forum/#!forum/ruby-driver-user) . Features[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#features) ------------------------------------------------------------------------------------------- This driver exposes the following features of DSE 5.0: * [Graph](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph#graph) * [Authentication](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication#authentication) with nodes running DSE * [Geospatial types](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/geospatial#geospatial-types) Note that this driver is fully compatible with previous versions of DataStax Enterprise. Installation[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#installation) --------------------------------------------------------------------------------------------------- The driver is named dse-driver on rubygems.org and can easily be installed with Bundler or the gem program. It will download the appropriate Cassandra driver as well. Upgrade[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#upgrade) ----------------------------------------------------------------------------------------- The driver is intended to have the same look and feel as the core driver to make upgrading from the core driver trivial. The only change is to replace references to the `Cassandra` module with `Dse` when creating the cluster object: require 'dse' # This returns a Dse::Cluster instance cluster = Dse.cluster # This returns a Dse::Session instance session = cluster.connect rs = session.execute('select * from system.local') Breaking changes in 2.0[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#breaking-changes-in-2-0) ------------------------------------------------------------------------------------------------------------------------- This release adds support for [graph execution profiles](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph#execution-profiles) . As a result, the cluster-level `graph_options` object has been removed. That object is effectively stored in the `:default_graph` execution profile. However, since execution profiles are read-only, graph options in profiles cannot be manipulated. Instead, either specify new graph options at query execution time, or use separate execution profiles for your different scenarios. Furthermore, the `Dse::Graph::Options` class is no longer in the public api. Instead of constructing a `Dse::Graph::Options` object and passing it to `Session.execute_graph*`, you must now pass the primitive graph options or specify the name of an execution profile that encapsulates the desired graph options. Similarly, when creating a `Dse::Graph::Statement`, you must specify primitive graph options instead of a `Dse::Graph::Options` object. Since execution profiles are immutable, you must set expert options at construction time with the `expert_options` hash. See the [documentation](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph#expert-options) for more details. Another behavior change is that in v1.x, graph query timeout defaulted to unlimited. This caused queries to fall back to server timeouts. The default was set this way to accommodate multi-day analytics queries and multi-second OLTP queries without requiring intervention / special handling from the user. The introduction of execution profiles into the driver enables the user to more easily run different types of queries: # Use the default graph profile with its OLTP-motivated timeout (30 seconds) rs = session.execute_graph('g.V()') # Use the default graph analytics profile for an OLAP query (timeout 7 days) rs = session.execute_graph('g.V()', execution_profile: :default_graph_analytics # Use the default system query profile for graph system queries (timeout 3 minutes) rs = session.execute_graph("system.graph('mygraph').exists()", execution_profile: :default_graph_system) Thus, no query runs with unlimited timeout by default as of this version of the driver. Finally, in v1.x, graph query timeout was specified via the `:timeout` option in calls to `Session.execute_graph*` or packaged up in a graph options object. Since the graph execution profile now assumes the role of graph options, use the `:timeout` attribute in the graph execution profile to specify graph timeout. In particular, to set the default graph timeout for graph queries, you must define your own `:default_graph` execution profile that will take precedence over one that would normally be generated by the driver: cluster = Dse.cluster(execution_profiles: { default_graph: Dse::Graph::ExecutionProfile.new(timeout: 17, graph_name: 'mygraph') }) In the example above, the default graph timeout is set to 17 seconds. Note that you are not permitted to mix primitive options (that are now available in execution profiles) with an execution\_profiles hash when creating the cluster object: # Illegal! cluster = Dse.cluster(execution_profiles: { default_graph: Dse::Graph::ExecutionProfile.new(timeout: 17, graph_name: 'mygraph') }, timeout: 7) Thus, in order to specify that non-graph queries should execute with a timeout of 7 seconds by default, you must override the Cassandra default execution profile, named `:default`: # Legal. cluster = Dse.cluster(execution_profiles: { default_graph: Dse::Graph::ExecutionProfile.new(timeout: 17, graph_name: 'mygraph'), default: Cassandra::Execution::Profile.new(timeout: 7) }) Determining driver versions[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#determining-driver-versions) --------------------------------------------------------------------------------------------------------------------------------- Within a script or irb, you can determine the exact versions of the dse and core drivers by accessing the VERSION constant of the appropriate module: require 'dse' puts "Dse Driver Version: #{Dse::VERSION}" puts "Cassandra Driver Version: #{Cassandra::VERSION}" Compatibility[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#compatibility) ----------------------------------------------------------------------------------------------------- Although this driver exposes new features introduced in DSE 5.0, it is fully compatible and supported for use with previous versions of DSE. License[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/index.html#license) ----------------------------------------------------------------------------------------- © DataStax, Inc. The full license terms are available at [http://www.datastax.com/terms/datastax-dse-driver-license-terms](http://www.datastax.com/terms/datastax-dse-driver-license-terms) --- # DataStax Enterprise Ruby Driver - Features [DataStax Enterprise Ruby Driver 2.1 (Latest version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.1 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/) * This release exposes three major features of DataStax Enterprise 5.0: * [DSE Graph](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph) * [DSE Unified Authentication](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication) , which includes Kerberos support * [Geospatial Types](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/geospatial) Note that this driver is fully compatible with previous versions of DataStax Enterprise. --- # DataStax Enterprise Ruby Driver - Authentication [DataStax Enterprise Ruby Driver 2.1 (Latest version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.1 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication/) * Authentication[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication/index.html#authentication) ------------------------------------------------------------------------------------------------------------------------------- DSE 5.0 introduces [DSE Unified Authentication](http://docs.datastax.com/en/datastax_enterprise/5.0/datastax_enterprise/unifiedAuth/unifiedAuthConfig.html) , which supports multiple authentication schemes concurrently. Thus, different clients may authenticate with any authentication provider that is supported under the “unified authentication” umbrella: internal authentication, LDAP, and Kerberos. _NOTE:_ the authentication providers described below are backward-compatible with legacy authentication mechanisms provided by older DSE releases. So, feel free to use these providers regardless of your DSE environment. ### Internal and LDAP Authentication[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication/index.html#internal-and-ldap-authentication) Just as [Cassandra::Auth::Providers::Password](http://docs.datastax.com/en/developer/ruby-driver/3.0/api/cassandra/auth/providers/password) handles internal and LDAP authentication with Cassandra, the `Dse::Auth::Providers::Password` provider handles these types of authentication in DSE 5.0 configured with DseAuthenticator. The Ruby DSE driver makes it very easy to authenticate with username and password: `ruby cluster = Dse.cluster(username: 'user', password: 'pass')` The driver creates the provider under the hood and configures the cluster object appropriately. ### Kerberos Authentication[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication/index.html#kerberos-authentication) #### Initial Setup[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication/index.html#initial-setup) Unlike other authentication mechanisms, Kerberos requires some set-up on the client. First, set the `KRB5_CONFIG` environment variable to the location of your `krb5.conf` file and use `kinit` to obtain a ticket from your Kerberos server. This environment variable is also needed by the Ruby DSE driver when run in an MRI Ruby interpreter. This is due to the fact that Kerberos support is implemented as a C extension that uses the gssapi system libraries – the same libraries that command line tools like kinit use. The JRuby implementation of Kerberos support uses the Java security framework, which requires the `java.security.krb5.conf` system property to be set to the location of the `krb5.conf` file. One way to accomplish this is to set the `JRUBY_OPTS` environment variable before running your client application: export JRUBY_OPTS="-J-Djava.security.krb5.conf=/home/user1/krb5.conf" #### Configuring the Client[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication/index.html#configuring-the-client) To enable kerberos authentication with DSE nodes, set the `auth_provider` of the cluster to a `Dse::Auth::Providers::GssApi` instance. The following example code shows all the ways to set this up. require 'dse' # Create a provider for the 'dse' service and have it use the first ticket in the default ticket cache for # authentication with nodes, which have hostname entries in the Kerberos server. All of the # assignments below are equivalent: provider = Dse::Auth::Providers::GssApi.new provider = Dse::Auth::Providers::GssApi.new('dse') provider = Dse::Auth::Providers::GssApi.new('dse', true) provider = Dse::Auth::Providers::GssApi.new('dse', true, nil) # Same as above, but this time turn off hostname resolution because the Kerberos server # may be configured with ip's, not hostnames, of DSE nodes. provider = Dse::Auth::Providers::GssApi.new('dse', false) # Use a custom hostname resolver. class MyResolver def resolve(ip) "host-#{ip}" end end provider = Dse::Auth::Providers::GssApi.new('dse', MyResolver.new) # Specify different principal to use for authentication. This principal must already have a valid # ticket in the Kerberos ticket cache. Also, the principal name is case-sensitive, so make sure it # *exactly* matches your Kerberos ticket. provider = Dse::Auth::Providers::GssApi.new('dse', true, 'cassandra@DATASTAX.COM') # However you configure the provider, pass it to Dse.cluster to have it be used for authentication. cluster = Dse.cluster(auth_provider: provider) #### Ticket Caches[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication/index.html#ticket-caches) By default, `kinit` and related tools (e.g. `klist`, `kdestroy`) manipulate a simple file tied to the client os user’s numeric id on Linux: `/tmp/krb5cc_`. This file only supports one “ticket granting ticket”, so if you have a need for multiple credentials in your system (e.g. multiple applications each of which need to authenticate with different credentials to different services), you can supply the `-c` argument to kinit to authenticate and store the resulting ticket in a different cache. In that set-up, you must initialize your `auth_provider` in the driver with this info: # The fourth arg is the path to the cache file. provider = Dse::Auth::Providers::GssApi.new('dse', true, nil, '/home/myuser/krb.cache') For MRI (the underlying gssapi C library, actually), you can set the `KRB5CCNAME` environment variable instead of supplying an extra argument to the provider constructor. Mac supports non-default caches as well, but it’s not necessary because by default the default cache is an in-memory store that supports multiple tickets. --- # DataStax Enterprise Ruby Driver - Geospatial Types [DataStax Enterprise Ruby Driver 2.1 (Latest version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.1 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/geospatial/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/geospatial/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/geospatial/) * Geospatial Types[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/geospatial/index.html#geospatial-types) ------------------------------------------------------------------------------------------------------------------------------- DataStax Enterprise v5.0 adds support for three geospatial types in the underlying Cassandra 3.x database. Instances of these types can be expressed in [well-known text (WKT)](https://en.wikipedia.org/wiki/Well-known_text) form as well as a binary representation known as [well-known binary (WKB)](https://en.wikipedia.org/wiki/Well-known_text#Well-known_binary) . This latter representation is sent over the wire between the client and DSE node, but the former makes it easy to submit queries with geospatial type references in cqlsh. For example, if you had a `points` table with an int key `f1` and a PointType column `p`, you could insert a row into it like this in cqlsh: `INSERT INTO points (f1, p) VALUES (7, 'POINT (32.0 12.0)');` You can compose points into line-strings and you can compose line-strings into polygons. See [this section of the WKT documentation](https://en.wikipedia.org/wiki/Well-known_text#Geometric_objects) for details. ### Point[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/geospatial/index.html#point) A _Point_ is a point with x,y coordinates. Columns in DSE have the custom type `org.apache.cassandra.db.marshal.PointType`. # The geospatial types are defined in the Dse::Geometry module. Save some typing and include it # here so that we can refer to the classes with their base names. include Dse::Geometry # Create a table with a PointType column and insert a row into it. session.execute("CREATE TABLE IF NOT EXISTS points_of_interest" \ " (name text PRIMARY KEY, coords 'PointType')") session.execute('INSERT INTO points_of_interest (name, coords) VALUES (?, ?)', arguments: ['Empire State', Point.new(38.0, 21.0)]) # Now retrieve the point. rs = session.execute('SELECT * FROM points_of_interest') rs.each do |row| # We can emit the point in its WKT representation. puts "#{row['name']} #{row['coords'].wkt}" # Or the x and y coordinates puts "#{row['name']} #{row['coords'].x},#{row['coords'].y}" # Which is really the to_s of the point, so you can do this: puts "#{row['name']} #{row['coords']}" end ### LineString[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/geospatial/index.html#line-string) A _LineString_ is a set of lines, characterized by a sequence of \*Point\*s. As \*Point\*s live in the 2D xy-plane, so do \*LineString\*s. Each line shares a point with another line, thus forming a string of lines. A real-world example of this is a path on a map. Columns in DSE have the custom type `org.apache.cassandra.db.marshal.LineStringType`. # The geospatial types are defined in the Dse::Geometry module. Save some typing and include it # here so that we can refer to the classes with their base names. include Dse::Geometry # Create a table with a LineString column and insert a row into it. session.execute("CREATE TABLE IF NOT EXISTS directions" \ " (origin text PRIMARY KEY, destination text, directions 'LineStringType')") session.execute('INSERT INTO directions (origin, destination, directions) VALUES (?, ?, ?)', arguments: ['office', 'home', LineString.new(Point.new(12.0, 21.0),\ Point.new(13.0, 31.0),\ Point.new(14.0, 41.0))]) # Now retrieve the line-string. rs = session.execute('SELECT * FROM directions') rs.each do |row| directions = row['directions'].points.map do |point| "#{point.x},#{point.y}" end.join(" to ") puts "Directions from #{row['origin']} to #{row['destination']}: #{directions}" # Or more simply (thanks to an overridden to_s) puts "Directions from #{row['origin']} to #{row['destination']}: #{row['directions']}" # And its wkt for fun puts "WKT: #{row['directions'].wkt}" end ### Polygon[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/geospatial/index.html#polygon) A _Polygon_ is an enclosed shape consisting of a set of linear-rings. A linear-ring is a _LineString_ whose last point is the same as its first point (thus forming a ring when you connect the points). The first ring specified in a polygon defines the outer edges of the polygon and is called the exterior ring. A polygon may also have holes within it, specified by other linear-rings, and those holes may contain linear-rings indicating islands. All such rings are called interior rings. # The geospatial types are defined in the Dse::Geometry module. Save some typing and include it # here so that we can refer to the classes with their base names. include Dse::Geometry # Create a table with a Polygon column and insert a row into it. A polygon consists of a set # of linear-rings. A linear-ring is a LineString whose last point is the same as its first point. session.execute("CREATE TABLE IF NOT EXISTS places (name text PRIMARY KEY, layout 'PolygonType')") exterior_ring = LineString.new(Point.new(0, 0), Point.new(20, 0), Point.new(26, 26), Point.new(0, 26), Point.new(0, 0)) interior_ring = LineString.new(Point.new(1, 1), Point.new(1, 5), Point.new(5, 5), Point.new(5, 1), Point.new(1, 1)) session.execute('INSERT INTO places (name, layout) VALUES (?, ?)', arguments: ['Capitol', Polygon.new(exterior_ring, interior_ring)]) # Now retrieve the polygon rs = session.execute('SELECT * FROM places') rs.each do |row| puts "Layout of #{row['name']}:" # Write out the exterior ring puts "Exterior: #{row['layout'].exterior_ring}" # Write out the first point in the first interior ring...because we can. puts "First interior point: #{row['layout'].interior_rings.first.points.first}" # Finally, let's emit the WKT representation. puts "WKT: #{row['layout'].wkt}" end --- # DataStax Enterprise Ruby Driver - Graph [DataStax Enterprise Ruby Driver 2.1 (Latest version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.1 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph/) * Graph[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/index.html#graph) ---------------------------------------------------------------------------------------------------- The DSE Graph service processes graph queries written in the [Gremlin](https://github.com/tinkerpop/gremlin/wiki) language. `Session#execute_graph` and `Session#execute_graph_async` are responsible for transmitting graph queries to DSE graph. The response is a graph result set, which may contain domain object representations of graph objects. A script using the DSE driver to execute graph queries will typically begin like this: require 'dse' # Connect to DSE and create a session whose graph queries will be tied to the graph # named 'mygraph' by default. See the documentation for Dse::Graph::Options for all # supported graph options. cluster = Dse.cluster(graph_name: 'mygraph') session = cluster.connect The DSE driver is a wrapper around the core Cassandra driver, so any valid options to the core driver are valid in the DSE driver as well. This includes specifying execution profiles. ### Execution Profiles[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/index.html#execution-profiles) Execution profiles were introduced in v3.1.0 of the Cassandra driver to group together a set of options for executing queries. The DSE driver provides the `Dse::Graph::ExecutionProfile` class to encapsulate graph options and core execution profile attributes. Graph execution profile attributes, like their Cassandra driver counterpart, fall back to system default values when not specified: * load\_balancing\_policy: `LoadBalancing::Policies::TokenAware.new(LoadBalancing::Policies::DCAwareRoundRobin.new, true)` * retry-policy: `Retry::Policies::Default.new` * consistency: `:local_one` The exception to this rule is that the timeout defaults to 30 seconds, while the Cassandra system default is 12. Most of the graph options default to `nil` and defer to values in server-side configuration. The following options, however, do have client-side defaults: \* graph\_source: `g` \* graph\_language: `gremlin-groovy` When querying these options in an execution profile, `nil` is returned. However, at request execution time, the appropriate defaults are sent in the request payload. The DSE driver initializes the following three default graph execution profiles: * `:default_graph` - used by default by `Session#execute_graph*` * timeout: `30` because graph queries tend to run longer than CQL queries. * `:default_graph_system` - useful when running system queries. * timeout: `180` because system queries typically run longer than ordinary graph queries since they are mutating the schema and must synchronize with multiple nodes. * `:default_graph_analytics` - useful for analytics queries * timeout: `604800`, which is 7 days because analytics queries can run for a very long time * graph\_source: `a` because analytics queries must run against the ‘analytics’ source. * load\_balancing\_policy: `Dse::LoadBalancing::Policies::HostTargeting.new()`, which gives priority to the analytics master node. Analytics queries must run on the analytics master, and without this policy, the client would likely send requests to a different (coordinator) node and that node would have to forward the request to the analytics master. Thus, this load-balancing policy saves a network hop. Unspecified options above fall back to the system defaults. If you define your own `:default_graph*` profiles, you must take care to set the options you want to override as well as options that you’d like to keep unchanged from the internally-built `:default_graph*` profile, since you don’t want your profile to fall back to system defaults (e.g. load-balancing-policy for the `:default_graph_analytics` profile). Graph options specified to `Dse#cluster` are stored in the `:default_graph` graph execution profile. Thus, without specifying any execution-profile parameters to `Dse#cluster`, the resulting profiles will often be as you want them. In the above example, we want graph queries to interact with graph `mygraph` most of the time. In addition, if the `graph_name` graph option is specified, it will be set into the `:default_graph_analytics` profile. Just as in the core driver, execution profiles provide default options for executing queries. Specify overrides as options to `Session#execute_graph`: session.execute_graph('g.V()', graph_name: 'starmap', execution_profile: :default_graph_analytics) Define entirely new profiles when creating the `cluster` object. Profile names should be strings or symbols, though they can be any type of object that has a reliable hashcode because ultimately the name becomes a key in a hash. cluster = Dse.cluster( execution_profiles: { test1: Dse::Graph::ExecutionProfile.new(graph_source: 'g', timeout: 5), 'test2' => Dse::Graph::ExecutionProfile.new(graph_source: 'a', timeout: 12) } ) session = cluster.connect result = session.execute_graph('g.V()', execution_profile: :test1) result2 = session.execute_graph('g.V()', execution_profile: 'test2') Note that it is illegal specify execution\_profiles and the above-mentioned primitive options when initializing the cluster. Define the `:default` and `:default_graph*` profiles as appropriate when you want to change default behavior _and_ define your own profiles. #### Expert Options[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/index.html#expert-options) In an effort to make the DSE driver compatible with future versions of DataStax Enterprise Graph, graph execution profiles also support specifying arbitrary key-value options. These “expert options” presumably exist in an as-yet unreleased version of DataStax Enterprise. To leverage this feature, simply supply an `expert_options` hash when creating your execution profile or execution your graph statement: profile = Dse::Graph::ExecutionProfile.new(graph_source: 'g', expert_options: {'some_option' => 'some_value'}) session.execute_graph('g.V()', expert_options: {'some_option' => 'some_value'}) ### Vertices[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/index.html#vertices) Vertices in DSE Graph have properties. A property may have multiple values. This is represented as an array when manipulating a Vertex object. A property value may also have properties of their own (known as meta-properties). These meta-properties are simple key-value pairs of strings; they do not nest. # Run a query to get all the vertices in our graph. results = session.execute_graph('g.V()') # Each result is a Dse::Graph::Vertex. # Print out the label and a few of its properties. puts "Number of vertex results: #{results.size}" results.each do |v| # Start with the label puts "#{v.label}:" # Vertex properties support multiple values as well as meta-properties # (simple key-value attributes that apply to a given property's value). # # Emit the 'name' property's first value. puts " name: #{v.properties['name'][0].value}" # Name again, using our abbreviated syntax puts " name: #{v['name'][0].value}" # Print all the values of the 'name' property values = v['name'].map do |vertex_prop| vertex_prop.value end puts " all names: #{values.join(',')}" # That's a little inconvenient. So use the 'values' shortcut: puts " all names: #{v['name'].values.join(',')}" # Let's get the 'title' meta-property of 'name's first value. puts " title: #{v['name'][0].properties['title']}" # This has a short-cut syntax as well: puts " title: #{v['name'][0]['title']}" end ### Edges[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/index.html#edges) Edges connect a pair of vertices in DSE Graph. They also have properties, but they are simple key-value pairs of strings. results = session.execute_graph('g.E()') puts "Number of edge results: #{results.size}" # Each result is a Dse::Graph::Edge object. results.each do |e| # Start with the label puts "#{e.label}:" # Now the id's of the two vertices that this edge connects. puts " in id: #{e.in_v}" puts " out id: #{e.out_v}" # Edge properties are simple key-value pairs; sort of like # meta-properties on vertices. puts " edge_prop1: #{e.properties['edge_prop1']}" # This supports the short-cut syntax as well: puts " edge_prop1: #{e['edge_prop1']}" end ### Path and Arbitrary Objects[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/index.html#path-and-arbitrary-objects) Paths describe a path between two vertices. The graph response from DSE does not indicate that the response is a path, so the driver cannot automatically coerce such results into Path objects. The driver returns a DSE::Graph::Result object in such cases, and you can coerce the result. results = session.execute_graph('g.V().in().path()') puts "Number of path results: #{results.size}" results.each do |r| # The 'value' of the result is a hash representation of the JSON result. puts "first label: #{r.value['labels'].first}" # Since we know this is a Path result, coerce it and use the Path object's methods. p = r.as_path puts "first label: #{p.labels.first}" end When a query has a simple result, the :value attribute of the result object contains the simple value rather than a hash. results = session.execute_graph('g.V().count()') puts "Number of vertices: #{results.first.value}" ### Duration Graph Type[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/index.html#duration-graph-type) DSE Graph supports several [datatypes](http://docs.datastax.com/en/latest-dse/datastax_enterprise/graph/reference/refDSEGraphDataTypes.html) for properties. The _Duration_ type represents a duration of time. When DSE Graph returns properties of this type, the string representation is non-trivial and requires parsing in order for the user to really gain any information from it. The driver includes a helper class to parse such responses from DSE graph as well as to send such values in bound paramters in requests: # Create a Duration property in the schema called 'runtime' and declare that 'process' vertices can have this property. session.execute_graph( "schema.propertyKey('runtime').Duration().ifNotExists().create(); schema.propertyKey('name').Text().ifNotExists().create(); schema.vertexLabel('process').properties('name', 'runtime').ifNotExists().create()") # We want to record that a process ran for 1 hour, 2 minutes, 3.5 seconds. runtime = Dse::Graph::Duration.new(0, 1, 2, 3.5) session.execute_graph( "graph.addVertex(label, 'process', 'name', 'calculator', 'runtime', my_runtime);", arguments: {'my_runtime' => runtime}) # Now retrieve the vertex. Assume this is the only vertex in the graph for simplicity. v = session.execute_graph('g.V()').first runtime = Dse::Graph::Duration.parse(v['runtime'].first.value) puts "#{runtime.hours} hours, #{runtime.minutes} minutes, #{runtime.seconds} seconds" ### Miscellaneous Features[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/index.html#miscellaneous-features) There are a number of other features in the api to make development easier. # We can access particular items in the result-set via array dereference p results[1] # Run a query against a different graph, but don't mess with the cluster default. results = session.execute_graph('g.V().count()', graph_name: 'my_other__graph') # Set an "expert" option for which we don't have a proper graph option. # NOTE: Such options are not part of the public api and may change in a future # release of DSE. results = session.execute_graph('g.V().count()', graph_name: 'my_other__graph', expert_options: {'super-cool-option' => 'value'}) # Create a statement object encapsulating a graph query, options, parameters, # for ease of reuse. statement = Dse::Graph::Statement.new('g.V().limit(n)', {n: 3}, graph_name: 'mygraph') results = session.execute_graph(statement) --- # DataStax Enterprise Ruby Driver - Dse [DataStax Enterprise Ruby Driver 2.1 (Latest version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.1 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/) * module Dse[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#module-dse) ======================================================================================================= Includes[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#includes) --------------------------------------------------------------------------------------------------- * `Cassandra::Statements` Modules[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#modules) ------------------------------------------------------------------------------------------------- * `[Auth](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/auth/ "Dse::Auth (module)") ` * `[Geometry](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/geometry/ "Dse::Geometry (module)") ` * `[Graph](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/graph/ "Dse::Graph (module)") ` * `[LoadBalancing](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/load_balancing/ "Dse::LoadBalancing (module)") ` Classes[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#classes) ------------------------------------------------------------------------------------------------- * `[Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/cluster/ "Dse::Cluster (class)") ` * `[Session](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/session/ "Dse::Session (class)") ` Constants[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#constants) ----------------------------------------------------------------------------------------------------- ### VERSION[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#version-constant) '2.1.4'.freeze Methods[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#methods) ------------------------------------------------------------------------------------------------- _self._ ### **cluster**[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#cluster-class_method) (options = {}) Creates a `[Cluster instance](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/cluster/ "Dse::Cluster (class)") `, which extends [Cassandra::Cluster](http://docs.datastax.com/en/developer/ruby-driver/3.0/api/cassandra/cluster "Cassandra::Cluster") . The API is identical, except that it returns a `[Dse::Session](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/session/ "Dse::Session (class)") ` (see below). It takes all of the same options as Cassandra.cluster and the following extra options. Examples: Connecting to localhost cluster = Dse.cluster Configuring `[Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/cluster/ "Dse::Cluster (class)") ` cluster = Dse.cluster( username: username, password: password, hosts: ['10.0.1.1', '10.0.1.2', '10.0.1.3'] ) Parameters: | Name | Type | Details | | --- | --- | --- | | options | `Hash` | _(defaults to: `{}`)_ a customizable set of options | Keys for options: | Key | Type | Details | | --- | --- | --- | | :graph\_name | `String` | name of graph to use in graph statements | | :graph\_source | `String` | graph traversal source | | :graph\_language | `String` | language used in graph queries | | :graph\_read\_consistency | `Cassandra::CONSISTENCIES` | read consistency level for graph statements. Overrides the standard statement consistency level | | :graph\_write\_consistency | `Cassandra::CONSISTENCIES` | write consistency level for graph statements. Overrides the standard statement consistency level | Returns: | Type | Details | | --- | --- | | `[Dse::Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/cluster/ "Dse::Cluster (class)") ` | a cluster instance | _self._ ### **cluster\_async**[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#cluster_async-class_method) (options = {}) Creates a `[Cluster instance](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/cluster/ "Dse::Cluster (class)") `. Returns: | Type | Details | | --- | --- | | `Cassandra::Future`<`[Dse::Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/cluster/ "Dse::Cluster (class)") `\> | a future resolving to the cluster instance. | See Also: * `[cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/index.html#cluster-class_method "Dse.cluster (method)") ` --- # DataStax Enterprise Ruby Driver - API docs [DataStax Enterprise Ruby Driver 2.1 (Latest version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.1 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/) * API docs[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/index.html#api-docs) =============================================================================================== Modules[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/index.html#modules) --------------------------------------------------------------------------------------------- * `[Dse](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/ "Dse (module)") ` --- # DataStax Enterprise Ruby Driver - Changelog [DataStax Enterprise Ruby Driver 2.1 (Latest version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.1 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/) * Changelog[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#changelog) ======================================================================================================= Changelog for the Ruby DataStax Enterprise Driver. 2.1.3[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#2-1-3) ----------------------------------------------------------------------------------------------- ### Features:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#features) * Update OSS driver dependency to v3.2.3. ### Fixes introduced in OSS driver v3.2.3:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#fixes-introduced-in-oss-driver-v3-2-3) * [RUBY-322](https://datastax-oss.atlassian.net/browse/RUBY-322) Decimals with zero scale aren’t parsed properly. * [RUBY-323](https://datastax-oss.atlassian.net/browse/RUBY-323) Travis can time out due to unintialized instance variable warning in CqlProtocolHandler. Thanks @baldarn for the contribution! * [RUBY-324](https://datastax-oss.atlassian.net/browse/RUBY-324) CQL generation does not handle nested collections properly. Thanks @mnin for the contribution! * [RUBY-325](https://datastax-oss.atlassian.net/browse/RUBY-325) Upgrade Yard to resolve security vulnerability. * [RUBY-326](https://datastax-oss.atlassian.net/browse/RUBY-326) CQL generation should include ascending clustering order specification. Thanks @mnin for the contribution! 2.1.2[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#2-1-2) ----------------------------------------------------------------------------------------------- ### Features:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#features) * Update OSS driver dependency to v3.2.2. ### Fixes introduced in OSS driver v3.2.2:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#fixes-introduced-in-oss-driver-v3-2-2) * [RUBY-319](https://datastax-oss.atlassian.net/browse/RUBY-319) Support reading decimals in scientific notation with positive exponent. * [RUBY-320](https://datastax-oss.atlassian.net/browse/RUBY-320) Cassandra::Future.all(\[\]).join hangs forever 2.1.1[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#2-1-1) ----------------------------------------------------------------------------------------------- ### Features:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#features) * Update OSS driver dependency to v3.2.1. ### Bug Fixes:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#bug-fixes) * [RUBY-315](https://datastax-oss.atlassian.net/browse/RUBY-315) Bump rubocop version to address security vulnerability; disallow Ruby versions prior to 2.2. * [RUBY-317](https://datastax-oss.atlassian.net/browse/RUBY-317) Upgrade Yard to address security vulnerability. ### Fixes introduced in OSS driver v3.2.1:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#fixes-introduced-in-oss-driver-v3-2-1) * [RUBY-315](https://datastax-oss.atlassian.net/browse/RUBY-315) Bump rubocop version to address security vulnerability; disallow Ruby versions prior to 2.2. * [RUBY-316](https://datastax-oss.atlassian.net/browse/RUBY-316) Memory leak in ruby driver due to request timers not being cleaned up when extremely large request timeout is set. * [RUBY-317](https://datastax-oss.atlassian.net/browse/RUBY-317) Upgrade Yard to address security vulnerability. * [RUBY-318](https://datastax-oss.atlassian.net/browse/RUBY-318) Fix Travis config to work with JRuby on new image. 2.1.0[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#2-1-0) ----------------------------------------------------------------------------------------------- ### Features:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#features) * Update OSS driver dependency to v3.2.0. This effectively adds support for MRI 2.4. ### Features and Fixes introduced in OSS driver v3.2.0:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#features-and-fixes-introduced-in-oss-driver-v3-2-0) * [RUBY-294](https://datastax-oss.atlassian.net/browse/RUBY-294) Support MRI 2.4.x. Thanks, @lautis, for this contribution! * [RUBY-291](https://datastax-oss.atlassian.net/browse/RUBY-291) Driver fails to connect to cluster when a table column type has a quoted name. * [RUBY-292](https://datastax-oss.atlassian.net/browse/RUBY-292) Driver sporadically crashes with “undefined method ‘ip’” error. Thanks, @grosser, for the fix! * [RUBY-295](https://datastax-oss.atlassian.net/browse/RUBY-295) When a custom address resolver is configured, consult it when handling all host events, and thus prevent the creation of invalid Host objects. 2.0.0[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#2-0-0) ----------------------------------------------------------------------------------------------- ### Features:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#features) * Add graph execution profile support. * Improve cluster.inspect output. 1.0.1[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#1-0-1) ----------------------------------------------------------------------------------------------- ### Bug Fixes:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#bug-fixes) * [RUBY-253](https://datastax-oss.atlassian.net/browse/RUBY-253) Installed gem can’t find native extensions 1.0.0[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#1-0-0) ----------------------------------------------------------------------------------------------- ### Features:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#features) * Added Kerberos support for JRuby. * Add support for non-default kerberos caches. * Graph queries should default to having no timeout. * When a graph query is executed with a timeout, send the timeout to the graph server to scope execution time server-side. * Support clearing individual options in a Dse::Graph::Options object. * Allow “expert” options to be set in graph options. * Support Duration datatype in graph queries. ### Bug Fixes:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#bug-fixes) * [RUBY-249](https://datastax-oss.atlassian.net/browse/RUBY-249) Dse::Graph::Options.inspect erroneously reports nil option values * [RUBY-252](https://datastax-oss.atlassian.net/browse/RUBY-252) Graph option timeout ignored when set at cluster level 1.0.0 rc2[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#1-0-0-rc2) ------------------------------------------------------------------------------------------------------- ### Bug Fixes:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#bug-fixes) * Updated license info in source files * Updated gemspec to declare dependency on v3.0.2 of core driver * Fixed defect in build process where JRuby gem was created with the same filename as mri gem. 1.0.0 rc1[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#1-0-0-rc1) ------------------------------------------------------------------------------------------------------- ### Features:[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/changelog/index.html#features) * Added Dse module with Cluster and Session classes for executing graph queries * Added DseAuthenticator authentication-type support * Added Kerberos authentication support * Added geospatial type support --- # DataStax Enterprise Ruby Driver - Authentication [DataStax Enterprise Ruby Driver 2.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication/) * Authentication[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication/index.html#authentication) ------------------------------------------------------------------------------------------------------------------------------- DSE 5.0 introduces [DSE Unified Authentication](http://docs.datastax.com/en/datastax_enterprise/5.0/datastax_enterprise/unifiedAuth/unifiedAuthConfig.html) , which supports multiple authentication schemes concurrently. Thus, different clients may authenticate with any authentication provider that is supported under the “unified authentication” umbrella: internal authentication, LDAP, and Kerberos. _NOTE:_ the authentication providers described below are backward-compatible with legacy authentication mechanisms provided by older DSE releases. So, feel free to use these providers regardless of your DSE environment. ### Internal and LDAP Authentication[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication/index.html#internal-and-ldap-authentication) Just as [Cassandra::Auth::Providers::Password](http://docs.datastax.com/en/developer/ruby-driver/3.0/api/cassandra/auth/providers/password) handles internal and LDAP authentication with Cassandra, the `Dse::Auth::Providers::Password` provider handles these types of authentication in DSE 5.0 configured with DseAuthenticator. The Ruby DSE driver makes it very easy to authenticate with username and password: `ruby cluster = Dse.cluster(username: 'user', password: 'pass')` The driver creates the provider under the hood and configures the cluster object appropriately. ### Kerberos Authentication[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication/index.html#kerberos-authentication) #### Initial Setup[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication/index.html#initial-setup) Unlike other authentication mechanisms, Kerberos requires some set-up on the client. First, set the `KRB5_CONFIG` environment variable to the location of your `krb5.conf` file and use `kinit` to obtain a ticket from your Kerberos server. This environment variable is also needed by the Ruby DSE driver when run in an MRI Ruby interpreter. This is due to the fact that Kerberos support is implemented as a C extension that uses the gssapi system libraries – the same libraries that command line tools like kinit use. The JRuby implementation of Kerberos support uses the Java security framework, which requires the `java.security.krb5.conf` system property to be set to the location of the `krb5.conf` file. One way to accomplish this is to set the `JRUBY_OPTS` environment variable before running your client application: export JRUBY_OPTS="-J-Djava.security.krb5.conf=/home/user1/krb5.conf" #### Configuring the Client[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication/index.html#configuring-the-client) To enable kerberos authentication with DSE nodes, set the `auth_provider` of the cluster to a `Dse::Auth::Providers::GssApi` instance. The following example code shows all the ways to set this up. require 'dse' # Create a provider for the 'dse' service and have it use the first ticket in the default ticket cache for # authentication with nodes, which have hostname entries in the Kerberos server. All of the # assignments below are equivalent: provider = Dse::Auth::Providers::GssApi.new provider = Dse::Auth::Providers::GssApi.new('dse') provider = Dse::Auth::Providers::GssApi.new('dse', true) provider = Dse::Auth::Providers::GssApi.new('dse', true, nil) # Same as above, but this time turn off hostname resolution because the Kerberos server # may be configured with ip's, not hostnames, of DSE nodes. provider = Dse::Auth::Providers::GssApi.new('dse', false) # Use a custom hostname resolver. class MyResolver def resolve(ip) "host-#{ip}" end end provider = Dse::Auth::Providers::GssApi.new('dse', MyResolver.new) # Specify different principal to use for authentication. This principal must already have a valid # ticket in the Kerberos ticket cache. Also, the principal name is case-sensitive, so make sure it # *exactly* matches your Kerberos ticket. provider = Dse::Auth::Providers::GssApi.new('dse', true, 'cassandra@DATASTAX.COM') # However you configure the provider, pass it to Dse.cluster to have it be used for authentication. cluster = Dse.cluster(auth_provider: provider) #### Ticket Caches[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication/index.html#ticket-caches) By default, `kinit` and related tools (e.g. `klist`, `kdestroy`) manipulate a simple file tied to the client os user’s numeric id on Linux: `/tmp/krb5cc_`. This file only supports one “ticket granting ticket”, so if you have a need for multiple credentials in your system (e.g. multiple applications each of which need to authenticate with different credentials to different services), you can supply the `-c` argument to kinit to authenticate and store the resulting ticket in a different cache. In that set-up, you must initialize your `auth_provider` in the driver with this info: # The fourth arg is the path to the cache file. provider = Dse::Auth::Providers::GssApi.new('dse', true, nil, '/home/myuser/krb.cache') For MRI (the underlying gssapi C library, actually), you can set the `KRB5CCNAME` environment variable instead of supplying an extra argument to the provider constructor. Mac supports non-default caches as well, but it’s not necessary because by default the default cache is an in-memory store that supports multiple tickets. --- # DataStax Enterprise Ruby Driver - Home [DataStax Enterprise Ruby Driver 2.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/) * DataStax Enterprise Ruby Driver[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#data-stax-enterprise-ruby-driver) ========================================================================================================================================== _NOTE: The DataStax Enterprise Ruby Driver can be used solely with DataStax Enterprise. Please consult [the license](http://www.datastax.com/terms/datastax-dse-driver-license-terms) ._ This driver is built on top of the [DataStax Ruby driver for Apache Cassandra](http://docs.datastax.com/en/developer/ruby-driver/3.0) and enhanced for the adaptive data management and mixed workload capabilities provided by DSE. Therefore a lot of the underlying concepts are the same. Documentation[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#documentation) ----------------------------------------------------------------------------------------------------- Driver documentation can be found [here](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/) . In particular, you’ll find our [Features](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features) and [API](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api) sections very enlightening. Feedback Requested[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#feedback-requested) --------------------------------------------------------------------------------------------------------------- _Help us focus our efforts!_ [Provide your input](http://goo.gl/forms/pCs8PTpHLf) on the Ruby Driver Platform and Runtime Survey (we kept it short). If you find an issue, please file an issue in our [public JIRA](https://datastax-oss.atlassian.net/browse/RUBY) . _Please be sure to specify the affects-version (DSE-1.X.Y)._ You can also post questions in [our forum](https://groups.google.com/a/lists.datastax.com/forum/#!forum/ruby-driver-user) . Features[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#features) ------------------------------------------------------------------------------------------- This driver exposes the following features of DSE 5.0: * [Graph](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph#graph) * [Authentication](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication#authentication) with nodes running DSE * [Geospatial types](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/geospatial#geospatial-types) Note that this driver is fully compatible with previous versions of DataStax Enterprise. Installation[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#installation) --------------------------------------------------------------------------------------------------- The driver is named dse-driver on rubygems.org and can easily be installed with Bundler or the gem program. It will download the appropriate Cassandra driver as well. Upgrade[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#upgrade) ----------------------------------------------------------------------------------------- The driver is intended to have the same look and feel as the core driver to make upgrading from the core driver trivial. The only change is to replace references to the `Cassandra` module with `Dse` when creating the cluster object: require 'dse' # This returns a Dse::Cluster instance cluster = Dse.cluster # This returns a Dse::Session instance session = cluster.connect rs = session.execute('select * from system.local') Breaking changes in 2.0[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#breaking-changes-in-2-0) ------------------------------------------------------------------------------------------------------------------------- This release adds support for [graph execution profiles](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph#execution-profiles) . As a result, the cluster-level `graph_options` object has been removed. That object is effectively stored in the `:default_graph` execution profile. However, since execution profiles are read-only, graph options in profiles cannot be manipulated. Instead, either specify new graph options at query execution time, or use separate execution profiles for your different scenarios. Furthermore, the `Dse::Graph::Options` class is no longer in the public api. Instead of constructing a `Dse::Graph::Options` object and passing it to `Session.execute_graph*`, you must now pass the primitive graph options or specify the name of an execution profile that encapsulates the desired graph options. Similarly, when creating a `Dse::Graph::Statement`, you must specify primitive graph options instead of a `Dse::Graph::Options` object. Since execution profiles are immutable, you must set expert options at construction time with the `expert_options` hash. See the [documentation](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph#expert-options) for more details. Another behavior change is that in v1.x, graph query timeout defaulted to unlimited. This caused queries to fall back to server timeouts. The default was set this way to accommodate multi-day analytics queries and multi-second OLTP queries without requiring intervention / special handling from the user. The introduction of execution profiles into the driver enables the user to more easily run different types of queries: # Use the default graph profile with its OLTP-motivated timeout (30 seconds) rs = session.execute_graph('g.V()') # Use the default graph analytics profile for an OLAP query (timeout 7 days) rs = session.execute_graph('g.V()', execution_profile: :default_graph_analytics # Use the default system query profile for graph system queries (timeout 3 minutes) rs = session.execute_graph("system.graph('mygraph').exists()", execution_profile: :default_graph_system) Thus, no query runs with unlimited timeout by default as of this version of the driver. Finally, in v1.x, graph query timeout was specified via the `:timeout` option in calls to `Session.execute_graph*` or packaged up in a graph options object. Since the graph execution profile now assumes the role of graph options, use the `:timeout` attribute in the graph execution profile to specify graph timeout. In particular, to set the default graph timeout for graph queries, you must define your own `:default_graph` execution profile that will take precedence over one that would normally be generated by the driver: cluster = Dse.cluster(execution_profiles: { default_graph: Dse::Graph::ExecutionProfile.new(timeout: 17, graph_name: 'mygraph') }) In the example above, the default graph timeout is set to 17 seconds. Note that you are not permitted to mix primitive options (that are now available in execution profiles) with an execution\_profiles hash when creating the cluster object: # Illegal! cluster = Dse.cluster(execution_profiles: { default_graph: Dse::Graph::ExecutionProfile.new(timeout: 17, graph_name: 'mygraph') }, timeout: 7) Thus, in order to specify that non-graph queries should execute with a timeout of 7 seconds by default, you must override the Cassandra default execution profile, named `:default`: # Legal. cluster = Dse.cluster(execution_profiles: { default_graph: Dse::Graph::ExecutionProfile.new(timeout: 17, graph_name: 'mygraph'), default: Cassandra::Execution::Profile.new(timeout: 7) }) Determining driver versions[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#determining-driver-versions) --------------------------------------------------------------------------------------------------------------------------------- Within a script or irb, you can determine the exact versions of the dse and core drivers by accessing the VERSION constant of the appropriate module: require 'dse' puts "Dse Driver Version: #{Dse::VERSION}" puts "Cassandra Driver Version: #{Cassandra::VERSION}" Compatibility[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#compatibility) ----------------------------------------------------------------------------------------------------- Although this driver exposes new features introduced in DSE 5.0, it is fully compatible and supported for use with previous versions of DSE. License[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/index.html#license) ----------------------------------------------------------------------------------------- Copyright © 2016 DataStax Inc. The full license terms are available at [http://www.datastax.com/terms/datastax-dse-driver-license-terms](http://www.datastax.com/terms/datastax-dse-driver-license-terms) --- # DataStax Enterprise Ruby Driver - Features [DataStax Enterprise Ruby Driver 2.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/) * This release exposes three major features of DataStax Enterprise 5.0: * [DSE Graph](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph) * [DSE Unified Authentication](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication) , which includes Kerberos support * [Geospatial Types](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/geospatial) Note that this driver is fully compatible with previous versions of DataStax Enterprise. --- # DataStax Enterprise Ruby Driver - Geospatial Types [DataStax Enterprise Ruby Driver 2.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/geospatial/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/geospatial/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/geospatial/) * Geospatial Types[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/geospatial/index.html#geospatial-types) ------------------------------------------------------------------------------------------------------------------------------- DataStax Enterprise v5.0 adds support for three geospatial types in the underlying Cassandra 3.x database. Instances of these types can be expressed in [well-known text (WKT)](https://en.wikipedia.org/wiki/Well-known_text) form as well as a binary representation known as [well-known binary (WKB)](https://en.wikipedia.org/wiki/Well-known_text#Well-known_binary) . This latter representation is sent over the wire between the client and DSE node, but the former makes it easy to submit queries with geospatial type references in cqlsh. For example, if you had a `points` table with an int key `f1` and a PointType column `p`, you could insert a row into it like this in cqlsh: `INSERT INTO points (f1, p) VALUES (7, 'POINT (32.0 12.0)');` You can compose points into line-strings and you can compose line-strings into polygons. See [this section of the WKT documentation](https://en.wikipedia.org/wiki/Well-known_text#Geometric_objects) for details. ### Point[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/geospatial/index.html#point) A _Point_ is a point with x,y coordinates. Columns in DSE have the custom type `org.apache.cassandra.db.marshal.PointType`. # The geospatial types are defined in the Dse::Geometry module. Save some typing and include it # here so that we can refer to the classes with their base names. include Dse::Geometry # Create a table with a PointType column and insert a row into it. session.execute("CREATE TABLE IF NOT EXISTS points_of_interest" \ " (name text PRIMARY KEY, coords 'PointType')") session.execute('INSERT INTO points_of_interest (name, coords) VALUES (?, ?)', arguments: ['Empire State', Point.new(38.0, 21.0)]) # Now retrieve the point. rs = session.execute('SELECT * FROM points_of_interest') rs.each do |row| # We can emit the point in its WKT representation. puts "#{row['name']} #{row['coords'].wkt}" # Or the x and y coordinates puts "#{row['name']} #{row['coords'].x},#{row['coords'].y}" # Which is really the to_s of the point, so you can do this: puts "#{row['name']} #{row['coords']}" end ### LineString[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/geospatial/index.html#line-string) A _LineString_ is a set of lines, characterized by a sequence of \*Point\*s. As \*Point\*s live in the 2D xy-plane, so do \*LineString\*s. Each line shares a point with another line, thus forming a string of lines. A real-world example of this is a path on a map. Columns in DSE have the custom type `org.apache.cassandra.db.marshal.LineStringType`. # The geospatial types are defined in the Dse::Geometry module. Save some typing and include it # here so that we can refer to the classes with their base names. include Dse::Geometry # Create a table with a LineString column and insert a row into it. session.execute("CREATE TABLE IF NOT EXISTS directions" \ " (origin text PRIMARY KEY, destination text, directions 'LineStringType')") session.execute('INSERT INTO directions (origin, destination, directions) VALUES (?, ?, ?)', arguments: ['office', 'home', LineString.new(Point.new(12.0, 21.0),\ Point.new(13.0, 31.0),\ Point.new(14.0, 41.0))]) # Now retrieve the line-string. rs = session.execute('SELECT * FROM directions') rs.each do |row| directions = row['directions'].points.map do |point| "#{point.x},#{point.y}" end.join(" to ") puts "Directions from #{row['origin']} to #{row['destination']}: #{directions}" # Or more simply (thanks to an overridden to_s) puts "Directions from #{row['origin']} to #{row['destination']}: #{row['directions']}" # And its wkt for fun puts "WKT: #{row['directions'].wkt}" end ### Polygon[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/geospatial/index.html#polygon) A _Polygon_ is an enclosed shape consisting of a set of linear-rings. A linear-ring is a _LineString_ whose last point is the same as its first point (thus forming a ring when you connect the points). The first ring specified in a polygon defines the outer edges of the polygon and is called the exterior ring. A polygon may also have holes within it, specified by other linear-rings, and those holes may contain linear-rings indicating islands. All such rings are called interior rings. # The geospatial types are defined in the Dse::Geometry module. Save some typing and include it # here so that we can refer to the classes with their base names. include Dse::Geometry # Create a table with a Polygon column and insert a row into it. A polygon consists of a set # of linear-rings. A linear-ring is a LineString whose last point is the same as its first point. session.execute("CREATE TABLE IF NOT EXISTS places (name text PRIMARY KEY, layout 'PolygonType')") exterior_ring = LineString.new(Point.new(0, 0), Point.new(20, 0), Point.new(26, 26), Point.new(0, 26), Point.new(0, 0)) interior_ring = LineString.new(Point.new(1, 1), Point.new(1, 5), Point.new(5, 5), Point.new(5, 1), Point.new(1, 1)) session.execute('INSERT INTO places (name, layout) VALUES (?, ?)', arguments: ['Capitol', Polygon.new(exterior_ring, interior_ring)]) # Now retrieve the polygon rs = session.execute('SELECT * FROM places') rs.each do |row| puts "Layout of #{row['name']}:" # Write out the exterior ring puts "Exterior: #{row['layout'].exterior_ring}" # Write out the first point in the first interior ring...because we can. puts "First interior point: #{row['layout'].interior_rings.first.points.first}" # Finally, let's emit the WKT representation. puts "WKT: #{row['layout'].wkt}" end --- # DataStax Enterprise Ruby Driver - Dse [DataStax Enterprise Ruby Driver 2.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/) * module Dse[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#module-dse) ======================================================================================================= Includes[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#includes) --------------------------------------------------------------------------------------------------- * `Cassandra::Statements` Modules[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#modules) ------------------------------------------------------------------------------------------------- * `[Auth](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/auth/ "Dse::Auth (module)") ` * `[Geometry](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/geometry/ "Dse::Geometry (module)") ` * `[Graph](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/graph/ "Dse::Graph (module)") ` * `[LoadBalancing](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/load_balancing/ "Dse::LoadBalancing (module)") ` Classes[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#classes) ------------------------------------------------------------------------------------------------- * `[Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/cluster/ "Dse::Cluster (class)") ` * `[Session](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/session/ "Dse::Session (class)") ` Constants[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#constants) ----------------------------------------------------------------------------------------------------- ### VERSION[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#version-constant) '2.0.0'.freeze Methods[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#methods) ------------------------------------------------------------------------------------------------- _self._ ### **cluster**[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#cluster-class_method) (options = {}) Creates a `[Cluster instance](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/cluster/ "Dse::Cluster (class)") `, which extends [Cassandra::Cluster](http://docs.datastax.com/en/developer/ruby-driver/3.0/api/cassandra/cluster "Cassandra::Cluster") . The API is identical, except that it returns a `[Dse::Session](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/session/ "Dse::Session (class)") ` (see below). It takes all of the same options as Cassandra.cluster and the following extra options. Examples: Connecting to localhost cluster = Dse.cluster Configuring `[Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/cluster/ "Dse::Cluster (class)") ` cluster = Dse.cluster( username: username, password: password, hosts: ['10.0.1.1', '10.0.1.2', '10.0.1.3'] ) Parameters: | Name | Type | Details | | --- | --- | --- | | options | `Hash` | _(defaults to: `{}`)_ a customizable set of options | Keys for options: | Key | Type | Details | | --- | --- | --- | | :graph\_name | `String` | name of graph to use in graph statements | | :graph\_source | `String` | graph traversal source | | :graph\_language | `String` | language used in graph queries | | :graph\_read\_consistency | `Cassandra::CONSISTENCIES` | read consistency level for graph statements. Overrides the standard statement consistency level | | :graph\_write\_consistency | `Cassandra::CONSISTENCIES` | write consistency level for graph statements. Overrides the standard statement consistency level | Returns: | Type | Details | | --- | --- | | `[Dse::Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/cluster/ "Dse::Cluster (class)") ` | a cluster instance | _self._ ### **cluster\_async**[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#cluster_async-class_method) (options = {}) Creates a `[Cluster instance](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/cluster/ "Dse::Cluster (class)") `. Returns: | Type | Details | | --- | --- | | `Cassandra::Future`<`[Dse::Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/cluster/ "Dse::Cluster (class)") `\> | a future resolving to the cluster instance. | See Also: * `[cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/index.html#cluster-class_method "Dse.cluster (method)") ` --- # DataStax Enterprise Ruby Driver - Graph [DataStax Enterprise Ruby Driver 2.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph/) * Graph[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/index.html#graph) ---------------------------------------------------------------------------------------------------- The DSE Graph service processes graph queries written in the [Gremlin](https://github.com/tinkerpop/gremlin/wiki) language. `Session#execute_graph` and `Session#execute_graph_async` are responsible for transmitting graph queries to DSE graph. The response is a graph result set, which may contain domain object representations of graph objects. A script using the DSE driver to execute graph queries will typically begin like this: require 'dse' # Connect to DSE and create a session whose graph queries will be tied to the graph # named 'mygraph' by default. See the documentation for Dse::Graph::Options for all # supported graph options. cluster = Dse.cluster(graph_name: 'mygraph') session = cluster.connect The DSE driver is a wrapper around the core Cassandra driver, so any valid options to the core driver are valid in the DSE driver as well. This includes specifying execution profiles. ### Execution Profiles[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/index.html#execution-profiles) Execution profiles were introduced in v3.1.0 of the Cassandra driver to group together a set of options for executing queries. The DSE driver provides the `Dse::Graph::ExecutionProfile` class to encapsulate graph options and core execution profile attributes. Graph execution profile attributes, like their Cassandra driver counterpart, fall back to system default values when not specified: * load\_balancing\_policy: `LoadBalancing::Policies::TokenAware.new(LoadBalancing::Policies::DCAwareRoundRobin.new, true)` * retry-policy: `Retry::Policies::Default.new` * consistency: `:local_one` The exception to this rule is that the timeout defaults to 30 seconds, while the Cassandra system default is 12. Most of the graph options default to `nil` and defer to values in server-side configuration. The following options, however, do have client-side defaults: \* graph\_source: `g` \* graph\_language: `gremlin-groovy` When querying these options in an execution profile, `nil` is returned. However, at request execution time, the appropriate defaults are sent in the request payload. The DSE driver initializes the following three default graph execution profiles: * `:default_graph` - used by default by `Session#execute_graph*` * timeout: `30` because graph queries tend to run longer than CQL queries. * `:default_graph_system` - useful when running system queries. * timeout: `180` because system queries typically run longer than ordinary graph queries since they are mutating the schema and must synchronize with multiple nodes. * `:default_graph_analytics` - useful for analytics queries * timeout: `604800`, which is 7 days because analytics queries can run for a very long time * graph\_source: `a` because analytics queries must run against the ‘analytics’ source. * load\_balancing\_policy: `Dse::LoadBalancing::Policies::HostTargeting.new()`, which gives priority to the analytics master node. Analytics queries must run on the analytics master, and without this policy, the client would likely send requests to a different (coordinator) node and that node would have to forward the request to the analytics master. Thus, this load-balancing policy saves a network hop. Unspecified options above fall back to the system defaults. If you define your own `:default_graph*` profiles, you must take care to set the options you want to override as well as options that you’d like to keep unchanged from the internally-built `:default_graph*` profile, since you don’t want your profile to fall back to system defaults (e.g. load-balancing-policy for the `:default_graph_analytics` profile). Graph options specified to `Dse#cluster` are stored in the `:default_graph` graph execution profile. Thus, without specifying any execution-profile parameters to `Dse#cluster`, the resulting profiles will often be as you want them. In the above example, we want graph queries to interact with graph `mygraph` most of the time. In addition, if the `graph_name` graph option is specified, it will be set into the `:default_graph_analytics` profile. Just as in the core driver, execution profiles provide default options for executing queries. Specify overrides as options to `Session#execute_graph`: session.execute_graph('g.V()', graph_name: 'starmap', execution_profile: :default_graph_analytics) Define entirely new profiles when creating the `cluster` object. Profile names should be strings or symbols, though they can be any type of object that has a reliable hashcode because ultimately the name becomes a key in a hash. cluster = Dse.cluster( execution_profiles: { test1: Dse::Graph::ExecutionProfile.new(graph_source: 'g', timeout: 5), 'test2' => Dse::Graph::ExecutionProfile.new(graph_source: 'a', timeout: 12) } ) session = cluster.connect result = session.execute_graph('g.V()', execution_profile: :test1) result2 = session.execute_graph('g.V()', execution_profile: 'test2') Note that it is illegal specify execution\_profiles and the above-mentioned primitive options when initializing the cluster. Define the `:default` and `:default_graph*` profiles as appropriate when you want to change default behavior _and_ define your own profiles. #### Expert Options[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/index.html#expert-options) In an effort to make the DSE driver compatible with future versions of DataStax Enterprise Graph, graph execution profiles also support specifying arbitrary key-value options. These “expert options” presumably exist in an as-yet unreleased version of DataStax Enterprise. To leverage this feature, simply supply an `expert_options` hash when creating your execution profile or execution your graph statement: profile = Dse::Graph::ExecutionProfile.new(graph_source: 'g', expert_options: {'some_option' => 'some_value'}) session.execute_graph('g.V()', expert_options: {'some_option' => 'some_value'}) ### Vertices[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/index.html#vertices) Vertices in DSE Graph have properties. A property may have multiple values. This is represented as an array when manipulating a Vertex object. A property value may also have properties of their own (known as meta-properties). These meta-properties are simple key-value pairs of strings; they do not nest. # Run a query to get all the vertices in our graph. results = session.execute_graph('g.V()') # Each result is a Dse::Graph::Vertex. # Print out the label and a few of its properties. puts "Number of vertex results: #{results.size}" results.each do |v| # Start with the label puts "#{v.label}:" # Vertex properties support multiple values as well as meta-properties # (simple key-value attributes that apply to a given property's value). # # Emit the 'name' property's first value. puts " name: #{v.properties['name'][0].value}" # Name again, using our abbreviated syntax puts " name: #{v['name'][0].value}" # Print all the values of the 'name' property values = v['name'].map do |vertex_prop| vertex_prop.value end puts " all names: #{values.join(',')}" # That's a little inconvenient. So use the 'values' shortcut: puts " all names: #{v['name'].values.join(',')}" # Let's get the 'title' meta-property of 'name's first value. puts " title: #{v['name'][0].properties['title']}" # This has a short-cut syntax as well: puts " title: #{v['name'][0]['title']}" end ### Edges[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/index.html#edges) Edges connect a pair of vertices in DSE Graph. They also have properties, but they are simple key-value pairs of strings. results = session.execute_graph('g.E()') puts "Number of edge results: #{results.size}" # Each result is a Dse::Graph::Edge object. results.each do |e| # Start with the label puts "#{e.label}:" # Now the id's of the two vertices that this edge connects. puts " in id: #{e.in_v}" puts " out id: #{e.out_v}" # Edge properties are simple key-value pairs; sort of like # meta-properties on vertices. puts " edge_prop1: #{e.properties['edge_prop1']}" # This supports the short-cut syntax as well: puts " edge_prop1: #{e['edge_prop1']}" end ### Path and Arbitrary Objects[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/index.html#path-and-arbitrary-objects) Paths describe a path between two vertices. The graph response from DSE does not indicate that the response is a path, so the driver cannot automatically coerce such results into Path objects. The driver returns a DSE::Graph::Result object in such cases, and you can coerce the result. results = session.execute_graph('g.V().in().path()') puts "Number of path results: #{results.size}" results.each do |r| # The 'value' of the result is a hash representation of the JSON result. puts "first label: #{r.value['labels'].first}" # Since we know this is a Path result, coerce it and use the Path object's methods. p = r.as_path puts "first label: #{p.labels.first}" end When a query has a simple result, the :value attribute of the result object contains the simple value rather than a hash. results = session.execute_graph('g.V().count()') puts "Number of vertices: #{results.first.value}" ### Duration Graph Type[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/index.html#duration-graph-type) DSE Graph supports several [datatypes](http://docs.datastax.com/en/latest-dse/datastax_enterprise/graph/reference/refDSEGraphDataTypes.html) for properties. The _Duration_ type represents a duration of time. When DSE Graph returns properties of this type, the string representation is non-trivial and requires parsing in order for the user to really gain any information from it. The driver includes a helper class to parse such responses from DSE graph as well as to send such values in bound paramters in requests: # Create a Duration property in the schema called 'runtime' and declare that 'process' vertices can have this property. session.execute_graph( "schema.propertyKey('runtime').Duration().ifNotExists().create(); schema.propertyKey('name').Text().ifNotExists().create(); schema.vertexLabel('process').properties('name', 'runtime').ifNotExists().create()") # We want to record that a process ran for 1 hour, 2 minutes, 3.5 seconds. runtime = Dse::Graph::Duration.new(0, 1, 2, 3.5) session.execute_graph( "graph.addVertex(label, 'process', 'name', 'calculator', 'runtime', my_runtime);", arguments: {'my_runtime' => runtime}) # Now retrieve the vertex. Assume this is the only vertex in the graph for simplicity. v = session.execute_graph('g.V()').first runtime = Dse::Graph::Duration.parse(v['runtime'].first.value) puts "#{runtime.hours} hours, #{runtime.minutes} minutes, #{runtime.seconds} seconds" ### Miscellaneous Features[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/index.html#miscellaneous-features) There are a number of other features in the api to make development easier. # We can access particular items in the result-set via array dereference p results[1] # Run a query against a different graph, but don't mess with the cluster default. results = session.execute_graph('g.V().count()', graph_name: 'my_other__graph') # Set an "expert" option for which we don't have a proper graph option. # NOTE: Such options are not part of the public api and may change in a future # release of DSE. results = session.execute_graph('g.V().count()', graph_name: 'my_other__graph', expert_options: {'super-cool-option' => 'value'}) # Create a statement object encapsulating a graph query, options, parameters, # for ease of reuse. statement = Dse::Graph::Statement.new('g.V().limit(n)', {n: 3}, graph_name: 'mygraph') results = session.execute_graph(statement) --- # DataStax Enterprise Ruby Driver - API docs [DataStax Enterprise Ruby Driver 2.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 2.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/) * API docs[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/index.html#api-docs) =============================================================================================== Modules[](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/index.html#modules) --------------------------------------------------------------------------------------------- * `[Dse](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/ "Dse (module)") ` --- # DataStax Enterprise Ruby Driver - Authentication [DataStax Enterprise Ruby Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 1.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/authentication/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/authentication/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication/) * Authentication[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication/index.html#authentication) ------------------------------------------------------------------------------------------------------------------------------- DSE 5.0 introduces [DSE Unified Authentication](http://docs.datastax.com/en/datastax_enterprise/5.0/datastax_enterprise/unifiedAuth/unifiedAuthConfig.html) , which supports multiple authentication schemes concurrently. Thus, different clients may authenticate with any authentication provider that is supported under the “unified authentication” umbrella: internal authentication, LDAP, and Kerberos. _NOTE:_ the authentication providers described below are backward-compatible with legacy authentication mechanisms provided by older DSE releases. So, feel free to use these providers regardless of your DSE environment. ### Internal and LDAP Authentication[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication/index.html#internal-and-ldap-authentication) Just as [Cassandra::Auth::Providers::Password](http://docs.datastax.com/en/developer/ruby-driver/3.0/api/cassandra/auth/providers/password/) handles internal and LDAP authentication with Cassandra, the `Dse::Auth::Providers::Password` provider handles these types of authentication in DSE 5.0 configured with DseAuthenticator. The Ruby DSE driver makes it very easy to authenticate with username and password: `ruby cluster = Dse.cluster(username: 'user', password: 'pass')` The driver creates the provider under the hood and configures the cluster object appropriately. ### Kerberos Authentication[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication/index.html#kerberos-authentication) #### Initial Setup[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication/index.html#initial-setup) Unlike other authentication mechanisms, Kerberos requires some set-up on the client. First, set the `KRB5_CONFIG` environment variable to the location of your `krb5.conf` file and use `kinit` to obtain a ticket from your Kerberos server. This environment variable is also needed by the Ruby DSE driver when run in an MRI Ruby interpreter. This is due to the fact that Kerberos support is implemented as a C extension that uses the gssapi system libraries – the same libraries that command line tools like kinit use. The JRuby implementation of Kerberos support uses the Java security framework, which requires the `java.security.krb5.conf` system property to be set to the location of the `krb5.conf` file. One way to accomplish this is to set the `JRUBY_OPTS` environment variable before running your client application: export JRUBY_OPTS="-J-Djava.security.krb5.conf=/home/user1/krb5.conf" #### Configuring the Client[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication/index.html#configuring-the-client) To enable kerberos authentication with DSE nodes, set the `auth_provider` of the cluster to a `Dse::Auth::Providers::GssApi` instance. The following example code shows all the ways to set this up. require 'dse' # Create a provider for the 'dse' service and have it use the first ticket in the default ticket cache for # authentication with nodes, which have hostname entries in the Kerberos server. All of the # assignments below are equivalent: provider = Dse::Auth::Providers::GssApi.new provider = Dse::Auth::Providers::GssApi.new('dse') provider = Dse::Auth::Providers::GssApi.new('dse', true) provider = Dse::Auth::Providers::GssApi.new('dse', true, nil) # Same as above, but this time turn off hostname resolution because the Kerberos server # may be configured with ip's, not hostnames, of DSE nodes. provider = Dse::Auth::Providers::GssApi.new('dse', false) # Use a custom hostname resolver. class MyResolver def resolve(ip) "host-#{ip}" end end provider = Dse::Auth::Providers::GssApi.new('dse', MyResolver.new) # Specify different principal to use for authentication. This principal must already have a valid # ticket in the Kerberos ticket cache. Also, the principal name is case-sensitive, so make sure it # *exactly* matches your Kerberos ticket. provider = Dse::Auth::Providers::GssApi.new('dse', true, 'cassandra@DATASTAX.COM') # However you configure the provider, pass it to Dse.cluster to have it be used for authentication. cluster = Dse.cluster(auth_provider: provider) #### Ticket Caches[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication/index.html#ticket-caches) By default, `kinit` and related tools (e.g. `klist`, `kdestroy`) manipulate a simple file tied to the client os user’s numeric id on Linux: `/tmp/krb5cc_`. This file only supports one “ticket granting ticket”, so if you have a need for multiple credentials in your system (e.g. multiple applications each of which need to authenticate with different credentials to different services), you can supply the `-c` argument to kinit to authenticate and store the resulting ticket in a different cache. In that set-up, you must initialize your `auth_provider` in the driver with this info: # The fourth arg is the path to the cache file. provider = Dse::Auth::Providers::GssApi.new('dse', true, nil, '/home/myuser/krb.cache') For MRI (the underlying gssapi C library, actually), you can set the `KRB5CCNAME` environment variable instead of supplying an extra argument to the provider constructor. Mac supports non-default caches as well, but it’s not necessary because by default the default cache is an in-memory store that supports multiple tickets. --- # DataStax Enterprise Ruby Driver - Features [DataStax Enterprise Ruby Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 1.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/) * This release exposes three major features of DataStax Enterprise 5.0: * [DSE Graph](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph) * [DSE Unified Authentication](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication) , which includes Kerberos support * [Geospatial Types](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/geospatial) Note that this driver is fully compatible with previous versions of DataStax Enterprise. --- # DataStax Enterprise Ruby Driver - Geospatial Types [DataStax Enterprise Ruby Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 1.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/geospatial/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/geospatial/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/geospatial/) * Geospatial Types[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/geospatial/index.html#geospatial-types) ------------------------------------------------------------------------------------------------------------------------------- DataStax Enterprise v5.0 adds support for three geospatial types in the underlying Cassandra 3.x database. Instances of these types can be expressed in [well-known text (WKT)](https://en.wikipedia.org/wiki/Well-known_text) form as well as a binary representation known as [well-known binary (WKB)](https://en.wikipedia.org/wiki/Well-known_text#Well-known_binary) . This latter representation is sent over the wire between the client and DSE node, but the former makes it easy to submit queries with geospatial type references in cqlsh. For example, if you had a `points` table with an int key `f1` and a PointType column `p`, you could insert a row into it like this in cqlsh: `INSERT INTO points (f1, p) VALUES (7, 'POINT (32.0 12.0)');` You can compose points into line-strings and you can compose line-strings into polygons. See [this section of the WKT documentation](https://en.wikipedia.org/wiki/Well-known_text#Geometric_objects) for details. ### Point[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/geospatial/index.html#point) A _Point_ is a point with x,y coordinates. Columns in DSE have the custom type `org.apache.cassandra.db.marshal.PointType`. # The geospatial types are defined in the Dse::Geometry module. Save some typing and include it # here so that we can refer to the classes with their base names. include Dse::Geometry # Create a table with a PointType column and insert a row into it. session.execute("CREATE TABLE IF NOT EXISTS points_of_interest" \ " (name text PRIMARY KEY, coords 'PointType')") session.execute('INSERT INTO points_of_interest (name, coords) VALUES (?, ?)', arguments: ['Empire State', Point.new(38.0, 21.0)]) # Now retrieve the point. rs = session.execute('SELECT * FROM points_of_interest') rs.each do |row| # We can emit the point in its WKT representation. puts "#{row['name']} #{row['coords'].wkt}" # Or the x and y coordinates puts "#{row['name']} #{row['coords'].x},#{row['coords'].y}" # Which is really the to_s of the point, so you can do this: puts "#{row['name']} #{row['coords']}" end ### LineString[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/geospatial/index.html#line-string) A _LineString_ is a set of lines, characterized by a sequence of \*Point\*s. As \*Point\*s live in the 2D xy-plane, so do \*LineString\*s. Each line shares a point with another line, thus forming a string of lines. A real-world example of this is a path on a map. Columns in DSE have the custom type `org.apache.cassandra.db.marshal.LineStringType`. # The geospatial types are defined in the Dse::Geometry module. Save some typing and include it # here so that we can refer to the classes with their base names. include Dse::Geometry # Create a table with a LineString column and insert a row into it. session.execute("CREATE TABLE IF NOT EXISTS directions" \ " (origin text PRIMARY KEY, destination text, directions 'LineStringType')") session.execute('INSERT INTO directions (origin, destination, directions) VALUES (?, ?, ?)', arguments: ['office', 'home', LineString.new(Point.new(12.0, 21.0),\ Point.new(13.0, 31.0),\ Point.new(14.0, 41.0))]) # Now retrieve the line-string. rs = session.execute('SELECT * FROM directions') rs.each do |row| directions = row['directions'].points.map do |point| "#{point.x},#{point.y}" end.join(" to ") puts "Directions from #{row['origin']} to #{row['destination']}: #{directions}" # Or more simply (thanks to an overridden to_s) puts "Directions from #{row['origin']} to #{row['destination']}: #{row['directions']}" # And its wkt for fun puts "WKT: #{row['directions'].wkt}" end ### Polygon[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/geospatial/index.html#polygon) A _Polygon_ is an enclosed shape consisting of a set of linear-rings. A linear-ring is a _LineString_ whose last point is the same as its first point (thus forming a ring when you connect the points). The first ring specified in a polygon defines the outer edges of the polygon and is called the exterior ring. A polygon may also have holes within it, specified by other linear-rings, and those holes may contain linear-rings indicating islands. All such rings are called interior rings. # The geospatial types are defined in the Dse::Geometry module. Save some typing and include it # here so that we can refer to the classes with their base names. include Dse::Geometry # Create a table with a Polygon column and insert a row into it. A polygon consists of a set # of linear-rings. A linear-ring is a LineString whose last point is the same as its first point. session.execute("CREATE TABLE IF NOT EXISTS places (name text PRIMARY KEY, layout 'PolygonType')") exterior_ring = LineString.new(Point.new(0, 0), Point.new(20, 0), Point.new(26, 26), Point.new(0, 26), Point.new(0, 0)) interior_ring = LineString.new(Point.new(1, 1), Point.new(1, 5), Point.new(5, 5), Point.new(5, 1), Point.new(1, 1)) session.execute('INSERT INTO places (name, layout) VALUES (?, ?)', arguments: ['Capitol', Polygon.new(exterior_ring, interior_ring)]) # Now retrieve the polygon rs = session.execute('SELECT * FROM places') rs.each do |row| puts "Layout of #{row['name']}:" # Write out the exterior ring puts "Exterior: #{row['layout'].exterior_ring}" # Write out the first point in the first interior ring...because we can. puts "First interior point: #{row['layout'].interior_rings.first.points.first}" # Finally, let's emit the WKT representation. puts "WKT: #{row['layout'].wkt}" end --- # DataStax Enterprise Ruby Driver - Graph [DataStax Enterprise Ruby Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 1.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/features/graph/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/features/graph/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph/) * Graph[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph/index.html#graph) ---------------------------------------------------------------------------------------------------- The DSE Graph service processes graph queries written in the [Gremlin](https://github.com/tinkerpop/gremlin/wiki) language. `Session#execute_graph` and `Session#execute_graph_async` are responsible for transmitting graph queries to DSE graph. The response is a graph result set, which may contain domain object representations of graph objects. Any script using the DSE driver to execute graph queries will begin like this: require 'dse' # Connect to DSE and create a session whose graph queries will be tied to the graph # named 'mygraph' by default. See the documentation for Dse::Graph::Options for all # supported graph options. cluster = Dse.cluster(graph_name: 'mygraph') session = cluster.connect The DSE driver is a wrapper around the core Cassandra driver, so any valid options to the core driver are valid in the DSE driver as well. To execute system query statements (to create a graph for example), _do not_ specify a graph name to bind to when connecting. This is illegal in DSE graph. ### Vertices[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph/index.html#vertices) Vertices in DSE Graph have properties. A property may have multiple values. This is represented as an array when manipulating a Vertex object. A property value may also have properties of their own (known as meta-properties). These meta-properties are simple key-value pairs of strings; they do not nest. # Run a query to get all the vertices in our graph. results = session.execute_graph('g.V()') # Each result is a Dse::Graph::Vertex. # Print out the label and a few of its properties. puts "Number of vertex results: #{results.size}" results.each do |v| # Start with the label puts "#{v.label}:" # Vertex properties support multiple values as well as meta-properties # (simple key-value attributes that apply to a given property's value). # # Emit the 'name' property's first value. puts " name: #{v.properties['name'][0].value}" # Name again, using our abbreviated syntax puts " name: #{v['name'][0].value}" # Print all the values of the 'name' property values = v['name'].map do |vertex_prop| vertex_prop.value end puts " all names: #{values.join(',')}" # That's a little inconvenient. So use the 'values' shortcut: puts " all names: #{v['name'].values.join(',')}" # Let's get the 'title' meta-property of 'name's first value. puts " title: #{v['name'][0].properties['title']}" # This has a short-cut syntax as well: puts " title: #{v['name'][0]['title']}" end ### Edges[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph/index.html#edges) Edges connect a pair of vertices in DSE Graph. They also have properties, but they are simple key-value pairs of strings. results = session.execute_graph('g.E()') puts "Number of edge results: #{results.size}" # Each result is a Dse::Graph::Edge object. results.each do |e| # Start with the label puts "#{e.label}:" # Now the id's of the two vertices that this edge connects. puts " in id: #{e.in_v}" puts " out id: #{e.out_v}" # Edge properties are simple key-value pairs; sort of like # meta-properties on vertices. puts " edge_prop1: #{e.properties['edge_prop1']}" # This supports the short-cut syntax as well: puts " edge_prop1: #{e['edge_prop1']}" end ### Path and Arbitrary Objects[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph/index.html#path-and-arbitrary-objects) Paths describe a path between two vertices. The graph response from DSE does not indicate that the response is a path, so the driver cannot automatically coerce such results into Path objects. The driver returns a DSE::Graph::Result object in such cases, and you can coerce the result. results = session.execute_graph('g.V().in().path()') puts "Number of path results: #{results.size}" results.each do |r| # The 'value' of the result is a hash representation of the JSON result. puts "first label: #{r.value['labels'].first}" # Since we know this is a Path result, coerce it and use the Path object's methods. p = r.as_path puts "first label: #{p.labels.first}" end When a query has a simple result, the :value attribute of the result object contains the simple value rather than a hash. results = session.execute_graph('g.V().count()') puts "Number of vertices: #{results.first.value}" ### Duration Graph Type[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph/index.html#duration-graph-type) DSE Graph supports several [datatypes](http://docs.datastax.com/en/latest-dse/datastax_enterprise/graph/reference/refDSEGraphDataTypes.html) for properties. The _Duration_ type represents a duration of time. When DSE Graph returns properties of this type, the string representation is non-trivial and requires parsing in order for the user to really gain any information from it. The driver includes a helper class to parse such responses from DSE graph as well as to send such values in bound paramters in requests: # Create a Duration property in the schema called 'runtime' and declare that 'process' vertices can have this property. session.execute_graph( "schema.propertyKey('runtime').Duration().ifNotExists().create(); schema.propertyKey('name').Text().ifNotExists().create(); schema.vertexLabel('process').properties('name', 'runtime').ifNotExists().create()") # We want to record that a process ran for 1 hour, 2 minutes, 3.5 seconds. runtime = Dse::Graph::Duration.new(0, 1, 2, 3.5) session.execute_graph( "graph.addVertex(label, 'process', 'name', 'calculator', 'runtime', my_runtime);", arguments: {'my_runtime' => runtime}) # Now retrieve the vertex. Assume this is the only vertex in the graph for simplicity. v = session.execute_graph('g.V()').first runtime = Dse::Graph::Duration.parse(v['runtime'].first.value) puts "#{runtime.hours} hours, #{runtime.minutes} minutes, #{runtime.seconds} seconds" ### Miscellaneous Features[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph/index.html#miscellaneous-features) There are a number of other features in the api to make development easier. # We can access particular items in the result-set via array dereference p results[1] # Run a query against a different graph, but don't mess with the cluster default. results = session.execute_graph('g.V().count()', graph_name: 'my_other__graph') # Create a Graph Options object that we can save off and use. The graph_options arg to execute_graph # supports an Options object. options = Dse::Graph::Options.new options.graph_name = 'mygraph' results = session.execute_graph('g.V().count()', graph_options: options) # Set an "expert" option for which we don't have accessor methods. # NOTE: Such options are not part of the public api and may change in a future release of DSE. options.set('super-cool-option', true) # Change the graph options on the cluster to alter subsequent query behavior. # Switch to the analytics source in this case. cluster.graph_options.graph_source = 'a' results = session.execute_graph('g.V().count()') # Create a statement object encapsulating a graph query, options, parameters, # for ease of reuse. statement = Dse::Graph::Statement.new('g.V().limit(n)', {n: 3}, graph_name: 'mygraph') results = session.execute_graph(statement) --- # DataStax Enterprise Ruby Driver - Home [DataStax Enterprise Ruby Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 1.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/) * DataStax Enterprise Ruby Driver[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/index.html#data-stax-enterprise-ruby-driver) ========================================================================================================================================== _NOTE: The DataStax Enterprise Ruby Driver can be used solely with DataStax Enterprise. Please consult [the license](http://www.datastax.com/terms/datastax-dse-driver-license-terms) ._ This driver is built on top of the [DataStax Ruby driver for Apache Cassandra](http://docs.datastax.com/en/developer/ruby-driver/latest) and enhanced for the adaptive data management and mixed workload capabilities provided by DSE. Therefore a lot of the underlying concepts are the same. Documentation[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/index.html#documentation) ----------------------------------------------------------------------------------------------------- Driver documentation can be found [here](http://docs.datastax.com/en/developer/ruby-driver-dse/latest) . In particular, you’ll find our [Features](http://docs.datastax.com/en/developer/ruby-driver-dse/latest/features) and [API](http://docs.datastax.com/en/developer/ruby-driver-dse/latest/api) sections very enlightening. Feedback Requested[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/index.html#feedback-requested) --------------------------------------------------------------------------------------------------------------- _Help us focus our efforts!_ [Provide your input](http://goo.gl/forms/pCs8PTpHLf) on the Ruby Driver Platform and Runtime Survey (we kept it short). If you find an issue, please file an issue in our [public JIRA](https://datastax-oss.atlassian.net/browse/RUBY) . _Please be sure to specify the affects-version (DSE-1.X.Y)._ You can also post questions in [our forum](https://groups.google.com/a/lists.datastax.com/forum/#!forum/ruby-driver-user) . Features[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/index.html#features) ------------------------------------------------------------------------------------------- This driver exposes the following features of DSE 5.0: * [Graph](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/graph#graph) * [Authentication](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/authentication#authentication) with nodes running DSE * [Geospatial types](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/features/geospatial#geospatial-types) Note that this driver is fully compatible with previous versions of DataStax Enterprise. Installation[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/index.html#installation) --------------------------------------------------------------------------------------------------- The driver is named dse-driver on rubygems.org and can easily be installed with Bundler or the gem program. It will download the appropriate Cassandra driver as well. Upgrade[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/index.html#upgrade) ----------------------------------------------------------------------------------------- The driver is intended to have the same look and feel as the core driver to make upgrading from the core driver trivial. The only change is to replace references to the `Cassandra` module with `Dse` when creating the cluster object: require 'dse' # This returns a Dse::Cluster instance cluster = Dse.cluster # This returns a Dse::Session instance session = cluster.connect rs = session.execute('select * from system.local') Determining driver versions[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/index.html#determining-driver-versions) --------------------------------------------------------------------------------------------------------------------------------- Within a script or irb, you can determine the exact versions of the dse and core drivers by accessing the VERSION constant of the appropriate module: require 'dse' puts "Dse Driver Version: #{Dse::VERSION}" puts "Cassandra Driver Version: #{Cassandra::VERSION}" Compatibility[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/index.html#compatibility) ----------------------------------------------------------------------------------------------------- Although this driver exposes new features introduced in DSE 5.0, it is fully compatible and supported for use with previous versions of DSE. License[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/index.html#license) ----------------------------------------------------------------------------------------- Copyright © 2016 DataStax Inc. The full license terms are available at [http://www.datastax.com/terms/datastax-dse-driver-license-terms](http://www.datastax.com/terms/datastax-dse-driver-license-terms) --- # DataStax Enterprise Ruby Driver - Dse [DataStax Enterprise Ruby Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 1.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/dse/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/dse/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/) * module Dse[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#module-dse) ======================================================================================================= Includes[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#includes) --------------------------------------------------------------------------------------------------- * `Cassandra::Statements` Modules[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#modules) ------------------------------------------------------------------------------------------------- * `[Auth](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/auth/ "Dse::Auth (module)") ` * `[Geometry](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/geometry/ "Dse::Geometry (module)") ` * `[Graph](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/graph/ "Dse::Graph (module)") ` * `[LoadBalancing](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/load_balancing/ "Dse::LoadBalancing (module)") ` Classes[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#classes) ------------------------------------------------------------------------------------------------- * `[Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/cluster/ "Dse::Cluster (class)") ` * `[Session](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/session/ "Dse::Session (class)") ` Constants[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#constants) ----------------------------------------------------------------------------------------------------- ### VERSION[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#version-constant) '1.0.1'.freeze Methods[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#methods) ------------------------------------------------------------------------------------------------- _self._ ### **cluster**[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#cluster-class_method) (options = {}) Creates a `[Cluster instance](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/cluster/ "Dse::Cluster (class)") `, which extends [Cassandra::Cluster](http://docs.datastax.com/en/developer/ruby-driver/3.0/api/cassandra/cluster "Cassandra::Cluster") . The API is identical, except that it returns a `[Dse::Session](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/session/ "Dse::Session (class)") ` (see below). It takes all of the same options as Cassandra.cluster and the following extra options. Examples: Connecting to localhost cluster = Dse.cluster Configuring `[Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/cluster/ "Dse::Cluster (class)") ` cluster = Dse.cluster( username: username, password: password, hosts: ['10.0.1.1', '10.0.1.2', '10.0.1.3'] ) Parameters: | Name | Type | Details | | --- | --- | --- | | options | `Hash` | _(defaults to: `{}`)_ a customizable set of options | Keys for options: | Key | Type | Details | | --- | --- | --- | | :graph\_options | `[Dse::Graph::Options](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/graph/options/ "Dse::Graph::Options (class)") ` | options for the DSE graph statement handler. Takes priority over other `:graph_*` options specified below. | | :graph\_name | `String` | name of graph to use in graph statements | | :graph\_source | `String` | graph traversal source | | :graph\_language | `String` | language used in graph queries | | :graph\_read\_consistency | `Cassandra::CONSISTENCIES` | read consistency level for graph statements. Overrides the standard statement consistency level | | :graph\_write\_consistency | `Cassandra::CONSISTENCIES` | write consistency level for graph statements. Overrides the standard statement consistency level | Returns: | Type | Details | | --- | --- | | `[Dse::Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/cluster/ "Dse::Cluster (class)") ` | a cluster instance | _self._ ### **cluster\_async**[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#cluster_async-class_method) (options = {}) Creates a `[Cluster instance](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/cluster/ "Dse::Cluster (class)") `. Returns: | Type | Details | | --- | --- | | `Cassandra::Future`<`[Dse::Cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/cluster/ "Dse::Cluster (class)") `\> | a future resolving to the cluster instance. | See Also: * `[cluster](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/index.html#cluster-class_method "Dse.cluster (method)") ` --- # DataStax Enterprise Ruby Driver - API docs [DataStax Enterprise Ruby Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/ruby-driver-dse/index.html) 1.0 * [2.1](https://docs.datastax.com/en/developer/ruby-driver-dse/2.1/api/) * [2.0](https://docs.datastax.com/en/developer/ruby-driver-dse/2.0/api/) * [1.0](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/) * API docs[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/index.html#api-docs) =============================================================================================== Modules[](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/index.html#modules) --------------------------------------------------------------------------------------------- * `[Dse](https://docs.datastax.com/en/developer/ruby-driver-dse/1.0/api/dse/ "Dse (module)") ` --- # DataStax Enterprise PHP Driver - Building PHP Extension [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/) * Building PHP Extension[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#building-php-extension) =============================================================================================================================== The PHP DSE driver is implemented as a native PHP extension and leverages the [C/C++ DSE driver](http://docs.datastax.com/en/developer/cpp-driver-dse/latest) . The driver will build on most standard Unix-like and Microsoft Windows platforms. Packages are available for the following platforms: * [CentOS 6](http://downloads.datastax.com/php-driver/centos/6/dse) * [CentOS 7](http://downloads.datastax.com/php-driver/centos/7/dse) * [Ubuntu 14.04 LTS](http://downloads.datastax.com/php-driver/ubuntu/14.04/dse) * [Ubuntu 16.04 LTS](http://downloads.datastax.com/php-driver/ubuntu/16.04/dse) * [Windows](http://downloads.datastax.com/php-driver/windows/dse) **NOTE**: The build procedures only need to be performed for driver development or if your system doesn’t have packages available for download and installation. Compatibility[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#compatibility) ------------------------------------------------------------------------------------------------------------- * PHP 5.6, PHP 7.0, and PHP 7.1 * 32-bit (x86) and 64-bit (x64) * Thread safe (TS) and non-thread safe (NTS) * Compilers: GCC 4.1.2+, Clang 3.4+, and MSVC 2012/2015 Dependencies[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#dependencies) ----------------------------------------------------------------------------------------------------------- The DSE PHP Extension depends on the following software: * [The C/C++ DSE driver](http://docs.datastax.com/en/developer/cpp-driver-dse/latest/building) * [CMake](http://www.cmake.org/download) v2.6.4+ * [libuv](http://libuv.org/) 1.x * Kerberos v5 ([Heimdal](https://www.h5l.org/) or [MIT](https://web.mit.edu/kerberos) ) * [OpenSSL](https://www.openssl.org/) v1.0.x or v1.1.x * [The GNU Multiple Precision Arithmetic Library](https://gmplib.org/) Linux/Mac OS[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#linux-mac-os) ----------------------------------------------------------------------------------------------------------- The driver is known to build on CentOS/RHEL 6/7, Mac OS X 10.10/10.11 (Yosemite and El Capitan), Mac OS 10.12 (Sierra), and Ubuntu 14.04/16.04 LTS. **NOTE**: The driver will also build on most standard Unix-like systems using GCC 4.1.2+ or Clang 3.4+. ### Installing dependencies[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#installing-dependencies) #### Initial environment setup[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#initial-environment-setup) ##### CentOS/RHEL 6 (Yum)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#centos-rhel-6-yum) CentOS/RHEL 6 ships with PHP v5.3.x as the default version of PHP; which is not supported. A supported version of PHP can be installed by performing the following: yum install epel-release rpm -Uvh https://mirror.webtatic.com/yum/el6/latest.rpm Once completed PHP v5.6.x, v7.0.x, or v7.1.x can be installed: yum install automake cmake gcc-c++ git libtool pcre-devel php71w-devel php71w-pear ##### CentOS/RHEL 7 (Yum)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#centos-rhel-7-yum) CentOS/RHEL 7 ships with PHP v5.4.x as the default version of PHP; which is not supported. A supported version of PHP can be installed by performing the following: yum install epel-release rpm -Uvh https://mirror.webtatic.com/yum/el7/latest.rpm Once completed PHP v5.6.x, v7.0.x, or v7.1.x can be installed: yum install automake cmake gcc-c++ git libtool pcre-devel php71w-devel php71w-pear ##### Ubuntu 14.04 (APT)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#ubuntu-14-04-apt) Ubuntu 14.04 LTS (Debian 8) ships with PHP v5.5.x as the default version of PHP; which is not supported. A supported version of PHP can be installed by performing the following: add-apt-repository ppa:ondrej/php apt-get update Once completed PHP v5.6.x, v7.0.x, or v7.1.x can be installed: apt-get install build-essential cmake git libpcre3-dev php7.1-dev ##### Ubuntu 16.04 (APT)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#ubuntu-16-04-apt) Starting with Ubuntu 16.04 LTS (Debian 9) PHP v5.5.x has been removed as the default version of PHP and has been replaced with either PHP v7.0.x or PHP v7.1.x: apt-get install build-essential cmake git libpcre3-dev php7.1-dev ##### Mac OS (Brew)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#mac-os-brew) brew update brew upgrade brew tap homebrew/homebrew-php brew install autoconf automake libtool php71 #### GNU Multiple Precision Arithmetic[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#gnu-multiple-precision-arithmetic) ##### CentOS/RHEL (Yum)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#centos-rhel-yum) yum install gmp-devel ##### Ubuntu (APT)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#ubuntu-apt) apt-get install libgmp-dev ##### Mac OS (Brew)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#mac-os-brew) brew install gmp #### Kerberos[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#kerberos) ##### CentOS/RHEL (Yum)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#centos-rhel-yum) yum install krb5-devel ##### Ubuntu (APT)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#ubuntu-apt) apt-get install libkrb5-dev #### libuv[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#libuv) libuv v1.x should be used in order to ensure all features of the C/C++ DSE driver and the PHP DSE driver are available. When using a package manager for your operating system make sure you install v1.x; if available. ##### CentOS/RHEL and Ubuntu packages[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#centos-rhel-and-ubuntu-packages) Packages are available from our [download server](http://downloads.datastax.com/) : * [CentOS 6](http://downloads.datastax.com/cpp-driver/centos/6/dependencies/libuv) * [CentOS 7](http://downloads.datastax.com/cpp-driver/centos/7/dependencies/libuv) * [Ubuntu 14.04 LTS](http://downloads.datastax.com/cpp-driver/ubuntu/14.04/dependencies/libuv) * [Ubuntu 16.04 LTS](http://downloads.datastax.com/cpp-driver/ubuntu/16.04/dependencies/libuv) ##### Mac OS (Brew)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#mac-os-brew) brew install libuv ##### Manually build and install[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#manually-build-and-install) The following procedures should be performed if packages are not available for your system. pushd /tmp wget http://dist.libuv.org/dist/v1.13.1/libuv-v1.13.1.tar.gz tar xzf libuv-v1.13.1.tar.gz pushd libuv-v1.13.1 sh autogen.sh ./configure make install popd popd #### OpenSSL[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#openssl) ##### CentOS (Yum)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#centos-yum) yum install openssl-devel ##### Ubuntu (APT)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#ubuntu-apt) apt-get install libssl-dev ##### Mac OS (Brew)[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#mac-os-brew) brew install openssl **NOTE**: For Mac OS X 10.11 (El Capitan) and Mac OS 10.12 (Sierra) a link needs to be created in order to make OpenSSL available to the building libraries: brew link --force openssl #### C/C++ DSE driver[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#c-c-dse-driver) ##### CentOS/RHEL and Ubuntu packages[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#centos-rhel-and-ubuntu-packages) Packages are available from our [download server](http://downloads.datastax.com/) and the latest version of the driver be used: * [CentOS 6](http://downloads.datastax.com/cpp-driver/centos/6/dse) * [CentOS 7](http://downloads.datastax.com/cpp-driver/centos/7/dse) * [Ubuntu 14.04 LTS](http://downloads.datastax.com/cpp-driver/ubuntu/14.04/dse) * [Ubuntu 16.04 LTS](http://downloads.datastax.com/cpp-driver/ubuntu/16.04/dse) ##### Manually build and install[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#manually-build-and-install) The following procedures should be performed if packages are not available for your system. The C/C++ DSE driver is made available as a submodule; if preferred the source is also available [here](https://github.com/datastax/cpp-dse-driver) . ###### Updating source tree to build submodule[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#updating-source-tree-to-build-submodule) git update --init lib\cpp-dse-driver ##### Building and installing the C/C++ DSE driver[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#building-and-installing-the-c-c-dse-driver) mkdir build pushd build cmake .. make make install popd [Refer to the official build documentation](http://docs.datastax.com/en/developer/cpp-driver-dse/latest/building) for more detailed instructions. ### Building and Installing the PHP DSE extension[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#building-and-installing-the-php-dse-extension) pushd ext phpize popd mkdir build pushd build ../ext/configure make make install popd ### Enabling the PHP DSE extension[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#enabling-the-php-dse-extension) To determine where the `php.ini` file is located on your system run the following command: php -r "echo php_ini_loaded_file();" Edit the `php.ini` file and add the following line to enable the extension: ; DataStax PHP DSE Driver for DataStax Enterprise extension=dse.so To verify the extension is being loaded the following command can be executed: php -i | grep -A 11 "^dse$" ### Enabling testing framework[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#enabling-testing-framework) In order to execute the [Behat](http://behat.org/) test suite and [PHPUnit](https://phpunit.de/) unit and integration tests [Composer](https://getcomposer.org/) must downloaded and installed: curl -sS https://getcomposer.org/installer | php php composer.phar install Windows[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#windows) ------------------------------------------------------------------------------------------------- We provide a self-contained [batch script](https://github.com/datastax/php-dse-driver/blob/master/ext/vc_build.bat) for building the PHP DSE driver and all of its dependencies. In order to run it, you have to install the build dependencies and clone the repository with the DataStax PHP DSE driver for DataStax Enterprise. ### Obtaining build dependencies[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#obtaining-build-dependencies) * Download and install [Bison](http://gnuwin32.sourceforge.net/downlinks/bison.php) * Make sure Bison is in your system PATH and not installed in a directory with spaces (e.g. `%SYSTEMDRIVE%\GnuWin32`) * Download and install [CMake](http://www.cmake.org/download) * Make sure to select the option “Add CMake to the system PATH for all users” or “Add CMake to the system PATH for current user” * Download and install [Git](http://git-scm.com/download/win) * Make sure to select the option “Use Git from Windows Command Prompt” or manually add the git executable to the system PATH. * Download and install [ActiveState Perl](https://www.perl.org/get.html#win32) * Make sure to select the option “Add Perl to PATH environment variable” * Download and install [Python v2.7.x](https://www.python.org/downloads) * Make sure to select/install the feature “Add python.exe to Path” * Download and install Kerberos for Windows v4.0.1 * [32-bit](http://web.mit.edu/kerberos/dist/kfw/4.0/kfw-4.0.1-i386.msi) * [64-bit](http://web.mit.edu/kerberos/dist/kfw/4.0/kfw-4.0.1-amd64.msi) ### Building the driver[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#building-the-driver) The [batch script](https://github.com/datastax/php-dse-driver/blob/master/ext/vc_build.bat) detects installed versions of Visual Studio to simplify the build process on Windows and select the correct version of Visual Studio for the PHP version the driver is being built for. First you will need to open a “Command Prompt” to execute the batch script. Running the batch script without any arguments will build the driver for PHP v7.1 and for the current system architecture (e.g. x64). To perform advanced build configuration, execute the batch script with the `--HELP` argument to display the options available. Usage: VC_BUILD.BAT [OPTION...] --DEBUG Enable debug build --RELEASE Enable release build (default) --DISABLE-CLEAN Disable clean build --ENABLE-THREAD-SAFETY Enable thread safety --ENABLE-PACKAGES [version] Enable package generation (5.6, 7.0, 7.1) (*) --ENABLE-TEST-CONFIGURATION Enable test configuration build --PHP-VERSION [version] PHP version 5.6, 7.0, and 7.1 (**) --X86 Target 32-bit build (***) --X64 Target 64-bit build (***) C/C++ Driver Options --USE-BOOST-ATOMIC Use Boost atomic --HELP Display this message * Minimum supported officially released PHP binary installations ** Defaults to PHP v7.1 if --PHP-VERSION is not used *** Default target architecture is determined based on system architecture #### Enable testing[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#enable-testing) Ensure the driver is built with –ENABLE-TEST-CONFIGURATION in order to execute the [Behat](http://behat.org/) test suite and [PHPUnit](https://phpunit.de/) unit and integration tests. #### Manual/PHP step-by-step windows build[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#manual-php-step-by-step-windows-build) The PHP DSE driver extension can also be built using the [Build your own PHP on Windows](https://wiki.php.net/internals/windows/stepbystepbuild) instructions followed by the [Building PECL extensions](https://wiki.php.net/internals/windows/stepbystepbuild#building_pecl_extensions) instruction where the driver can be statically linked into the PHP executable or as an import (DLL) library. This process requires that the binary dependencies of the PHP DSE driver extension be included in the`phpdev\vc##\x##\deps` directory along with the standard PHP library dependencies. Use `--enable-dse` to build library into the PHP executable and `--enable-dse=shared` for import (DLL) library. The PHP DSE driver extension dependencies not included with the standard PHP library can be download [here](http://downloads.datastax.com/cpp-driver/windows/dse) . **Note**: The binary libraries downloaded/used must be compatible with the MSVC compiler and the PHP DSE driver extension. Testing PHP Extension[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#testing-php-extension) ============================================================================================================================= Features[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#features) --------------------------------------------------------------------------------------------------- ### Linux/Mac OS[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#linux-mac-os) bin/behat ### Windows[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#windows) bin\behat.bat Unit and integration tests[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#unit-and-integration-tests) --------------------------------------------------------------------------------------------------------------------------------------- ### Linux/Mac OS[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#linux-mac-os) bin/phpunit ### Windows[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/index.html#windows) bin\phpunit.bat --- # DataStax Enterprise PHP Driver - Authentication [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/authentication/) * Authentication[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/index.html#authentication) ============================================================================================================================== Clients that require authentication when connecting to a secured DSE cluster (using `com.datastax.bdp.cassandra.auth.DseAuthenticator`) should use the following examples as reference: * [Plaintext/DSE](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/dse) * [LDAP](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/ldap) * [GSSAPI (Kerberos)](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/kerberos) --- # DataStax Enterprise PHP Driver - Home [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/) * DataStax Enterprise PHP Driver[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#data-stax-enterprise-php-driver) ======================================================================================================================================= A driver built specifically for the [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) (DSE). It builds on the [DataStax PHP driver for Apache Cassandra](https://github.com/datastax/php-driver) and includes specific features for DSE. This software can be used solely with [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) . See the [License section](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#licence) below. **Note**: DataStax products do not support big-endian systems. Getting the Driver[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#getting-the-driver) -------------------------------------------------------------------------------------------------------------- Binary versions of the driver, available for multiple operating systems and multiple versions of PHP, can be obtained from our [download server](http://downloads.datastax.com/php-driver) . The source code is made available via [GitHub](https://github.com/datastax/php-dse-driver) . Features[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#features) ------------------------------------------------------------------------------------------ ### DSE v5.0+[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#dse-v5-0) * [DSE authentication](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/) * [Plaintext/DSE](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/dse) * [LDAP](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/ldap) * [GSSAPI (Kerberos)](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/kerberos/) * [DSE geospatial types](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/geotypes/) * [DSE graph integration](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/) ### DSE v5.1+[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#dse-v5-1) * [DSE proxy authentication and execution](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/proxy) * [DSE DateRange](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/date_range) Compatibility[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#compatibility) ---------------------------------------------------------------------------------------------------- This driver works exclusively with [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) . The current version works with: * [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) 4.7, 4.8, 5.0 and 5.1+ * PHP 5.6, PHP 7.0, and PHP 7.1 * 32-bit (x86) and 64-bit (x64) * Thread safe (TS) and non-thread safe (NTS) * Compilers: GCC 4.1.2+, Clang 3.4+, and MSVC 2010/2012/2013/2015 Documentation[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#documentation) ---------------------------------------------------------------------------------------------------- * [Home](http://docs.datastax.com/en/developer/php-driver-dse/latest) * [API](http://docs.datastax.com/en/developer/php-driver-dse/latest/api) * [Features](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/) * [Building and Testing](http://docs.datastax.com/en/developer/php-driver-dse/latest/building_testing) * [Migration](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/migration/) Getting Help[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#getting-help) -------------------------------------------------------------------------------------------------- * JIRA: [https://datastax-oss.atlassian.net/browse/PHP](https://datastax-oss.atlassian.net/browse/PHP) (Assign “Component/s” field set to “DSE”) * Mailing List: [https://groups.google.com/a/lists.datastax.com/forum/#!forum/php-driver-user](https://groups.google.com/a/lists.datastax.com/forum/#!forum/php-driver-user) * DataStax Academy via Slack: [https://academy.datastax.com/slack](https://academy.datastax.com/slack) Feedback Requested[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#feedback-requested) -------------------------------------------------------------------------------------------------------------- **Help us focus our efforts!** [Provide your input](http://goo.gl/forms/HbSiIJ2tLP) on the DSE PHP Driver Platform and Runtime Survey (we kept it short). Examples[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#examples) ------------------------------------------------------------------------------------------ The driver includes several examples in the [features](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/) directory. License[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/index.html#license) ---------------------------------------------------------------------------------------- Copyright © 2017 DataStax, Inc. [http://www.datastax.com/terms/datastax-dse-driver-license-terms](http://www.datastax.com/terms/datastax-dse-driver-license-terms) --- # DataStax Enterprise PHP Driver - Features [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/) * Features[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/index.html#features) =================================================================================================== The PHP DataStax Enterprise Driver builds on the [core](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/) features need to fully leverage Apache Cassandra in addition to features specifically designed for DataStax Enterprise: * [DSE plaintext and GSSAPI authentication](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/) * [DSE geospatial types](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/geotypes/) * [DSE graph integration](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/) --- # DataStax Enterprise PHP Driver - Geospatial types [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/geotypes/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/geotypes/) * Geospatial types[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/geotypes/index.html#geospatial-types) ============================================================================================================================ DataStax Enterprise 5.0+ adds types for representing geospatial data. The three new geospatial types are point, line string and polygon. These types can be specified directly in a query string using [well-known text (WKT)](https://en.wikipedia.org/wiki/Well-known_text) or can be bound to a query using the following objects: [`Dse\Point`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Point/) , [`Dse\LineString`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.LineString/) and [`Dse\Polygon`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Point/) . Point[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/geotypes/index.html#point) ------------------------------------------------------------------------------------------------------ A point is a 2-dimensional location in space represented by two, double precision floating numbers. Tables with columns of this type are created using the type `org.apache.cassandra.db.marshal.PointType` or the shorter `PointType`. $session = Dse::cluster()->build()->connect("examples"); # Create table and add a coordinate for the point of interest using the `Point` # type $session->execute( "CREATE TABLE IF NOT EXISTS points_of_interest " . "(name varchar PRIMARY KEY, coords 'PointType')" ); $session->execute( "INSERT INTO points_of_interest (name, coords) VALUES (?, ?)", array("arguments" => array("Eiffel Tower", new Dse\Point(48.8582, 2.2945))) ); # Get the coordinates for the inserted location $row = $session->execute("SELECT * FROM points_of_interest")->first(); echo "Name: '{$row['name']}' Coords: ({$row['coords']})" . PHP_EOL; Line String[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/geotypes/index.html#line-string) ------------------------------------------------------------------------------------------------------------------ A line string is a 2-dimensional set of lines represented by a string of points. Tables with columns of this type are created using the type `org.apache.cassandra.db.marshal.LineStringType` or the shorter `LineStringType`. # Create table for trail paths $session->execute( "CREATE TABLE IF NOT EXISTS trails " . "(name varchar PRIMARY KEY, path 'LineStringType')" ); # Add a new trail path using the `LineString` type $path = new Dse\LineString(new Dse\Point(38, 78), new Dse\Point(39, 78), new Dse\Point(39.5, 79)); # ... $session->execute( "INSERT INTO trails (name, path) VALUES (?, ?)", array("arguments" => array("Appalachian National Scenic Trail", $path)) ); # Get the trail's path coordinates $row = $session->execute("SELECT * FROM trails")->first(); echo "Name: '{$row['name']}'" . PHP_EOL; echo "Path: " . implode(" --> ", $row['path']->points()) . PHP_EOL; Polygon[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/geotypes/index.html#polygon) ---------------------------------------------------------------------------------------------------------- A polygon is a bound set of line segments that form a closed loop. It is characterized by a set of rings formed by line strings. The first ring represents the external bounds of the polygon and all follow up rings represent holes. The rings must be closed loops so they must be at least four points with the first and last points being the same location. Tables with columns of this type are created using the type `org.apache.cassandra.db.marshal.PolygonType` or the shorter `PolygonType`. # Create a table to represent boundaries of places in the world (in this case a state) $session->execute( "CREATE TABLE IF NOT EXISTS boundaries " . "(name varchar PRIMARY KEY, boundary 'PolygonType')" ); # Use a `LineString` to represent the exterior boundary of the state $stateBoundary = new Dse\LineString(new Dse\Point(35, 10), new Dse\Point(45, 45), new Dse\Point(15, 40), new Dse\Point(10, 20), new Dse\Point(35, 10)); # Use a `LineString` to represent the boundary of a county inside the state's # exteriro boundary $countyBoundary = new Dse\LineString(new Dse\Point(20, 30), new Dse\Point(35, 35), new Dse\Point(30, 20), new Dse\Point(20, 30)); # Add the state's boundary using the `Polygon` type $boundary = new Dse\Polygon($stateBoundary, $countyBoundary); $session->execute( "INSERT INTO boundaries (name, boundary) VALUES (?, ?)", array("arguments" => array("California", $boundary)) ); $ Get the state's boundary $row = $session->execute("SELECT * FROM boundaries")->first(); echo "Name: '{$row['name']}'" . PHP_EOL; echo "State Boundary: " . implode("; ", $row['boundary']->exteriorRing()->points()) . PHP_EOL; foreach ($row['boundary']->interiorRings() as $countyBoundary) { echo "County Boundary: " . implode("; ", $countyBoundary->points()) . PHP_EOLo } --- # DataStax Enterprise PHP Driver - Graph [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/) * Graph[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/index.html#graph) =================================================================================================== DataStax Enterprise 5.0+ now includes a graph-orient database. The DSE driver can execute graph queries written in the Gremlin language. Graph queries are executed using either the `Session::executeGraph()` and `Session::executeGraphAsync()` methods and return `Graph\ResultSet` objects which can represent Cassandra types or graph specific types (e.g. vertices and edges). Graph Options[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/index.html#graph-options) ------------------------------------------------------------------------------------------------------------------- Graph options control how graph queries are run and can be specified when constructing a `Dse\Cluster` object or they can be specified per query. At a minimum, a graph name must be provide when running regular graph queries. Running system commands do not require specifying a graph name. # Construct graph options with a graph name "users" $graphOptions = Dse::graphOptions() ->withGraphName("users") ->build(); # Construct a new cluster object with specific graph options $cluster = Dse::cluster() ->withGraphOptions($graphOptions) ->build(); $session = $cluster->connect(); # Execute a graph query using the cluster-level graph options $resultset = $session->executeGraph("g.V().count()"); Graph options can also be specified (or overridden) when executing a query. $cluster = Dse::cluster()->build(); $session = $cluster->connect(); $resultset = $session->executeGraph("g.V().count()", array("graph_name" => "users")); Graph Results[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/index.html#graph-results) ------------------------------------------------------------------------------------------------------------------- A `Dse\Graph\ResultSet` object is returned from the graph execution methods. Resultsets are iterable and indexable list of `Dse\Graph\Result` objects. `Dse\Graph\Result` is an arbitrary data result and it can be various types from simple data types such as numbers and strings, composite data types such as arrays and dictionaries, as well as graph elements such as vertices and edges. # A `Dse\Graph\Result can hold arbitrary data, in this case the number of # vertices held by the graph. $result = $session->execute("g.V().count()")->first(); echo "Vertex count: {$result->value()}" . PHP_EOL; Vertices[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/index.html#vertices) --------------------------------------------------------------------------------------------------------- Vertices are graph elements connected by edges. They contain properties and unlike other graph elements (e.g. edges) vertex properties can contain multiple values and can have properties of their own. $resultset = $session->executeGraph("g.V()"); foreach ($resultset as $result) { $vertex = $result->asVertex(); # Convert to vertex echo "Vertex label: {$vertex->id()['~label']}" . PHP_EOL; foreach($vertex->properties() as $property) { echo "Vertex property name: {$property->name()}" . PHP_EOL; # Each vertex property can contain multiple values foreach ($property->value() as $value) { echo "Vertex property value: {$value['value']}" . PHP_EOL; } } } Edges[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/index.html#edges) --------------------------------------------------------------------------------------------------- Edges connected pairs of vertices. Like vertices they have properties, but they are simple key/value pairs. $resultset = $session->executeGraph("g.E()"); foreach ($resultset as $result) { $edge = $result->asEdge(); echo "Edge type: {$edge->id()['~type']}" . PHP_EOL; # Each edge has an input and output vertex echo "Edge incoming vertex label: {$edge->inVLabel()}" . PHP_EOL; echo "Edge outgoing vertex label: {$edge->outVLabel()}" . PHP_EOL; # Edge properties are simple key/value pairs foreach($edge->properties() as $property) { echo "Edge property name: {$property->name()}" . PHP_EOL; echo "Edge property value: {$property->value()}" . PHP_EOL; } } Paths[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/index.html#paths) --------------------------------------------------------------------------------------------------- Paths describe a list of graph elements that connect two vertices. $resultset = $session->executeGraph("g.V().in().path()"); $path = $resultset->first()->asPath(); echo "Path labels: " . json_encode($path->labels()) . PHP_EOL; echo "Length of path: " . count($path->labels()) . PHP_EOL; $objects = $path->objects(); for ($i = 0; $i < count($objects); $i++) { try { $vertex = $objects[$i]->asVertex(); echo "Object $i is a(n) " . get_class($vertex) . " with the value: " . $vertex->property('name')->value()[0]['value'] . PHP_EOL; } catch(Dse\Exception\DomainException $e) { $edge = $objects[$i]->asEdge(); echo "Object $i is a(n) " . get_class($edge) . " with the value: " . $edge->label(). PHP_EOL; } } --- # DataStax Enterprise PHP Driver - Core [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/) * Core[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#core) ================================================================================================ Usage[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#usage) -------------------------------------------------------------------------------------------------- ### Specifying addresses of DSE nodes[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#specifying-addresses-of-dse-nodes) [`withContactPoints()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withContactPoints) and [`withPort()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withPort) methods of the [`Dse\Cluster\Builder`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/) are used to specify IP addresses or hostnames and port number of the nodes in a given DSE cluster. Note that you don’t have to specify the addresses of all hosts in your cluster. Once the driver has established a connection to any host, it will perform auto-discovery and connect to all hosts in the cluster. withContactPoints('10.0.1.24', 'example.com', 'localhost') ->withPort(9042) ->build(); $session = $cluster->connect(); ### Discovering nodes in the cluster[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#discovering-nodes-in-the-cluster) After the initial connection to one of the hosts specified via `withContactPoints()` succeeds, the driver discovers the addresses and connects to all members of the cluster automatically. You can also see the nodes that the driver discovered by running `SELECT * FROM system.peers`. ### Persistent sessions[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#persistent-sessions) In order to limit the startup time and total number of connections to a DSE cluster, the PHP Driver enables persistent sessions by default. All cluster and sessions using the same initial configuration will be shared across requests when persistent sessions are enabled. You can toggle this setting using [`Dse\Cluster\Builder::withPersistentSessions()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withPersistentSessions) . withPersistentSessions(false) ->build(); $session = $cluster->connect(); Note that disabling persistent sessions will cause a significant slow down of cluster initialization as the connections will be forced to get re-established for every request. Once persistent sessions are enabled, you can view how many of them are currently active. They will be exposed in the Dse extension section of `phpinfo()`. Persistent sessions stay alive for the duration of the parent process, typically a php-fpm worker or apache worker. These sessions will be reused for all requests served by that worker process. Once a worker process has reached its end of life, sessions will get cleaned up automatically and will be re-create in the new process. ### Configuring load balancing policy[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#configuring-load-balancing-policy) The PHP Driver comes with a variety of load balancing policies. By default it uses a combination of latency aware, token aware and data center aware round robin load balancing. The token aware load balancing policy uses the same hashing algorithms as the Apache Cassandra to directly route the execution of prepared statements to the replica node, avoiding an additional network hop to/from the coordinator. You can toggle its usage with [`Dse\Cluster\Builder::withTokenAwareRouting()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withTokenAwareRouting) . withTokenAwareRouting(false) ->build(); $session = $cluster->connect(); The default datacenter aware round robin load balancing policy is configured to keep all traffic in the same datacenter. Upon connecting to a host from the initial list of contact points, the driver will consider that host’s datacenter to be local. Only hosts from the same datacenter will be connected to and used for executing statements. You can override the name of the local datacenter. The number of hosts from remote datacenters that the driver may use and whether it should execute statements with local consistencies on those hosts in case none of the local hosts are available. All of that is configurable via [`Dse\Cluster\Builder::withDatacenterAwareRoundRobinLoadBalancingPolicy()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withDatacenterAwareRoundRobinLoadBalancingPolicy) . withDatacenterAwareRoundRobinLoadBalancingPolicy("us-west", 2, true) ->build(); $session = $cluster->connect(); You may disable datacenter awareness by calling [`Dse\Cluster\Builder::withRoundRobinLoadBalancingPolicy()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withRoundRobinLoadBalancingPolicy) . withRoundRobinLoadBalancingPolicy() ->build(); $session = $cluster->connect(); Finally, latency-aware routing ensures that requests are routed to the hosts that respond the fastest. You can switch it off via [`Dse\Cluster\Builder::withLatencyAwareRouting()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withLatencyAwareRouting) . withLatencyAwareRouting(false) ->build(); $session = $cluster->connect(); ### Setting protocol version[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#setting-protocol-version) The PHP driver will automatically negotiate native protocol version of TCP connections to the latest supported by both the driver and Apache Cassandra servers. It does this by attempting connection at the highest supported protocol version (currently 2) and negotiating it down upon unsupported version responses from the server. In a scenario with an Apache Cassandra cluster consisting of nodes of mixed versions (e.g. 1.2.x and 2.0.x), this might pose problems as the driver could establish native protocol version to be 2, while some of the nodes don’t support it, causing connections to the rest of the cluster to fail. You can force the driver to start negotiation at a lower protocol version by using [`Dse\Cluster\Builder::withProtocolVersion()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withProtocolVersion) . withProtocolVersion(1) ->build(); $session = $cluster->connect(); ### Tweaking driver’s throughput[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#tweaking-driver-s-throughput) There are a few variables affecting the total throughput of the driver that can be tweaked client-side. The maximum number of requests that can be executed at the same time is calculated with the following formula: inflight_requests = io_threads * requests_per_connection * maximum_number_of_connections_per_host * connected_hosts Where `io_threads` by default is `1`, `requests_per_connection` for the currently supported protocol versions is `128`, `maximum_number_of_connections_per_host` by default is `2` and `connected_hosts` is the total number of hosts that can be connected to. This last variable depends on the load balancing policy used, data center aware policy only connects to the hosts in the same data center by default. You can change the value of `io_threads` from the formula above by using [`Dse\Cluster\Builder::withIOThreads()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withIOThreads) . withIOThreads(4) ->build(); $session = $cluster->connect(); You can change the value of `maximum_number_of_connections_per_host` from the formula above by using [`Dse\Cluster\Builder::withConnectionsPerHost()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withConnectionsPerHost) . withConnectionsPerHost(4, 8) ->build(); $session = $cluster->connect(); ### Disabling TCP nodelay[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#disabling-tcp-nodelay) By default, the driver enables TCP nodelay (Nagle’s algorithm) on all connections it uses. Disabling it is not recommended but possible via [`Dse\Cluster\Builder::withTCPNodelay()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withTCPNodelay) . withTCPNodelay(false) ->build(); $session = $cluster->connect(); ### Enabling TCP keepalive[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#enabling-tcp-keepalive) By default, TCP keepalive is disabled. It can be useful to make sure TCP connections are not silently dropped by a firewall or some other intermediary network device. You can enable it using [`Dse\Cluster\Builder::withTCPKeepalive()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withTCPKeepalive) . withTCPKeepalive(10) ->build(); $session = $cluster->connect(); ### Authenticating via `PasswordAuthenticator`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#authenticating-via-password-authenticator) The PHP Driver supports Apache Cassandra’s built-in password authentication mechanism. To enable it, use [`Dse\Cluster\Builder::withCredentials()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withCredentials) . withCredentials("username", "password") ->build(); $session = $cluster->connect(); ### Enabling SSL encryption[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#enabling-ssl-encryption) The PHP Driver supports SSL encryption of network connections. You must configure [`Dse\SSLOptions`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.SSLOptions/) using the [`Dse\SSLOptions\Builder`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/SSLOptions/class.Builder/) . withTrustedCerts('node1.pem', 'node2.pem') ->withVerifyFlags(Dse::VERIFY_PEER_CERT | Dse::VERIFY_PEER_IDENTITY) ->withClientCert('client.pem') ->withPrivateKey('id_rsa', 'passphrase') ->build() $cluster = Dse::cluster() ->withSSL($ssl) ->build(); $session = $cluster->connect(); ### Executing queries[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#executing-queries) You run CQL statements by passing them to [`Dse\Session::execute()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/) . execute('SELECT keyspace_name, columnfamily_name FROM system.schema_columnfamilies'); foreach ($result as $row) { printf("The keyspace \"%s\" has a table \"%s\".\n", $row['keyspace_name'], $row['columnfamily_name']); } ### Parameterized queries[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#parameterized-queries) **If you’re using Cassandra 2.0 or later** you no longer have to build CQL strings when you want to insert a value in a query, there’s a new feature that lets you bind values with regular statements: execute( "UPDATE users SET age = ? WHERE user_name = ?", array('arguments' => array(41, 'Sam')) ); For frequently executed queries, it’s strongly recommended to use prepared statements. As a rule of thumb, if your application is sending a request more than once, a prepared statement is almost always the right choice. ### Prepared statements[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#prepared-statements) The driver supports prepared statements. Use [`Dse\Session::prepare()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method.prepare) to create a [`Dse\PreparedStatement`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.PreparedStatement/) object, and then call [`Dse\Session::execute()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method.execute) . prepare('INSERT INTO users (username, email) VALUES (?, ?)'); $session->execute($statement, array( 'arguments' => array('avalanche123', 'bulat.shakirzyanov@datastax.com') )); A prepared statement can be run many times, but the CQL parsing will only be done once on each node. Use prepared statements for queries you run over and over again. ### Executing statements in parallel[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#executing-statements-in-parallel) With fully asynchronous API, it is very easy to run queries in parallel: prepare("UPDATE users SET age = ? WHERE user_name = ?"); $futures = array(); // execute all statements in background foreach ($data as $arguments) { $futures[] = $session->executeAsync($statement, array( 'arguments' => $arguments )); } // wait for all statements to complete foreach ($futures as $future) { // we will not wait for each result for more than 5 seconds $future->get(5); } Note that it is not enough to simply create a [`Dse\Future`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Future/) by calling one of the `*Async()` methods, you must ensure that this future has enough time to be executed by calling [`Dse\Future::get()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Future/#method.get) . ### Creating keyspaces and tables[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#creating-keyspaces-and-tables) There is no special facility for creating keyspaces and tables, they are created by executing CQL: execute($createKeyspace); $session->execute('USE measurements'); $session->execute($createTable); You can also `ALTER` keyspaces and tables, and you can read more about that in the [CQL3 syntax documentation](https://github.com/apache/cassandra/blob/cassandra-2.0/doc/cql3/CQL.textile) . ### Batch statements[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#batch-statements) **If you’re using Cassandra 2.0 or later** you can build batch requests, either from simple or prepared statements. Batches must not contain any select statements, only `INSERT`, `UPDATE` and `DELETE` statements are allowed. You can mix any combination of statements in a batch: prepare("UPDATE users SET name = ? WHERE user_id = ?"); $batch->add($statement, array('Sue', 'unicorn31')); $batch->add("UPDATE users SET age = 19 WHERE user_id = 'unicorn31'"); $batch->add( "INSERT INTO activity (user_id, what, when) VALUES (?, 'login', NOW())", array('unicorn31') ); $session->execute($batch); Batches can have one of three different types: `logged`, `unlogged` or `counter`, where `logged` is the default. Their exact semantics are defined in the [Cassandra documentation](http://docs.datastax.com/en/cql/3.1/cql/cql_reference/batch_r.html) , but this is how you specify which one you want: withDefaultPageSize(200) ->build(); $session = $cluster->connect(); You can also override the page size on a per-execute basis by adding the `page_size` execution option to a call to [`Dse\Session.executeAsync`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-executeAsync) or [`Dse\Session.execute`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) : execute($statement, array('page_size' => 100)); while ($result) { foreach ($result as $row) { var_dump($row); } $result = $result->nextPage(); } [Read more about `Dse\Rows::nextPage()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Rows/#method.nextPage) ### Consistency[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#consistency) You can specify the default consistency to use for statements execution when you create a new `Dse\Cluster`: withDefaultConsistency(Dse::CONSISTENCY_LOCAL_QUORUM) ->build(); $session = $cluster->connect(); [Read more `Dse\Cluster\Builder::withDefaultConsistency()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withDefaultConsistency) Consistency can also be passed via execution options. execute( 'SELECT * FROM users', array('consistency' => Dse::CONSISTENCY_LOCAL_QUORUM) ); $statement = $session->prepare('SELECT * FROM users'); $session->execute($statement, array( 'consistency' => Dse::CONSISTENCY_LOCAL_QUORUM )); $batch = new Dse\BatchStatement(); $batch->add("UPDATE users SET email = 'sue@foobar.com' WHERE id = 'sue'"); $batch->add("UPDATE users SET email = 'tom@foobar.com' WHERE id = 'tom'"); $session->execute($batch, array( 'consistency' => Dse::CONSISTENCY_LOCAL_QUORUM )); [Read more about `Dse\ExecutionOptions`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.ExecutionOptions/) [Read more about `Dse\Session::execute()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method.execute) The default consistency level unless you’ve set it yourself is `Dse::CONSISTENCY_LOCAL_ONE`. Consistency is ignored for `USE`, `TRUNCATE`, `CREATE` and `ALTER` statements, and some (like `Dse::CONSISTENCY_ANY`) aren’t allowed in all situations. ### Schema Metadata[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#schema-metadata) The DataStax PHP driver exposes schema metadata via [`Dse\Schema`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Schema/) object, available using [`Dse\Session::schema()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method.schema) . Schema metadata includes information about keyspace, tables and columns and it automatically kept up-to-date with the Cassandra cluster. schema(); foreach ($schema->keyspaces() as $keyspace) { printf("Keyspace: %s\n", $keyspace->name()); printf(" Replication Strategy: %s\n", $keyspace->replicationClassName()); printf(" Replication Options:\n"); $options = $keyspace->replicationOptions(); $keys = $options->keys(); $values = $options->values(); foreach (array_combine($keys, $values) as $key => $value) { printf(" %s: %s\n", $key, $value); } printf(" Durable Writes: %s\n", $keyspace->hasDurableWrites() ? 'true' : 'false'); foreach ($keyspace->tables() as $table) { printf(" Table: %s\n", $table->name()); printf(" Comment: %s\n", $table->comment()); printf(" Read Repair Chance: %f\n", $table->readRepairChance()); printf(" Local Read Repair Chance: %f\n", $table->localReadRepairChance()); printf(" GC Grace Seconds: %d\n", $table->gcGraceSeconds()); printf(" Caching: %s\n", $table->caching()); printf(" Bloom Filter FP Chance: %f\n", $table->bloomFilterFPChance()); printf(" Memtable Flush Period Ms: %d\n", $table->memtableFlushPeriodMs()); printf(" Default Time To Live: %d\n", $table->defaultTTL()); printf(" Speculative Retry: %s\n", $table->speculativeRetry()); printf(" Index Interval: %d\n", $table->indexInterval()); printf(" Compaction Strategy: %s\n", $table->compactionStrategyClassName()); printf(" Populate IO Cache On Flush: %s\n", $table->populateIOCacheOnFlush() ? 'yes' : 'no'); printf(" Replicate On Write: %s\n", $table->replicateOnWrite() ? 'yes' : 'no'); printf(" Max Index Interval: %d\n", $table->maxIndexInterval()); printf(" Min Index Interval: %d\n", $table->minIndexInterval()); foreach ($table->columns() as $column) { printf(" Column: %s\n", $column->name()); printf(" Type: %s\n", $column->type()); printf(" Order: %s\n", $column->isReversed() ? 'desc' : 'asc'); printf(" Frozen: %s\n", $column->isFrozen() ? 'yes' : 'no'); printf(" Static: %s\n", $column->isStatic() ? 'yes' : 'no'); if ($column->indexName()) { printf(" Index: %s\n", $column->indexName()); printf(" Index Options: %s\n", $column->indexOptions()); } } } } **NOTE** A new instance of [`Dse\Schema`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Schema/) is returned each time [`Dse\Session::schema()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method.schema) is called. This instance is a simple value object and its information, such as keyspaces, tables and columns will not be kept up-to-date with the state of the cluster. In order to obtain the latest schema metadata, you have to call [`Dse\Session::schema()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method.schema) again. ### Data Types[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#data-types) The PHP driver for Apache Cassandra supports [a variety of datatypes](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/datatypes/) . You can also use the rich type metadata API to define and inspect types, as well as validate data objects. The example below defines and creates a [`Dse\Map`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/) using [`Dse\Type`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Type/) interface. create('a', 1, 'b', 2, 'c', 3, 'd', 4); var_dump(array_combine($map->keys(), $map->values())); **NOTE** The `create()` method or various types validates and coerces provided values into the target type. ### Logging[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#logging) You can configure the location of the log file for the driver as well as the log level using the following `php.ini` settings: [dse] dse.log=syslog dse.log_level=INFO You can specify any file path as `dse.log`. The special value `syslog` can be used to for the driver to use syslog for logging. Syslog is only supported on \*nix systems. The possible log levels are: * CRITICAL * ERROR * WARN * INFO * DEBUG * TRACE Most of the logging will be when the driver connects and discovers new nodes, when connections fail and so on. The logging is designed to not cause much overhead and only relatively rare events are logged (e.g. normal requests are not logged). Architecture[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#architecture) ---------------------------------------------------------------------------------------------------------------- The PHP Driver follows the architecture of [the C/C++ Driver](http://datastax.github.io/cpp-driver/topics/#architecture) that it wraps. ### Persistent sessions[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/index.html#persistent-sessions) By default, the driver uses persistent sessions to prevent each request from creating completely new TCP connections to a DSE cluster. You can toggle this functionality using [`Dse\Cluster\Builder::withPersistentSessions`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/#method.withPersistentSessions) --- # DataStax Enterprise PHP Driver - DateRange [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/date_range/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/) * DateRange[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/date_range/index.html#date-range) ================================================================================================================= DataStax Enterprise 5.1+ introduces a `DateRange` type to represent ranges of dates and times. For example: * from 1999 to March 2003 * from 4/17/2002 18:36 to 4/19/2002 18:37:30.5 * from 9/25/2013 and never ending * from the beginning of time until 9/25/2013 * on 12/25/2005 One end of a DateRange (called a _bound_) consists of a millisecond-precision timestamp and a desired precision. Thus, a bound of **1999** is represented by a timestamp for any time in the year 1999 and a precision of **year**. Three classes in the driver model this structure: * [`Dse\DateRange\Precision`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/DateRange/class.Precision/) * [`Dse\DateRange\Bound`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/DateRange/class.Bound/) , * [`Dse\DateRange`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DateRange/) , Precision[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/date_range/index.html#precision) ---------------------------------------------------------------------------------------------------------------- The [`Precision`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/DateRange/class.Precision/) class contains constants for the valid precisions: * YEAR * MONTH * DAY * HOUR * MINUTE * SECOND * MILLISECOND This class cannot be instantiated. Bound[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/date_range/index.html#bound) -------------------------------------------------------------------------------------------------------- The [`Bound`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/DateRange/class.Bound/) class encapsulates one end of a date-range. It consists of an integer timestamp (obtained via the ([`timeMs()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/DateRange/class.Bound/#method-timeMs) ) accessor) and a [`Precision`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/DateRange/class.Precision/) (obtained via the [`precision()`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/DateRange/class.Bound/#method-precision) accessor). The timestamp is the number of milliseconds since the start of the epoch. This class also has a static method called `unbounded()` which returns a `Bound` that represents “no bound”. It is used as the virtual end-point of an open-ended range. To check if a bound is unbounded, simply compare to `Bound::unbounded()`: if ($b == Dse\DateRange\Bound::unbounded()) { ... } The constructor for `Bound` accepts `long`, `double`, [`Dse\Bigint`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Bigint/) , numeric string, and `DateTime` values for the timestamp attribute: use Dse\DateRange\Precision; use Dse\DateRange\Bound; $b = new Bound(Precision::YEAR, 12345); $b = new Bound(Precision::YEAR, "12345"); $b = new Bound(Precision::YEAR, new DateTime("2016-12-17")); This is particularly useful on 32-bit platforms where PHP does not inherently support 64-bit integers. DateRange[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/date_range/index.html#date-range) ----------------------------------------------------------------------------------------------------------------- A DateRange typically has a lower-bound (`lowerBound()`) and an upper-bound (`upperBound()`) such as “from 4/17/2002 18:36 to 4/19/2002 18:37:30.5”. Open-ended ranges have a `Bound::unbounded()` on the open-side. However, date ranges can also consist of a single value, as in “on 12/25/2005”. Such DateRange objects store the single bound in `lowerBound()`. `upperBound()` returns `NULL`. In addition, an `isSingleDate()` function returns whether or not this DateRange has a single date value. The constructor for `DateRange` accepts both `Bound` and `` pairs, where `timestamp` may be a `long`, `double`, [`Dse\Bigint`](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Bigint/) , numeric string, or `DateTime`. Putting all of this together, one can manipulate DateRange objects as follows: use Dse\DateRange; use Dse\DateRange\Precision; use Dse\DateRange\Bound; // long timestamp (seconds precision) representing 2 days after the beginning of the epoch $t = 86400 * 2; // Single date $d = new DateRange(Precision::YEAR, $time * 1000); $d = new DateRange(Precision::YEAR, new DateTime("2005-04-03")); // Single date, using a DateRange\Bound object. $bound = new Bound(Precision::YEAR, new DateTime("2005-04-03")); $d = new DateRange($bound); // Closed range $d = new DateRange(Precision::YEAR, ($t - 3600) * 1000, Precision::DAY, $t * 1000); // Open value $d = new DateRange(Bound::unbounded()); // Open range on one side. $d = new DateRange(Precision::MILLISECOND, $t, Bound::unbounded()); // Pull out attributes print $d->lowerBound()->precision(); print $d->upperBound()->timeMs(); // Check if unbounded on one side if ($d->lowerBound() == Bound::unbounded()) { … } --- # DataStax Enterprise PHP Driver - Sessions [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/sessions/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/sessions/) * Sessions[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/sessions/index.html#sessions) ============================================================================================================ Session[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/sessions/index.html#session) ---------------------------------------------------------------------------------------------------------- DataStax PHP Driver uses a Session object to execute and prepare statements. --- # DataStax Enterprise PHP Driver - Migration [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/migration/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/migration/) * Migration[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/migration/index.html#migration) =============================================================================================================== When using DataStax Enterprise (DSE) it is highly recommend that your application use the DataStax Enterprise Driver instead of using the DataStax Driver for Apache Cassandra. This will allow your application to take full advantage of DSE. Migrating your application is easy and namespace aliasing can allow your existing code to remain mostly unchanged. use Dse as Cassandra; # Existing code This should work for most code bases, but this has a couple limitations: * Code cannot use fully qualified names when using aliasing (e.g. `\Cassandra\SimpleStatement`) * Code that uses `is_a()` for objects in the `Cassandra` namespace will need to use `instanceof` instead. use Dse as Cassandra; $value = new Cassandra\Float(1); echo "is_a(\$value, 'Cassandra\Float')? " . (is_a($value, "Cassandra\Float") ? "true" : "false") . PHP_EOL; echo "is_a(\$value, Dse\Float)'? " . (is_a($value, "Dse\Float") ? "true" : "false") . PHP_EOL; echo "\$value instaneof 'Cassandra\Float'? " . ($value instanceof Cassandra\Float ? "true" : "false") . PHP_EOL; echo "\$value instaneof 'Dse\Float'? " . ($value instanceof Dse\Float ? "true" : "false") . PHP_EOL; --- # DataStax Enterprise PHP Driver - Dse [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/) * namespace Dse[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/index.html#namespace-Dse) ============================================================================================================ Namespaces[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/index.html#namespaces) ------------------------------------------------------------------------------------------------------ * `[Dse\Cluster](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/) ` * `[Dse\DateRange](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/DateRange/) ` * `[Dse\Exception](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Exception/) ` * `[Dse\Graph](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Graph/) ` * `[Dse\RetryPolicy](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/RetryPolicy/) ` * `[Dse\SSLOptions](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/SSLOptions/) ` * `[Dse\TimestampGenerator](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/TimestampGenerator/) ` * `[Dse\Type](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Type/) ` Classes[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/index.html#classes) ------------------------------------------------------------------------------------------------ * `[Dse\BatchStatement](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.BatchStatement/) ` * `[Dse\Bigint](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Bigint/) ` * `[Dse\Blob](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Blob/) ` * `[Dse\Collection](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/) ` * `[Dse\Custom](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Custom/) ` * `[Dse\Date](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Date/) ` * `[Dse\DateRange](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DateRange/) ` * `[Dse\Decimal](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Decimal/) ` * `[Dse\DefaultAggregate](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultAggregate/) ` * `[Dse\DefaultCluster](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultCluster/) ` * `[Dse\DefaultColumn](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultColumn/) ` * `[Dse\DefaultFunction](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultFunction/) ` * `[Dse\DefaultIndex](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultIndex/) ` * `[Dse\DefaultKeyspace](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultKeyspace/) ` * `[Dse\DefaultMaterializedView](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultMaterializedView/) ` * `[Dse\DefaultSchema](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultSchema/) ` * `[Dse\DefaultSession](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultSession/) ` * `[Dse\DefaultTable](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.DefaultTable/) ` * `[Dse\Duration](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Duration/) ` * `[Dse\ExecutionOptions](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.ExecutionOptions/) ` * `[Dse\Float](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Float/) ` * `[Dse\FutureClose](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.FutureClose/) ` * `[Dse\FuturePreparedStatement](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.FuturePreparedStatement/) ` * `[Dse\FutureRows](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.FutureRows/) ` * `[Dse\FutureSession](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.FutureSession/) ` * `[Dse\FutureValue](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.FutureValue/) ` * `[Dse\Inet](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Inet/) ` * `[Dse\LineString](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.LineString/) ` * `[Dse\Map](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/) ` * `[Dse\MaterializedView](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.MaterializedView/) ` * `[Dse\Point](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Point/) ` * `[Dse\Polygon](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Polygon/) ` * `[Dse\PreparedStatement](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.PreparedStatement/) ` * `[Dse\Rows](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Rows/) ` * `[Dse\Set](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/) ` * `[Dse\SimpleStatement](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.SimpleStatement/) ` * `[Dse\Smallint](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Smallint/) ` * `[Dse\SSLOptions](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.SSLOptions/) ` * `[Dse\Time](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Time/) ` * `[Dse\Timestamp](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Timestamp/) ` * `[Dse\Timeuuid](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Timeuuid/) ` * `[Dse\Tinyint](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Tinyint/) ` * `[Dse\Tuple](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Tuple/) ` * `[Dse\Type](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Type/) ` * `[Dse\UserTypeValue](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.UserTypeValue/) ` * `[Dse\Uuid](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Uuid/) ` * `[Dse\Varint](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Varint/) ` Interfaces[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/index.html#interfaces) ------------------------------------------------------------------------------------------------------ * `[Dse\Aggregate](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Aggregate/) ` * `[Dse\Cluster](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Cluster/) ` * `[Dse\Column](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Column/) ` * `[Dse\Exception](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Exception/) ` * `[Dse\Function](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Function/) ` * `[Dse\Future](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Future/) ` * `[Dse\Index](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Index/) ` * `[Dse\Keyspace](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Keyspace/) ` * `[Dse\Numeric](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Numeric/) ` * `[Dse\RetryPolicy](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.RetryPolicy/) ` * `[Dse\Schema](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Schema/) ` * `[Dse\Session](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/) ` * `[Dse\Statement](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Statement/) ` * `[Dse\Table](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Table/) ` * `[Dse\TimestampGenerator](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.TimestampGenerator/) ` * `[Dse\UuidInterface](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.UuidInterface/) ` * `[Dse\Value](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Value/) ` --- # DataStax Enterprise PHP Driver - API docs [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/) * API Documentation Index[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/index.html#api-documentation-index) ============================================================================================================================ Namespaces[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/index.html#namespaces) -------------------------------------------------------------------------------------------------- * `[Dse](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/) ` Classes[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/index.html#classes) -------------------------------------------------------------------------------------------- * `[Dse](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/) ` --- # DataStax Enterprise PHP Driver - Home [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/) * DataStax Enterprise PHP Driver[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/index.html#data-stax-enterprise-php-driver) ======================================================================================================================================= A driver built specifically for the DataStax Enterprise (DSE). It builds on the [DataStax PHP driver for Apache Cassandra](https://github.com/datastax/php-driver) and includes specific features for DSE. This software can be used solely with DataStax Enterprise. See the [License section](https://docs.datastax.com/en/developer/php-driver-dse/1.0/index.html#licence) below. Features[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/index.html#features) ------------------------------------------------------------------------------------------ * [DSE plaintext (LDAP) and GSSAPI (Kerberos) authentication](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/authentication/) * [DSE geospatial types](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/geotypes/) * [DSE graph integration](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/) Documentation[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/index.html#documentation) ---------------------------------------------------------------------------------------------------- Documentation for the DSE driver is available [here](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/) Examples[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/index.html#examples) ------------------------------------------------------------------------------------------ The driver includes several examples in the [features](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/) directory. License[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/index.html#license) ---------------------------------------------------------------------------------------- Copyright © 2016 DataStax, Inc. [http://www.datastax.com/terms/datastax-dse-driver-license-terms](http://www.datastax.com/terms/datastax-dse-driver-license-terms) --- # DataStax Enterprise PHP Driver - Dse [DataStax Enterprise PHP Driver 1.1 (Latest version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.1 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/) * class Dse[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#class-Dse) ========================================================================================================== The main entry point to the DataStax Enterprise PHP Driver. Use `[Dse::cluster()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#method-cluster) ` to build a cluster instance. Use `[Dse::ssl()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#method-ssl) ` to build SSL options instance. Use `[Dse::graphOptions()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#method-graphOptions) ` to build a graph options instance. Constants[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constants) ---------------------------------------------------------------------------------------------------------- ### `CONSISTENCY_ANY`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_ANY) \= 0 Consistency level ANY means the request is fulfilled as soon as the data has been written on the Coordinator. Requests with this consistency level are not guranteed to make it to Replica nodes. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_ONE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_ONE) \= 1 Consistency level ONE guarantees that data has been written to at least one Replica node. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_TWO`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_TWO) \= 2 Consistency level TWO guarantees that data has been written to at least two Replica nodes. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_THREE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_THREE) \= 3 Consistency level THREE guarantees that data has been written to at least three Replica nodes. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_QUORUM`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_QUORUM) \= 4 Consistency level QUORUM guarantees that data has been written to at least the majority of Replica nodes. How many nodes exactly are a majority depends on the replication factor of a given keyspace and is calculated using the formula `ceil(RF / 2 + 1)`, where `ceil` is a mathematical ceiling function and `RF` is the replication factor used. For example, for a replication factor of `5`, the majority is `ceil(5 / 2 + 1) = 3`. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_ALL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_ALL) \= 5 Consistency level ALL guarantees that data has been written to all Replica nodes. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_LOCAL_QUORUM`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_LOCAL_QUORUM) \= 6 Same as `CONSISTENCY_QUORUM`, but confined to the local data center. This consistency level works only with `NetworkTopologyStrategy` replication. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_EACH_QUORUM`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_EACH_QUORUM) \= 7 Consistency level EACH\_QUORUM guarantees that data has been written to at least a majority Replica nodes in all datacenters. This consistency level works only with `NetworkTopologyStrategy` replication. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_SERIAL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_SERIAL) \= 8 This is a serial consistency level, it is used in conditional updates, e.g. (`CREATE|INSERT ... IF NOT EXISTS`), and should be specified as the `serial_consistency` execution option when invoking `session.execute` or `session.execute_async`. Consistency level SERIAL, when set, ensures that a Paxos commit fails if any of the replicas is down. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_LOCAL_SERIAL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_LOCAL_SERIAL) \= 9 Same as `CONSISTENCY_SERIAL`, but confined to the local data center. This consistency level works only with `NetworkTopologyStrategy` replication. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `CONSISTENCY_LOCAL_ONE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CONSISTENCY_LOCAL_ONE) \= 10 Same as `CONSISTENCY_ONE`, but confined to the local data center. This consistency level works only with `NetworkTopologyStrategy` replication. See Also: * `[Session::execute()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Session/#method-execute) ` ### `VERIFY_NONE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-VERIFY_NONE) \= 0 Perform no verification of nodes when using SSL encryption. See Also: * `[Builder::withVerifyFlags()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/SSLOptions/class.Builder/#method-withVerifyFlags) ` ### `VERIFY_PEER_CERT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-VERIFY_PEER_CERT) \= 1 Verify presence and validity of SSL certificates. See Also: * `[Builder::withVerifyFlags()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/SSLOptions/class.Builder/#method-withVerifyFlags) ` ### `VERIFY_PEER_IDENTITY`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-VERIFY_PEER_IDENTITY) \= 2 Verify that the IP address matches the SSL certificate’s common name or one of its subject alternative names. This implies the certificate is also present. See Also: * `[Builder::withVerifyFlags()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/SSLOptions/class.Builder/#method-withVerifyFlags) ` ### `BATCH_LOGGED`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-BATCH_LOGGED) \= 0 See Also: * `[BatchStatement::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.BatchStatement/#method-__construct) ` ### `BATCH_UNLOGGED`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-BATCH_UNLOGGED) \= 1 See Also: * `[BatchStatement::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.BatchStatement/#method-__construct) ` ### `BATCH_COUNTER`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-BATCH_COUNTER) \= 2 See Also: * `[BatchStatement::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.BatchStatement/#method-__construct) ` ### `LOG_DISABLED`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-LOG_DISABLED) \= 0 Used to disable logging. ### `LOG_CRITICAL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-LOG_CRITICAL) \= 1 Allow critical level logging. ### `LOG_ERROR`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-LOG_ERROR) \= 2 Allow error level logging. ### `LOG_WARN`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-LOG_WARN) \= 3 Allow warning level logging. ### `LOG_INFO`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-LOG_INFO) \= 4 Allow info level logging. ### `LOG_DEBUG`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-LOG_DEBUG) \= 5 Allow debug level logging. ### `LOG_TRACE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-LOG_TRACE) \= 6 Allow trace level logging. ### `TYPE_TEXT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_TEXT) \= ‘text’ When using a map, collection or set of type text, all of its elements must be strings. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_ASCII`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_ASCII) \= ‘ascii’ When using a map, collection or set of type ascii, all of its elements must be strings. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_VARCHAR`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_VARCHAR) \= ‘varchar’ When using a map, collection or set of type varchar, all of its elements must be strings. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_BIGINT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_BIGINT) \= ‘bigint’ When using a map, collection or set of type bigint, all of its elements must be instances of `[Dse\Bigint](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Bigint/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_SMALLINT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_SMALLINT) \= ‘smallint’ When using a map, collection or set of type smallint, all of its elements must be instances of `[Dse\Inet](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Inet/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_TINYINT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_TINYINT) \= ‘tinyint’ When using a map, collection or set of type tinyint, all of its elements must be instances of `[Dse\Inet](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Inet/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_BLOB`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_BLOB) \= ‘blob’ When using a map, collection or set of type blob, all of its elements must be instances of `[Dse\Blob](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Blob/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_BOOLEAN`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_BOOLEAN) \= ‘boolean’ When using a map, collection or set of type bool, all of its elements must be boolean. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_COUNTER`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_COUNTER) \= ‘counter’ When using a map, collection or set of type counter, all of its elements must be instances of `[Dse\Bigint](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Bigint/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_DECIMAL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_DECIMAL) \= ‘decimal’ When using a map, collection or set of type decimal, all of its elements must be instances of `[Dse\Decimal](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Decimal/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_DOUBLE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_DOUBLE) \= ‘double’ When using a map, collection or set of type double, all of its elements must be doubles. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_FLOAT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_FLOAT) \= ‘float’ When using a map, collection or set of type float, all of its elements must be instances of `[Dse\Float](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Float/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_INT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_INT) \= ‘int’ When using a map, collection or set of type int, all of its elements must be ints. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_TIMESTAMP`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_TIMESTAMP) \= ‘timestamp’ When using a map, collection or set of type timestamp, all of its elements must be instances of `[Dse\Timestamp](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Timestamp/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_UUID`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_UUID) \= ‘uuid’ When using a map, collection or set of type uuid, all of its elements must be instances of `[Dse\Uuid](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Uuid/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_VARINT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_VARINT) \= ‘varint’ When using a map, collection or set of type varint, all of its elements must be instances of `[Dse\Varint](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Varint/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_TIMEUUID`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_TIMEUUID) \= ‘timeuuid’ When using a map, collection or set of type timeuuid, all of its elements must be instances of `[Dse\Timeuuid](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Timeuuid/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `TYPE_INET`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-TYPE_INET) \= ‘inet’ When using a map, collection or set of type inet, all of its elements must be instances of `[Dse\Inet](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Inet/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.Map/#method-__construct) ` ### `VERSION`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-VERSION) \= ‘1.0.0’ The current version of the extension. ### `CPP_DRIVER_VERSION`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CPP_DRIVER_VERSION) \= ‘2.6.0-dev’ The version of the cpp-driver library used to build the cpp-dse-driver driver library. ### `CPP_DRIVER_DSE_VERSION`[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#constant-CPP_DRIVER_DSE_VERSION) \= ‘1.2.0’ The version of the cpp-dse-driver library used to build the php-dse-driver extension. Methods[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#methods) ------------------------------------------------------------------------------------------------------ static `Cluster\Builder` ### cluster[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#method-cluster) ( ) Creates a new cluster builder for constructing a `[Dse\Cluster](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/interface.Cluster/) ` object. Static This method is static Returns: | Type | Details | | --- | --- | | `[Cluster\Builder](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Cluster/class.Builder/) ` | A cluster builder object with default settings | static `SSLOptions\Builder` ### ssl[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#method-ssl) ( ) Creates a new ssl builder for constructing a `[Dse\SSLOptions](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/class.SSLOptions/) ` object. Static This method is static Returns: | Type | Details | | --- | --- | | `[SSLOptions\Builder](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/SSLOptions/class.Builder/) ` | A SSL options builder with default settings | static `[Graph\Options](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Graph/class.Options/) ` ### graphOptions[](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/index.html#method-graphOptions) ( ) Creates a new graph options builder for constructing a `[Graph\Options](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Graph/class.Options/) ` object. Static This method is static Returns: | Type | Details | | --- | --- | | `[Graph\Options](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/Graph/class.Options/) ` | A graph options builder with default settings | --- # DataStax Enterprise PHP Driver - Building PHP Extension [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/building/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/) * Installing Cassandra PHP Extension[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#installing-cassandra-php-extension) ======================================================================================================================================================= You can build the extension yourself or use one of the provided scripts. Below you’ll find installation instructions for [Linux/OS X](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#linuxos-x) and [Windows](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#windows) . Linux/OS X[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#linux-os-x) ------------------------------------------------------------------------------------------------------- ### Install dependencies[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#install-dependencies) The Cassandra PHP Extension depends on the following libraries: * [The C/C++ driver and its dependencies](http://datastax.github.io/cpp-driver/topics/#installation) . * [The GNU Multiple Precision Arithmetic Library](https://gmplib.org/) . * [Libuv](http://libuv.org/) #### homebrew[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#homebrew) brew install libuv cmake gmp git #### apt-get[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#apt-get) sudo apt-get install g++ make cmake libuv-dev libssl-dev libgmp-dev php5 php5-dev openssl libpcre3-dev git #### yum[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#yum) sudo yum install automake cmake gcc gcc-c++ git libtool openssl-devel wget gmp gmp-devel boost php-devel pcre-devel git pushd /tmp wget http://dist.libuv.org/dist/v1.8.0/libuv-v1.8.0.tar.gz tar xzf libuv-v1.8.0.tar.gz pushd libuv-v1.8.0 sh autogen.sh ./configure sudo make install popd popd [Refer to the official documentation](http://datastax.github.io/cpp-driver/topics/building/) for the DataStax C/C++ Driver for Apache Cassandra in case you’re having issues installing any of its dependencies. ### Install the PHP extension[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#install-the-php-extension) #### Installing with pecl[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#installing-with-pecl) The PHP driver is published to the official PECL repository, in order to install it, you have to first [install the C/C++ driver v2.2.2+](http://datastax.github.io/cpp-driver/topics/building/) and then run the following command. pecl install cassandra You can also use PECL to install the driver from source by specifying the provided [package.xml](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/package.xml) file path as the argument to `pecl install` command. git clone https://github.com/datastax/php-driver.git cd php-driver pecl install ext/package.xml #### Installing with submoduled, statically compiled version of the C/C++ driver[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#installing-with-submoduled-statically-compiled-version-of-the-c-c-driver) git clone https://github.com/datastax/php-driver.git cd php-driver git submodule update --init cd ext ./install.sh **Note** [The install.sh script](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/install.sh#L25-L35) will also compile and statically link into the extension a submoduled version of the DataStax C/C++ driver for Apache Cassandra. To use a version of cpp driver that you already have on your system, run `phpize`, `./configure` and `make install`. Don’t forget to enable the PHP extension after running [install.sh](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/install.sh) : echo -e "; DataStax PHP Driver\nextension=cassandra.so" >> `php --ini | grep "Loaded Configuration" | sed -e "s|.*:\s*||"` Windows[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#windows) ------------------------------------------------------------------------------------------------- We provide [a self-contained batch script](https://github.com/datastax/php-dse-driver/blob/master/ext/vc_build.bat) for building the PHP driver and all of its dependencies. In order to run it, you have to install the build dependencies and clone the repository with the DataStax PHP Driver for Apache Cassandra. ### Obtaining Build Dependencies[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#obtaining-build-dependencies) * Download and install [Bison](http://gnuwin32.sourceforge.net/downlinks/bison.php) . * Make sure Bison is in your system PATH and not installed in a directory with spaces (e.g. `%SYSTEMDRIVE%\GnuWin32`) * Download and install [CMake](http://www.cmake.org/download) . * Make sure to select the option “Add CMake to the system PATH for all users” or “Add CMake to the system PATH for current user”. * Download and install [Git](http://git-scm.com/download/win) * Make sure to select the option “Use Git from Windows Command Prompt” or manually add the git executable to the system PATH. * Download and install [ActiveState Perl](https://www.perl.org/get.html#win32) * Make sure to select the option “Add Perl to PATH environment variable”. * Download and install [Python v2.7.x](https://www.python.org/downloads) * Make sure to select/install the feature “Add python.exe to Path” ### Building the Driver[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#building-the-driver) The [batch script](https://github.com/datastax/php-dse-driver/blob/master/ext/vc_build.bat) detects installed versions of Visual Studio to simplify the build process on Windows and select the correct version of Visual Studio for the PHP version the driver is being built for. First you will need to open a “Command Prompt” to execute the batch script. Running the batch script without any arguments will build the driver for PHP v7.0 with Zend thread safety (ZTS) and for the current system architecture (e.g. x64). To perform advanced build configuration, execute the batch script with the `--HELP` argument to display the options available. Usage: VC_BUILD.BAT [OPTION...] --DEBUG Enable debug build --RELEASE Enable release build (default) --DISABLE-CLEAN Disable clean build --DISABLE-THREAD-SAFETY Disable thread safety --ENABLE-PACKAGES [version] Enable package generation (5.5, 5.6, 7.0) (*) --ENABLE-TEST-CONFIGURATION Enable test configuration build --PHP-VERSION [version] PHP version 5.5, 5.6, 7.0 (**) --X86 Target 32-bit build (***) --X64 Target 64-bit build (***) C/C++ Driver Options --USE-BOOST-ATOMIC Use Boost atomic --HELP Display this message * Minimum supported officially released PHP binary installations ** Defaults to PHP v7.0 if --PHP-VERSION is not used *** Default target architecture is determined based on system architecture #### Manual/PHP Step-by-Step Windows Build[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#manual-php-step-by-step-windows-build) The PHP driver extension can also be built using the [Build your own PHP on Windows](https://wiki.php.net/internals/windows/stepbystepbuild) instructions followed by the [Building PECL extensions](https://wiki.php.net/internals/windows/stepbystepbuild#building_pecl_extensions) instruction where the driver can be statically linked into the PHP executable or as an import (DLL) library. This process requires that the binary dependencies of the PHP driver extension be included in the `phpdev\vc##\x##\deps` directory along with the standard PHP library dependencies. Use `--enable-cassandra` to built library into the PHP executable and `--enable-cassandra=shared` for import (DLL) library. The PHP driver extension dependencies that are not included with the standard PHP library can be download [here](http://downloads.datastax.com/cpp-driver/windows/) . **Note** The binary libraries downloaded/used must be compatible with the MSVC++ compiler and the PHP driver extension. #### Enable Testing[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/building/index.html#enable-testing) Ensure the driver is built with –ENABLE-TEST-CONFIGURATION in order to execute the [Behat](http://www.behat.org/) test suite and PHPUnit unit tests. You will also need to install CCM; detailed instructions can be found in this blog [post](http://www.datastax.com/dev/blog/ccm-2-0-and-windows) . --- # DataStax Enterprise PHP Driver - Authentication [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/authentication/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/authentication/) * Authentication[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/authentication/index.html#authentication) ============================================================================================================================== Clients that require authentication when connecting to a secured DSE cluster (using `com.datastax.bdp.cassandra.auth.DseAuthenticator`) should use the following examples as reference: * [LDAP and plain-text autentication](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/authentication/dse/) * [Kerberos authentication](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/authentication/kerberos/) --- # DataStax Enterprise PHP Driver - Features [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/) * Features[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/index.html#features) =================================================================================================== The PHP DataStax Enterprise Driver builds on the [core](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/) features need to fully leverage Apache Cassandra in addition to features specifically designed for DataStax Enterprise: * [DSE plaintext and GSSAPI authentication](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/authentication/) * [DSE geospatial types](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/geotypes/) * [DSE graph integration](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/) --- # DataStax Enterprise PHP Driver - Sessions [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/sessions/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/sessions/) * Sessions[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/sessions/index.html#sessions) ============================================================================================================ Session[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/sessions/index.html#session) ---------------------------------------------------------------------------------------------------------- DataStax PHP Driver uses a Session object to execute and prepare statements. --- # DataStax Enterprise PHP Driver - Graph [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/graph/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/) * Graph[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/index.html#graph) =================================================================================================== DataStax Enterprise 5.0+ now includes a graph-orient database. The DSE driver can execute graph queries written in the Gremlin language. Graph queries are executed using either the `Session::executeGraph()` and `Session::executeGraphAsync()` methods and return `Graph\ResultSet` objects which can represent Cassandra types or graph specific types (e.g. vertices and edges). Graph Options[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/index.html#graph-options) ------------------------------------------------------------------------------------------------------------------- Graph options control how graph queries are run and can be specified when constructing a `Dse\Cluster` object or they can be specified per query. At a minimum, a graph name must be provide when running regular graph queries. Running system commands do not require specifying a graph name. # Construct graph options with a graph name "users" $graphOptions = Dse::graphOptions() ->withGraphName("users") ->build(); # Construct a new cluster object with specific graph options $cluster = Dse::cluster() ->withGraphOptions($graphOptions) ->build(); $session = $cluster->connect(); # Execute a graph query using the cluster-level graph options $resultset = $session->executeGraph("g.V().count()"); Graph options can also be specified (or overridden) when executing a query. $cluster = Dse::cluster()->build(); $session = $cluster->connect(); $resultset = $session->executeGraph("g.V().count()", array("graph_name" => "users")); Graph Results[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/index.html#graph-results) ------------------------------------------------------------------------------------------------------------------- A `Dse\Graph\ResultSet` object is returned from the graph execution methods. Resultsets are iterable and indexable list of `Dse\Graph\Result` objects. `Dse\Graph\Result` is an arbitrary data result and it can be various types from simple data types such as numbers and strings, composite data types such as arrays and dictionaries, as well as graph elements such as vertices and edges. # A `Dse\Graph\Result can hold arbitrary data, in this case the number of # vertices held by the graph. $result = $session->execute("g.V().count()")->first(); echo "Vertex count: {$result->value()}" . PHP_EOL; Vertices[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/index.html#vertices) --------------------------------------------------------------------------------------------------------- Vertices are graph elements connected by edges. They contain properties and unlike other graph elements (e.g. edges) vertex properties can contain multiple values and can have properties of their own. $resultset = $session->executeGraph("g.V()"); foreach ($resultset as $result) { $vertex = $result->asVertex(); # Convert to vertex echo "Vertex label: {$vertex->id()['~label']}" . PHP_EOL; foreach($vertex->properties() as $property) { echo "Vertex property name: {$property->name()}" . PHP_EOL; # Each vertex property can contain multiple values foreach ($property->value() as $value) { echo "Vertex property value: {$value['value']}" . PHP_EOL; } } } Edges[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/index.html#edges) --------------------------------------------------------------------------------------------------- Edges connected pairs of vertices. Like vertices they have properties, but they are simple key/value pairs. $resultset = $session->executeGraph("g.E()"); foreach ($resultset as $result) { $edge = $result->asEdge(); echo "Edge type: {$edge->id()['~type']}" . PHP_EOL; # Each edge has an input and output vertex echo "Edge incoming vertex label: {$edge->inVLabel()}" . PHP_EOL; echo "Edge outgoing vertex label: {$edge->outVLabel()}" . PHP_EOL; # Edge properties are simple key/value pairs foreach($edge->properties() as $property) { echo "Edge property name: {$property->name()}" . PHP_EOL; echo "Edge property value: {$property->value()}" . PHP_EOL; } } Paths[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/graph/index.html#paths) --------------------------------------------------------------------------------------------------- Paths describe a list of graph elements that connect two vertices. $resultset = $session->executeGraph("g.V().in().path()"); $path = $resultset->first()->asPath(); echo "Path labels: " . json_encode($path->labels()) . PHP_EOL; echo "Length of path: " . count($path->labels()) . PHP_EOL; $objects = $path->objects(); for ($i = 0; $i < count($objects); $i++) { try { $vertex = $objects[$i]->asVertex(); echo "Object $i is a(n) " . get_class($vertex) . " with the value: " . $vertex->property('name')->value()[0]['value'] . PHP_EOL; } catch(Dse\Exception\DomainException $e) { $edge = $objects[$i]->asEdge(); echo "Object $i is a(n) " . get_class($edge) . " with the value: " . $edge->label(). PHP_EOL; } } --- # DataStax Enterprise PHP Driver - Geospatial types [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/geotypes/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/geotypes/) * Geospatial types[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/geotypes/index.html#geospatial-types) ============================================================================================================================ DataStax Enterprise 5.0+ adds types for representing geospatial data. The three new geospatial types are point, line string and polygon. These types can be specified directly in a query string using [well-known text (WKT)](https://en.wikipedia.org/wiki/Well-known_text) or can be bound to a query using the following objects: [`Dse\Point`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Point/) , [`Dse\LineString`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.LineString/) and [`Dse\Polygon`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Point/) . Point[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/geotypes/index.html#point) ------------------------------------------------------------------------------------------------------ A point is a 2-dimensional location in space represented by two, double precision floating numbers. Tables with columns of this type are created using the type `org.apache.cassandra.db.marshal.PointType` or the shorter `PointType`. $session = Dse::cluster()->build()->connect("examples"); # Create table and add a coordinate for the point of interest using the `Point` # type $session->execute(new Dse\SimpleStatement("CREATE TABLE IF NOT EXISTS points_of_interest (name varchar PRIMARY KEY, coords 'PointType')")); $session->execute(new Dse\SimpleStatement("INSERT INTO points_of_interest (name, coords) VALUES (?, ?)"), new Dse\ExecutionOptions(array("arguments" => array("Eiffel Tower", new Dse\Point(48.8582, 2.2945))))); # Get the coordinates for the inserted location $row = $session->execute(new Dse\SimpleStatement("SELECT * FROM points_of_interest"))->first(); echo "Name: '{$row['name']}' Coords: ({$row['coords']})" . PHP_EOL; Line String[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/geotypes/index.html#line-string) ------------------------------------------------------------------------------------------------------------------ A line string is a 2-dimensional set of lines represented by a string of points. Tables with columns of this type are created using the type `org.apache.cassandra.db.marshal.LineStringType` or the shorter `LineStringType`. # Create table for trail paths $session->execute(new Dse\SimpleStatement("CREATE TABLE IF NOT EXISTS trails (name varchar PRIMARY KEY, path 'LineStringType')")); # Add a new trail path using the `LineString` type $path = new Dse\LineString(new Dse\Point(38, 78), new Dse\Point(39, 78), new Dse\Point(39.5, 79)); # ... $session->execute(new Dse\SimpleStatement("INSERT INTO trails (name, path) VALUES (?, ?)"), new Dse\ExecutionOptions(array("arguments" => array("Appalachian National Scenic Trail", $path)))); # Get the trail's path coordinates $row = $session->execute(new Dse\SimpleStatement("SELECT * FROM trails"))->first(); echo "Name: '{$row['name']}'" . PHP_EOL; echo "Path: " . implode(" --> ", $row['path']->points()) . PHP_EOL; Polygon[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/geotypes/index.html#polygon) ---------------------------------------------------------------------------------------------------------- A polygon is a bound set of line segments that form a closed loop. It is characterized by a set of rings formed by line strings. The first ring represents the external bounds of the polygon and all follow up rings represent holes. The rings must be closed loops so they must be at least four points with the first and last points being the same location. Tables with columns of this type are created using the type `org.apache.cassandra.db.marshal.PolygonType` or the shorter `PolygonType`. # Create a table to represent boundaries of places in the world (in this case a state) $session->execute(new Dse\SimpleStatement("CREATE TABLE IF NOT EXISTS boundaries (name varchar PRIMARY KEY, boundary 'PolygonType')")); # Use a `LineString` to represent the exterior boundary of the state $stateBoundary = new Dse\LineString(new Dse\Point(35, 10), new Dse\Point(45, 45), new Dse\Point(15, 40), new Dse\Point(10, 20), new Dse\Point(35, 10)); # Use a `LineString` to represent the boundary of a county inside the state's # exteriro boundary $countyBoundary = new Dse\LineString(new Dse\Point(20, 30), new Dse\Point(35, 35), new Dse\Point(30, 20), new Dse\Point(20, 30)); # Add the state's boundary using the `Polygon` type $boundary = new Dse\Polygon($stateBoundary, $countyBoundary); $session->execute(new Dse\SimpleStatement("INSERT INTO boundaries (name, boundary) VALUES (?, ?)"), new Dse\ExecutionOptions(array("arguments" => array("California", $boundary)))); $ Get the state's boundary $row = $session->execute(new Dse\SimpleStatement("SELECT * FROM boundaries"))->first(); echo "Name: '{$row['name']}'" . PHP_EOL; echo "State Boundary: " . implode("; ", $row['boundary']->exteriorRing()->points()) . PHP_EOL; foreach ($row['boundary']->interiorRings() as $countyBoundary) { echo "County Boundary: " . implode("; ", $countyBoundary->points()) . PHP_EOLo } --- # DataStax Enterprise PHP Driver - Migration [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/migration/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/migration/) * Migration[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/migration/index.html#migration) =============================================================================================================== When using DataStax Enterprise (DSE) it is highly recommend that your application use the DataStax Enterprise Driver instead of using the DataStax Driver for Apache Cassandra. This will allow your application to take full advantage of DSE. Migrating your application is easy and namespace aliasing can allow your existing code to remain mostly unchanged. use Dse as Cassandra; # Existing code This should work for most code bases, but this has a couple limitations: * Code cannot use fully qualified names when using aliasing (e.g. `\Cassandra\SimpleStatement`) * Code that uses `is_a()` for objects in the `Cassandra` namespace will need to use `instanceof` instead. use Dse as Cassandra; $value = new Cassandra\Float(1); echo "is_a(\$value, 'Cassandra\Float')? " . (is_a($value, "Cassandra\Float") ? "true" : "false") . PHP_EOL; echo "is_a(\$value, Dse\Float)'? " . (is_a($value, "Dse\Float") ? "true" : "false") . PHP_EOL; echo "\$value instaneof 'Cassandra\Float'? " . ($value instanceof Cassandra\Float ? "true" : "false") . PHP_EOL; echo "\$value instaneof 'Dse\Float'? " . ($value instanceof Dse\Float ? "true" : "false") . PHP_EOL; --- # DataStax Enterprise PHP Driver - Dse [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/Dse/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/) * namespace Dse[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/index.html#namespace-Dse) ============================================================================================================ Namespaces[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/index.html#namespaces) ------------------------------------------------------------------------------------------------------ * `[Dse\Cluster](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/) ` * `[Dse\Exception](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Exception/) ` * `[Dse\Graph](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Graph/) ` * `[Dse\RetryPolicy](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/RetryPolicy/) ` * `[Dse\SSLOptions](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/SSLOptions/) ` * `[Dse\TimestampGenerator](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/TimestampGenerator/) ` * `[Dse\Type](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Type/) ` Classes[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/index.html#classes) ------------------------------------------------------------------------------------------------ * `[Dse\BatchStatement](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.BatchStatement/) ` * `[Dse\Bigint](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Bigint/) ` * `[Dse\Blob](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Blob/) ` * `[Dse\Collection](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/) ` * `[Dse\Custom](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Custom/) ` * `[Dse\Date](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Date/) ` * `[Dse\Decimal](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Decimal/) ` * `[Dse\DefaultAggregate](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultAggregate/) ` * `[Dse\DefaultCluster](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultCluster/) ` * `[Dse\DefaultColumn](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultColumn/) ` * `[Dse\DefaultFunction](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultFunction/) ` * `[Dse\DefaultIndex](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultIndex/) ` * `[Dse\DefaultKeyspace](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultKeyspace/) ` * `[Dse\DefaultMaterializedView](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultMaterializedView/) ` * `[Dse\DefaultSchema](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultSchema/) ` * `[Dse\DefaultSession](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultSession/) ` * `[Dse\DefaultTable](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.DefaultTable/) ` * `[Dse\ExecutionOptions](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/) ` * `[Dse\Float_](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Float_/) ` * `[Dse\FutureClose](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.FutureClose/) ` * `[Dse\FuturePreparedStatement](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.FuturePreparedStatement/) ` * `[Dse\FutureRows](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.FutureRows/) ` * `[Dse\FutureSession](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.FutureSession/) ` * `[Dse\FutureValue](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.FutureValue/) ` * `[Dse\Inet](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Inet/) ` * `[Dse\LineString](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.LineString/) ` * `[Dse\Map](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/) ` * `[Dse\MaterializedView](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.MaterializedView/) ` * `[Dse\Point](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Point/) ` * `[Dse\Polygon](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Polygon/) ` * `[Dse\PreparedStatement](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.PreparedStatement/) ` * `[Dse\Rows](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Rows/) ` * `[Dse\Set](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/) ` * `[Dse\SimpleStatement](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.SimpleStatement/) ` * `[Dse\Smallint](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Smallint/) ` * `[Dse\SSLOptions](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.SSLOptions/) ` * `[Dse\Time](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Time/) ` * `[Dse\Timestamp](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Timestamp/) ` * `[Dse\Timeuuid](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Timeuuid/) ` * `[Dse\Tinyint](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Tinyint/) ` * `[Dse\Tuple](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Tuple/) ` * `[Dse\Type](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Type/) ` * `[Dse\UserTypeValue](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.UserTypeValue/) ` * `[Dse\Uuid](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Uuid/) ` * `[Dse\Varint](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Varint/) ` Interfaces[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/index.html#interfaces) ------------------------------------------------------------------------------------------------------ * `[Dse\Aggregate](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Aggregate/) ` * `[Dse\Cluster](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Cluster/) ` * `[Dse\Column](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Column/) ` * `[Dse\Exception](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Exception/) ` * `[Dse\Function_](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Function_/) ` * `[Dse\Future](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Future/) ` * `[Dse\Index](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Index/) ` * `[Dse\Keyspace](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Keyspace/) ` * `[Dse\Numeric](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Numeric/) ` * `[Dse\RetryPolicy](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.RetryPolicy/) ` * `[Dse\Schema](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Schema/) ` * `[Dse\Session](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Session/) ` * `[Dse\Statement](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Statement/) ` * `[Dse\Table](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Table/) ` * `[Dse\TimestampGenerator](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.TimestampGenerator/) ` * `[Dse\UuidInterface](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.UuidInterface/) ` * `[Dse\Value](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Value/) ` --- # DataStax Enterprise PHP Driver - API docs [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/) * API Documentation Index[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/index.html#api-documentation-index) ============================================================================================================================ Namespaces[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/index.html#namespaces) -------------------------------------------------------------------------------------------------- * `[Dse](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/) ` Classes[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/index.html#classes) -------------------------------------------------------------------------------------------- * `[Dse](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/) ` --- # DataStax Enterprise PHP Driver - Core [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/features/core/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/) * Core[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#core) ================================================================================================ Usage[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#usage) -------------------------------------------------------------------------------------------------- ### Specifying addresses of DSE nodes[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#specifying-addresses-of-dse-nodes) [`withContactPoints()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withContactPoints) and [`withPort()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withPort) methods of the [`Dse\Cluster\Builder`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/) are used to specify IP addresses or hostnames and port number of the nodes in a given DSE cluster. Note that you don’t have to specify the addresses of all hosts in your cluster. Once the driver has established a connection to any host, it will perform auto-discovery and connect to all hosts in the cluster. withContactPoints('10.0.1.24', 'example.com', 'localhost') ->withPort(9042) ->build(); $session = $cluster->connect(); ### Discovering nodes in the cluster[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#discovering-nodes-in-the-cluster) After the initial connection to one of the hosts specified via `withContactPoints()` succeeds, the driver discovers the addresses and connects to all members of the cluster automatically. You can also see the nodes that the driver discovered by running `SELECT * FROM system.peers`. ### Persistent sessions[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#persistent-sessions) In order to limit the startup time and total number of connections to a DSE cluster, the PHP Driver enables persistent sessions by default. All cluster and sessions using the same initial configuration will be shared across requests when persistent sessions are enabled. You can toggle this setting using [`Dse\Cluster\Builder::withPersistentSessions()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withPersistentSessions) . withPersistentSessions(false) ->build(); $session = $cluster->connect(); Note that disabling persistent sessions will cause a significant slow down of cluster initialization as the connections will be forced to get re-established for every request. Once persistent sessions are enabled, you can view how many of them are currently active. They will be exposed in the Dse extension section of `phpinfo()`. Persistent sessions stay alive for the duration of the parent process, typically a php-fpm worker or apache worker. These sessions will be reused for all requests served by that worker process. Once a worker process has reached its end of life, sessions will get cleaned up automatically and will be re-create in the new process. ### Configuring load balancing policy[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#configuring-load-balancing-policy) The PHP Driver comes with a variety of load balancing policies. By default it uses a combination of latency aware, token aware and data center aware round robin load balancing. The token aware load balancing policy uses the same hashing algorithms as the Apache Cassandra to directly route the execution of prepared statements to the replica node, avoiding an additional network hop to/from the coordinator. You can toggle its usage with [`Dse\Cluster\Builder::withTokenAwareRouting()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withTokenAwareRouting) . withTokenAwareRouting(false) ->build(); $session = $cluster->connect(); The default datacenter aware round robin load balancing policy is configured to keep all traffic in the same datacenter. Upon connecting to a host from the initial list of contact points, the driver will consider that host’s datacenter to be local. Only hosts from the same datacenter will be connected to and used for executing statements. You can override the name of the local datacenter. The number of hosts from remote datacenters that the driver may use and whether it should execute statements with local consistencies on those hosts in case none of the local hosts are available. All of that is configurable via [`Dse\Cluster\Builder::withDatacenterAwareRoundRobinLoadBalancingPolicy()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withDatacenterAwareRoundRobinLoadBalancingPolicy) . withDatacenterAwareRoundRobinLoadBalancingPolicy("us-west", 2, true) ->build(); $session = $cluster->connect(); You may disable datacenter awareness by calling [`Dse\Cluster\Builder::withRoundRobinLoadBalancingPolicy()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withRoundRobinLoadBalancingPolicy) . withRoundRobinLoadBalancingPolicy() ->build(); $session = $cluster->connect(); Finally, latency-aware routing ensures that requests are routed to the hosts that respond the fastest. You can switch it off via [`Dse\Cluster\Builder::withLatencyAwareRouting()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withLatencyAwareRouting) . withLatencyAwareRouting(false) ->build(); $session = $cluster->connect(); ### Setting protocol version[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#setting-protocol-version) The PHP driver will automatically negotiate native protocol version of TCP connections to the latest supported by both the driver and Apache Cassandra servers. It does this by attempting connection at the highest supported protocol version (currently 2) and negotiating it down upon unsupported version responses from the server. In a scenario with an Apache Cassandra cluster consisting of nodes of mixed versions (e.g. 1.2.x and 2.0.x), this might pose problems as the driver could establish native protocol version to be 2, while some of the nodes don’t support it, causing connections to the rest of the cluster to fail. You can force the driver to start negotiation at a lower protocol version by using [`Dse\Cluster\Builder::withProtocolVersion()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withProtocolVersion) . withProtocolVersion(1) ->build(); $session = $cluster->connect(); ### Tweaking driver’s throughput[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#tweaking-driver-s-throughput) There are a few variables affecting the total throughput of the driver that can be tweaked client-side. The maximum number of requests that can be executed at the same time is calculated with the following formula: inflight_requests = io_threads * requests_per_connection * maximum_number_of_connections_per_host * connected_hosts Where `io_threads` by default is `1`, `requests_per_connection` for the currently supported protocol versions is `128`, `maximum_number_of_connections_per_host` by default is `2` and `connected_hosts` is the total number of hosts that can be connected to. This last variable depends on the load balancing policy used, data center aware policy only connects to the hosts in the same data center by default. You can change the value of `io_threads` from the formula above by using [`Dse\Cluster\Builder::withIOThreads()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withIOThreads) . withIOThreads(4) ->build(); $session = $cluster->connect(); You can change the value of `maximum_number_of_connections_per_host` from the formula above by using [`Dse\Cluster\Builder::withConnectionsPerHost()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withConnectionsPerHost) . withConnectionsPerHost(4, 8) ->build(); $session = $cluster->connect(); ### Disabling TCP nodelay[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#disabling-tcp-nodelay) By default, the driver enables TCP nodelay (Nagle’s algorithm) on all connections it uses. Disabling it is not recommended but possible via [`Dse\Cluster\Builder::withTCPNodelay()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withTCPNodelay) . withTCPNodelay(false) ->build(); $session = $cluster->connect(); ### Enabling TCP keepalive[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#enabling-tcp-keepalive) By default, TCP keepalive is disabled. It can be useful to make sure TCP connections are not silently dropped by a firewall or some other intermediary network device. You can enable it using [`Dse\Cluster\Builder::withTCPKeepalive()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withTCPKeepalive) . withTCPKeepalive(10) ->build(); $session = $cluster->connect(); ### Authenticating via `PasswordAuthenticator`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#authenticating-via-password-authenticator) The PHP Driver supports Apache Cassandra’s built-in password authentication mechanism. To enable it, use [`Dse\Cluster\Builder::withCredentials()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withCredentials) . withCredentials("username", "password") ->build(); $session = $cluster->connect(); ### Enabling SSL encryption[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#enabling-ssl-encryption) The PHP Driver supports SSL encryption of network connections. You must configure [`Dse\SSLOptions`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.SSLOptions/) using the [`Dse\SSLOptions\Builder`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/SSLOptions/class.Builder/) . withTrustedCerts('node1.pem', 'node2.pem') ->withVerifyFlags(Dse::VERIFY_PEER_CERT | Dse::VERIFY_PEER_IDENTITY) ->withClientCert('client.pem') ->withPrivateKey('id_rsa', 'passphrase') ->build() $cluster = Dse::cluster() ->withSSL($ssl) ->build(); $session = $cluster->connect(); ### Executing queries[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#executing-queries) You run CQL statements by passing them to [`Dse\Session::execute()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Session/) . execute(new Dse\SimpleStatement('SELECT keyspace_name, columnfamily_name FROM system.schema_columnfamilies')); foreach ($result as $row) { printf("The keyspace \"%s\" has a table \"%s\".\n", $row['keyspace_name'], $row['columnfamily_name']); } ### Parameterized queries[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#parameterized-queries) **If you’re using Cassandra 2.0 or later** you no longer have to build CQL strings when you want to insert a value in a query, there’s a new feature that lets you bind values with regular statements: execute( new Dse\SimpleStatement("UPDATE users SET age = ? WHERE user_name = ?"), new Dse\ExecutionOptions(array( 'arguments' => array(41, 'Sam') )) ); For frequently executed queries, it’s strongly recommended to use prepared statements. As a rule of thumb, if your application is sending a request more than once, a prepared statement is almost always the right choice. ### Prepared statements[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#prepared-statements) The driver supports prepared statements. Use [`Dse\Session::prepare()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Session/#method.prepare) to create a [`Dse\PreparedStatement`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.PreparedStatement/) object, and then call [`Dse\Session::execute()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Session/#method.execute) . prepare('INSERT INTO users (username, email) VALUES (?, ?)'); $session->execute($statement, new Dse\ExecutionOptions(array( 'arguments' => array('avalanche123', 'bulat.shakirzyanov@datastax.com') ))); A prepared statement can be run many times, but the CQL parsing will only be done once on each node. Use prepared statements for queries you run over and over again. ### Executing statements in parallel[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#executing-statements-in-parallel) With fully asynchronous API, it is very easy to run queries in parallel: prepare("UPDATE users SET age = ? WHERE user_name = ?"); $futures = array(); // execute all statements in background foreach ($data as $arguments) { $futures[]= $session->executeAsync($statement, new ExecutionOptions(array( 'arguments' => $arguments ))); } // wait for all statements to complete foreach ($futures as $future) { // we will not wait for each result for more than 5 seconds $future->get(5); } Note that it is not enough to simply create a [`Dse\Future`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Future/) by calling one of the `*Async()` methods, you must ensure that this future has enough time to be executed by calling [`Dse\Future::get()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Future/#method.get) . ### Creating keyspaces and tables[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#creating-keyspaces-and-tables) There is no special facility for creating keyspaces and tables, they are created by executing CQL: execute($createKeyspace); $session->execute('USE measurements'); $session->execute($createTable); You can also `ALTER` keyspaces and tables, and you can read more about that in the [CQL3 syntax documentation](https://github.com/apache/cassandra/blob/cassandra-2.0/doc/cql3/CQL.textile) . ### Batch statements[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#batch-statements) **If you’re using Cassandra 2.0 or later** you can build batch requests, either from simple or prepared statements. Batches must not contain any select statements, only `INSERT`, `UPDATE` and `DELETE` statements are allowed. You can mix any combination of statements in a batch: prepare("UPDATE users SET name = ? WHERE user_id = ?"); $batch->add($statement, array('Sue', 'unicorn31')); $statement = new Dse\SimpleStatement("UPDATE users SET age = 19 WHERE user_id = 'unicorn31'"); $batch->add($statement); $statement = new Dse\SimpleStatement("INSERT INTO activity (user_id, what, when) VALUES (?, 'login', NOW())"); $batch->add($statement, array('unicorn31')); $session->execute($batch); Batches can have one of three different types: `logged`, `unlogged` or `counter`, where `logged` is the default. Their exact semantics are defined in the [Cassandra documentation](http://docs.datastax.com/en/cql/3.1/cql/cql_reference/batch_r.html) , but this is how you specify which one you want: withDefaultPageSize(200) ->build(); $session = $cluster->connect(); You can also override the page size on a per-execute basis by adding the `page_size` option to [`Dse\ExecutionOptions`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/) : execute($statement, new Dse\ExecutionOptions(array('page_size' => 100))); while ($result) { foreach ($result as $row) { var_dump($row); } $result = $result->nextPage(); } [Read more about `Dse\Rows::nextPage()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Rows/#method.nextPage) ### Consistency[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#consistency) You can specify the default consistency to use for statements execution when you create a new `Dse\Cluster`: withDefaultConsistency(Dse::CONSISTENCY_LOCAL_QUORUM) ->build(); $session = $cluster->connect(); [Read more `Dse\Cluster\Builder::withDefaultConsistency()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withDefaultConsistency) Consistency can also be passed via `Dse\ExecutionOptions`. execute( new Dse\SimpleStatement('SELECT * FROM users'), new Dse\ExecutionOptions(array('consistency' => Dse::CONSISTENCY_LOCAL_QUORUM)) ); $statement = $session->prepare('SELECT * FROM users'); $session->execute($statement, new Dse\ExecutionOptions(array( 'consistency' => Dse::CONSISTENCY_LOCAL_QUORUM ))); $batch = new Dse\BatchStatement(); $batch->add(new Dse\SimpleStatement("UPDATE users SET email = 'sue@foobar.com' WHERE id = 'sue'")); $batch->add(new Dse\SimpleStatement("UPDATE users SET email = 'tom@foobar.com' WHERE id = 'tom'")); $session->execute($batch, new Dse\ExecutionOptions(array( 'consistency' => Dse::CONSISTENCY_LOCAL_QUORUM ))); [Read more about `Dse\ExecutionOptions`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/) [Read more about `Dse\Session::execute()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Session/#method.execute) The default consistency level unless you’ve set it yourself is `Dse::CONSISTENCY_LOCAL_ONE`. Consistency is ignored for `USE`, `TRUNCATE`, `CREATE` and `ALTER` statements, and some (like `Dse::CONSISTENCY_ANY`) aren’t allowed in all situations. ### Schema Metadata[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#schema-metadata) The DataStax PHP driver exposes schema metadata via [`Dse\Schema`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Schema/) object, available using [`Dse\Session::schema()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Session/#method.schema) . Schema metadata includes information about keyspace, tables and columns and it automatically kept up-to-date with the Cassandra cluster. schema(); foreach ($schema->keyspaces() as $keyspace) { printf("Keyspace: %s\n", $keyspace->name()); printf(" Replication Strategy: %s\n", $keyspace->replicationClassName()); printf(" Replication Options:\n"); $options = $keyspace->replicationOptions(); $keys = $options->keys(); $values = $options->values(); foreach (array_combine($keys, $values) as $key => $value) { printf(" %s: %s\n", $key, $value); } printf(" Durable Writes: %s\n", $keyspace->hasDurableWrites() ? 'true' : 'false'); foreach ($keyspace->tables() as $table) { printf(" Table: %s\n", $table->name()); printf(" Comment: %s\n", $table->comment()); printf(" Read Repair Chance: %f\n", $table->readRepairChance()); printf(" Local Read Repair Chance: %f\n", $table->localReadRepairChance()); printf(" GC Grace Seconds: %d\n", $table->gcGraceSeconds()); printf(" Caching: %s\n", $table->caching()); printf(" Bloom Filter FP Chance: %f\n", $table->bloomFilterFPChance()); printf(" Memtable Flush Period Ms: %d\n", $table->memtableFlushPeriodMs()); printf(" Default Time To Live: %d\n", $table->defaultTTL()); printf(" Speculative Retry: %s\n", $table->speculativeRetry()); printf(" Index Interval: %d\n", $table->indexInterval()); printf(" Compaction Strategy: %s\n", $table->compactionStrategyClassName()); printf(" Populate IO Cache On Flush: %s\n", $table->populateIOCacheOnFlush() ? 'yes' : 'no'); printf(" Replicate On Write: %s\n", $table->replicateOnWrite() ? 'yes' : 'no'); printf(" Max Index Interval: %d\n", $table->maxIndexInterval()); printf(" Min Index Interval: %d\n", $table->minIndexInterval()); foreach ($table->columns() as $column) { printf(" Column: %s\n", $column->name()); printf(" Type: %s\n", $column->type()); printf(" Order: %s\n", $column->isReversed() ? 'desc' : 'asc'); printf(" Frozen: %s\n", $column->isFrozen() ? 'yes' : 'no'); printf(" Static: %s\n", $column->isStatic() ? 'yes' : 'no'); if ($column->indexName()) { printf(" Index: %s\n", $column->indexName()); printf(" Index Options: %s\n", $column->indexOptions()); } } } } **NOTE** A new instance of [`Dse\Schema`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Schema/) is returned each time [`Dse\Session::schema()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Session/#method.schema) is called. This instance is a simple value object and its information, such as keyspaces, tables and columns will not be kept up-to-date with the state of the cluster. In order to obtain the latest schema metadata, you have to call [`Dse\Session::schema()`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Session/#method.schema) again. ### Data Types[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#data-types) The PHP driver for Apache Cassandra supports [a variety of datatypes](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/datatypes/) . You can also use the rich type metadata API to define and inspect types, as well as validate data objects. The example below defines and creates a [`Dse\Map`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/) using [`Dse\Type`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Type/) interface. create('a', 1, 'b', 2, 'c', 3, 'd', 4); var_dump(array_combine($map->keys(), $map->values())); **NOTE** The `create()` method or various types validates and coerces provided values into the target type. ### Logging[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#logging) You can configure the location of the log file for the driver as well as the log level using the following `php.ini` settings: [dse] dse.log=syslog dse.log_level=INFO You can specify any file path as `dse.log`. The special value `syslog` can be used to for the driver to use syslog for logging. Syslog is only supported on \*nix systems. The possible log levels are: * CRITICAL * ERROR * WARN * INFO * DEBUG * TRACE Most of the logging will be when the driver connects and discovers new nodes, when connections fail and so on. The logging is designed to not cause much overhead and only relatively rare events are logged (e.g. normal requests are not logged). Architecture[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#architecture) ---------------------------------------------------------------------------------------------------------------- The PHP Driver follows the architecture of [the C/C++ Driver](http://datastax.github.io/cpp-driver/topics/#architecture) that it wraps. ### Persistent sessions[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/features/core/index.html#persistent-sessions) By default, the driver uses persistent sessions to prevent each request from creating completely new TCP connections to a DSE cluster. You can toggle this functionality using [`Dse\Cluster\Builder::withPersistentSessions`](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/#method.withPersistentSessions) --- # DataStax Enterprise PHP Driver - Dse [DataStax Enterprise PHP Driver 1.0 (Earlier version)](https://docs.datastax.com/en/developer/php-driver-dse/index.html) 1.0 * [1.1](https://docs.datastax.com/en/developer/php-driver-dse/1.1/api/class.Dse/) * [1.0](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/) * class Dse[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#class-Dse) ========================================================================================================== The main entry point to the DataStax Enterprise PHP Driver. Use `[Dse::cluster()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#method-cluster) ` to build a cluster instance. Use `[Dse::ssl()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#method-ssl) ` to build SSL options instance. Use `[Dse::graphOptions()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#method-graphOptions) ` to build a graph options instance. Constants[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constants) ---------------------------------------------------------------------------------------------------------- ### `CONSISTENCY_ANY`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_ANY) \= 0 Consistency level ANY means the request is fulfilled as soon as the data has been written on the Coordinator. Requests with this consistency level are not guranteed to make it to Replica nodes. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_ONE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_ONE) \= 1 Consistency level ONE guarantees that data has been written to at least one Replica node. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_TWO`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_TWO) \= 2 Consistency level TWO guarantees that data has been written to at least two Replica nodes. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_THREE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_THREE) \= 3 Consistency level THREE guarantees that data has been written to at least three Replica nodes. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_QUORUM`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_QUORUM) \= 4 Consistency level QUORUM guarantees that data has been written to at least the majority of Replica nodes. How many nodes exactly are a majority depends on the replication factor of a given keyspace and is calculated using the formula `ceil(RF / 2 + 1)`, where `ceil` is a mathematical ceiling function and `RF` is the replication factor used. For example, for a replication factor of `5`, the majority is `ceil(5 / 2 + 1) = 3`. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_ALL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_ALL) \= 5 Consistency level ALL guarantees that data has been written to all Replica nodes. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_LOCAL_QUORUM`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_LOCAL_QUORUM) \= 6 Same as `CONSISTENCY_QUORUM`, but confined to the local data center. This consistency level works only with `NetworkTopologyStrategy` replication. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_EACH_QUORUM`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_EACH_QUORUM) \= 7 Consistency level EACH\_QUORUM guarantees that data has been written to at least a majority Replica nodes in all datacenters. This consistency level works only with `NetworkTopologyStrategy` replication. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_SERIAL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_SERIAL) \= 8 This is a serial consistency level, it is used in conditional updates, e.g. (`CREATE|INSERT ... IF NOT EXISTS`), and should be specified as the `serial_consistency` option of the `[Dse\ExecutionOptions](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/) ` instance. Consistency level SERIAL, when set, ensures that a Paxos commit fails if any of the replicas is down. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_LOCAL_SERIAL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_LOCAL_SERIAL) \= 9 Same as `CONSISTENCY_SERIAL`, but confined to the local data center. This consistency level works only with `NetworkTopologyStrategy` replication. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `CONSISTENCY_LOCAL_ONE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CONSISTENCY_LOCAL_ONE) \= 10 Same as `CONSISTENCY_ONE`, but confined to the local data center. This consistency level works only with `NetworkTopologyStrategy` replication. See Also: * `[ExecutionOptions::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.ExecutionOptions/#method-__construct) ` ### `VERIFY_NONE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-VERIFY_NONE) \= 0 Perform no verification of nodes when using SSL encryption. See Also: * `[Builder::withVerifyFlags()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/SSLOptions/class.Builder/#method-withVerifyFlags) ` ### `VERIFY_PEER_CERT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-VERIFY_PEER_CERT) \= 1 Verify presence and validity of SSL certificates. See Also: * `[Builder::withVerifyFlags()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/SSLOptions/class.Builder/#method-withVerifyFlags) ` ### `VERIFY_PEER_IDENTITY`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-VERIFY_PEER_IDENTITY) \= 2 Verify that the IP address matches the SSL certificate’s common name or one of its subject alternative names. This implies the certificate is also present. See Also: * `[Builder::withVerifyFlags()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/SSLOptions/class.Builder/#method-withVerifyFlags) ` ### `BATCH_LOGGED`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-BATCH_LOGGED) \= 0 See Also: * `[BatchStatement::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.BatchStatement/#method-__construct) ` ### `BATCH_UNLOGGED`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-BATCH_UNLOGGED) \= 1 See Also: * `[BatchStatement::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.BatchStatement/#method-__construct) ` ### `BATCH_COUNTER`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-BATCH_COUNTER) \= 2 See Also: * `[BatchStatement::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.BatchStatement/#method-__construct) ` ### `LOG_DISABLED`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-LOG_DISABLED) \= 0 Used to disable logging. ### `LOG_CRITICAL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-LOG_CRITICAL) \= 1 Allow critical level logging. ### `LOG_ERROR`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-LOG_ERROR) \= 2 Allow error level logging. ### `LOG_WARN`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-LOG_WARN) \= 3 Allow warning level logging. ### `LOG_INFO`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-LOG_INFO) \= 4 Allow info level logging. ### `LOG_DEBUG`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-LOG_DEBUG) \= 5 Allow debug level logging. ### `LOG_TRACE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-LOG_TRACE) \= 6 Allow trace level logging. ### `TYPE_TEXT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_TEXT) \= ‘text’ When using a map, collection or set of type text, all of its elements must be strings. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_ASCII`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_ASCII) \= ‘ascii’ When using a map, collection or set of type ascii, all of its elements must be strings. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_VARCHAR`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_VARCHAR) \= ‘varchar’ When using a map, collection or set of type varchar, all of its elements must be strings. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_BIGINT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_BIGINT) \= ‘bigint’ When using a map, collection or set of type bigint, all of its elements must be instances of `[Dse\Bigint](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Bigint/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_SMALLINT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_SMALLINT) \= ‘smallint’ When using a map, collection or set of type smallint, all of its elements must be instances of `[Dse\Inet](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Inet/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_TINYINT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_TINYINT) \= ‘tinyint’ When using a map, collection or set of type tinyint, all of its elements must be instances of `[Dse\Inet](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Inet/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_BLOB`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_BLOB) \= ‘blob’ When using a map, collection or set of type blob, all of its elements must be instances of `[Dse\Blob](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Blob/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_BOOLEAN`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_BOOLEAN) \= ‘boolean’ When using a map, collection or set of type bool, all of its elements must be boolean. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_COUNTER`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_COUNTER) \= ‘counter’ When using a map, collection or set of type counter, all of its elements must be instances of `[Dse\Bigint](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Bigint/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_DECIMAL`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_DECIMAL) \= ‘decimal’ When using a map, collection or set of type decimal, all of its elements must be instances of `[Dse\Decimal](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Decimal/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_DOUBLE`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_DOUBLE) \= ‘double’ When using a map, collection or set of type double, all of its elements must be doubles. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_FLOAT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_FLOAT) \= ‘float’ When using a map, collection or set of type float, all of its elements must be instances of Float. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_INT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_INT) \= ‘int’ When using a map, collection or set of type int, all of its elements must be ints. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_TIMESTAMP`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_TIMESTAMP) \= ‘timestamp’ When using a map, collection or set of type timestamp, all of its elements must be instances of `[Dse\Timestamp](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Timestamp/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_UUID`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_UUID) \= ‘uuid’ When using a map, collection or set of type uuid, all of its elements must be instances of `[Dse\Uuid](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Uuid/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_VARINT`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_VARINT) \= ‘varint’ When using a map, collection or set of type varint, all of its elements must be instances of `[Dse\Varint](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Varint/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_TIMEUUID`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_TIMEUUID) \= ‘timeuuid’ When using a map, collection or set of type timeuuid, all of its elements must be instances of `[Dse\Timeuuid](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Timeuuid/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `TYPE_INET`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-TYPE_INET) \= ‘inet’ When using a map, collection or set of type inet, all of its elements must be instances of `[Dse\Inet](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Inet/) `. See Also: * `[Set::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Set/#method-__construct) ` * `[Collection::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Collection/#method-__construct) ` * `[Map::__construct()](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.Map/#method-__construct) ` ### `VERSION`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-VERSION) \= ‘1.0.0’ The current version of the extension. ### `CPP_DRIVER_VERSION`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CPP_DRIVER_VERSION) \= ‘2.5.0’ The version of the cpp-driver library used to build the cpp-driver-dse driver library. ### `CPP_DRIVER_DSE_VERSION`[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#constant-CPP_DRIVER_DSE_VERSION) \= ‘1.1.0’ The version of the cpp-driver-dse library used to build the php-driver-dse extension. Methods[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#methods) ------------------------------------------------------------------------------------------------------ static `Cluster\Builder` ### cluster[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#method-cluster) ( ) Creates a new cluster builder for constructing a `[Dse\Cluster](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/interface.Cluster/) ` object. Static This method is static Returns: | Type | Details | | --- | --- | | `[Cluster\Builder](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Cluster/class.Builder/) ` | A cluster builder object with default settings | static `SSLOptions\Builder` ### ssl[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#method-ssl) ( ) Creates a new ssl builder for constructing a `[Dse\SSLOptions](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/class.SSLOptions/) ` object. Static This method is static Returns: | Type | Details | | --- | --- | | `[SSLOptions\Builder](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/SSLOptions/class.Builder/) ` | A SSL options builder with default settings | static `[Graph\Options](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Graph/class.Options/) ` ### graphOptions[](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/class.Dse/index.html#method-graphOptions) ( ) Creates a new graph options builder for constructing a `[Graph\Options](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Graph/class.Options/) ` object. Static This method is static Returns: | Type | Details | | --- | --- | | `[Graph\Options](https://docs.datastax.com/en/developer/php-driver-dse/1.0/api/Dse/Graph/class.Options/) ` | A graph options builder with default settings | --- # Page Not Found | DataStax Docs Page Not Found ============== The page you’re looking for doesn’t exist. It may have been moved. You can return to the [start page](https://docs.datastax.com/en/home/index.html) , or follow one of the links in the navigation above. If you arrived on this page by clicking a link on another site, please notify the owner of that site that the link is broken. If you typed the URL of this page manually, please double check that you entered the address correctly. ![](https://static.scarf.sh/a.png?x-pxid=3d61cc2b-8a71-4d6a-a50c-8a3d00ea2c86) --- # DataStax Node.js Driver - Batch statements [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/batch/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/batch/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/batch/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/batch/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/batch/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/batch/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/batch/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/batch/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/batch/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/batch/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/batch/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/batch/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/batch/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/batch/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/batch/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/batch/) * Batch statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/batch/index.html#batch-statements) ------------------------------------------------------------------------------------------------------------------------ It’s common for applications to require atomic batching of multiple `INSERT`, `UPDATE`, or `DELETE` statements, even in different partitions or column families. Thanks to the Cassandra protocol changes introduced in Cassandra 2.0, the driver allows you to execute multiple statements efficiently without the need to concatenate multiple queries. The method `batch()` accepts the queries as first parameter: const query1 = 'UPDATE user_profiles SET email = ? WHERE key = ?'; const query2 = 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)'; const queries = [\ { query: query1, params: [emailAddress, 'hendrix'] },\ { query: query2, params: ['hendrix', 'Changed email', new Date()] } \ ]; // Promise-based call client.batch(queries, { prepare: true }) .then(function() { // All queries have been executed successfully }) .catch(function(err) { // None of the changes have been applied }); Or using the callback-based invocation client.batch(queries, { prepare: true }, function (err) { // All queries have been executed successfully // Or none of the changes have been applied, check err }); By preparing your queries, you will get the best performance and your JavaScript parameters correctly mapped to Cassandra types. The driver will prepare each query once on each host and execute the batch every time with the different parameters provided. Note that Cassandra batches are not suitable for bulk loading, there are dedicated tools for that. Batches allow you to group related updates in a single request, so keep the batch size small (in the order of tens). Starting from Cassandra version 2.0.8, the server issues a warning if the batch size is greater than 5K. Refer to [CQL documentation](https://docs.datastax.com/en/cql/3.3/cql/cql_using/useBatchTOC.html) for information about correct and incorrect use of batches. --- # DataStax Node.js Driver - Authentication [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/auth/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/auth/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/auth/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth/index.html#authentication) =================================================================================================================== The driver includes three authentication providers: * `PlainTextAuthProvider`: Plain-text authentication for Apache Cassandra and DSE. * `DsePlainTextAuthProvider`: Plain-text authentication for DSE unified auth. * `DseGssapiAuthProvider`: GSSAPI authentication for DSE. In case you are using plain-text authentication on the server, you can set the `credentials` when creating the `Client` instance. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints, localDataCenter, credentials: { username: 'my_username', password: 'my_p@ssword1!' } }); Setting the authentication provider[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth/index.html#setting-the-authentication-provider) ------------------------------------------------------------------------------------------------------------------------------------------------------------- For other authentication methods, you can configure the provider in the `Client` options: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints, localDataCenter, authProvider: new cassandra.auth.DseGssapiAuthProvider() }); Note that to use the `DseGssapiAuthProvider` you need to add the dependency to `kerberos` version `~1.0.0` in your application. DSE Unified Authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth/index.html#dse-unified-authentication) ------------------------------------------------------------------------------------------------------------------------------------------- DSE Unified Authentication allows you to: * Proxy Login: Authenticate using a fixed set of authentication credentials but allow authorization of resources based on another user id. * Proxy Execute: Authenticate using a fixed set of authentication credentials but execute requests based on another user id. ### Proxy Login[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth/index.html#proxy-login) Proxy login allows you to authenticate with a user but act as another one. You need to ensure the authenticated user has the permission to use the authorization of resources of the other user. In the following example, we allow user “ben” to authenticate but use the authorization of “alice”. We grant login permission to “ben” by using a `GRANT` CQL query: GRANT PROXY.LOGIN ON ROLE 'alice' TO 'ben' Once “ben” is granted proxy login as “alice”: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: [ 'host1', 'host2' ], localDataCenter, authProvider: new cassandra.auth.DsePlainTextAuthProvider('ben', 'ben', 'alice') }); // All requests will be executed using the authorizationId 'alice' client.execute(query, params, { prepare: true }); ### Proxy Execute[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth/index.html#proxy-execute) Proxy execute allows you to execute requests as another user than the authenticated one. You need to ensure the authenticated user has the permission to use the authorization of resources of the specified user. In the following example will allow the user “ben” to execute requests as “alice”: We grant execute permission to “ben” by using a `GRANT` CQL query: GRANT PROXY.EXECUTE on role user1 to server Once “ben” is granted permission to execute queries as “alice”: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: [ 'host1', 'host2' ], localDataCenter, authProvider: new cassandra.auth.DsePlainTextAuthProvider('ben', 'ben') }); // The following requests will be executed as 'alice' client.execute(query, params, { prepare: true, executeAs: 'alice' }); Please see the [official documentation](https://docs.datastax.com/en/latest-dse/datastax_enterprise/unifiedAuth/unifiedAuthTOC.html) for more details. --- # DataStax Node.js Driver - Home [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * DataStax Node.js Driver for Apache Cassandra®[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#data-stax-node-js-driver-for-apache-cassandra) =================================================================================================================================================================== A modern, [feature-rich](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#features) and highly tunable Node.js client library for Apache Cassandra and [DSE](https://www.datastax.com/products/datastax-enterprise) using exclusively Cassandra’s binary protocol and Cassandra Query Language. Installation[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#installation) ------------------------------------------------------------------------------------------------- $ npm install cassandra-driver [![Build Status](https://api.travis-ci.com/datastax/nodejs-driver.svg?branch=master)](https://travis-ci.org/datastax/nodejs-driver) [![Build status](https://ci.appveyor.com/api/projects/status/m21t2tfdpmkjex1l/branch/master?svg=true)](https://ci.appveyor.com/project/datastax/nodejs-driver/branch/master) Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#features) ----------------------------------------------------------------------------------------- * Simple, Prepared, and [Batch](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/batch/) statements * Asynchronous IO, parallel execution, request pipelining * [Connection pooling](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/connection-pooling/) * Auto node discovery * Automatic reconnection * Configurable [load balancing](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#load-balancing-policy) and [retry policies](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#retry-policy) * Works with any cluster size * Built-in [object mapper](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/) * Both [promise and callback-based API](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/promise-callback/) * [Row streaming and pipes](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#row-streaming-and-pipes) * Built-in TypeScript support Documentation[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#documentation) --------------------------------------------------------------------------------------------------- * [Documentation index](https://docs.datastax.com/en/developer/nodejs-driver/latest/) * [CQL types to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/) * [API docs](https://docs.datastax.com/en/developer/nodejs-driver/latest/api/) * [FAQ](https://docs.datastax.com/en/developer/nodejs-driver/latest/faq/) Getting Help[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#getting-help) ------------------------------------------------------------------------------------------------- You can use the [project mailing list](https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user) or create a ticket on the [Jira issue tracker](https://datastax-oss.atlassian.net/projects/NODEJS/issues) . Basic usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#basic-usage) ----------------------------------------------------------------------------------------------- const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['h1', 'h2'], localDataCenter: 'datacenter1', keyspace: 'ks1' }); const query = 'SELECT name, email FROM users WHERE key = ?'; client.execute(query, [ 'someone' ]) .then(result => console.log('User with email %s', result.rows[0].email)); The driver supports both [promises and callbacks](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/promise-callback/) for the asynchronous methods, you can choose the approach that suits your needs. Note that in order to have concise code examples in this documentation, we will use the promise-based API of the driver along with the `await` keyword. If you are using [DataStax Astra](https://www.datastax.com/products/datastax-astra) you can configure your client by setting the secure bundle and the user credentials: const client = new cassandra.Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); ### Prepare your queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#prepare-your-queries) Using prepared statements provides multiple benefits. Prepared statements are parsed and prepared on the Cassandra nodes and are ready for future execution. Also, when preparing, the driver retrieves information about the parameter types which **allows an accurate mapping between a JavaScript type and a Cassandra type**. The driver will prepare the query once on each host and execute the statement with the bound parameters. // Use query markers (?) and parameters const query = 'UPDATE users SET birth = ? WHERE key=?'; const params = [ new Date(1942, 10, 1), 'jimi-hendrix' ]; // Set the prepare flag in the query options await client.execute(query, params, { prepare: true }); console.log('Row updated on the cluster'); ### Row streaming and pipes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#row-streaming-and-pipes) When using `#eachRow()` and `#stream()` methods, the driver parses each row as soon as it is received, yielding rows without buffering them. // Reducing a large result client.eachRow( 'SELECT time, val FROM temperature WHERE station_id=', ['abc'], (n, row) => { // The callback will be invoked per each row as soon as they are received minTemperature = Math.min(row.val, minTemperature); }, err => { // This function will be invoked when all rows where consumed or an error was encountered } ); The `#stream()` method works in the same way but instead of callback it returns a [Readable Streams2](https://nodejs.org/api/stream.html#stream_class_stream_readable) object in `objectMode` that emits instances of `Row`. It can be **piped** downstream and provides automatic pause/resume logic (it buffers when not read). client.stream('SELECT time, val FROM temperature WHERE station_id=', [ 'abc' ]) .on('readable', function () { // 'readable' is emitted as soon a row is received and parsed let row; while (row = this.read()) { console.log('time %s and value %s', row.time, row.val); } }) .on('end', function () { // Stream ended, there aren't any more rows }) .on('error', function (err) { // Something went wrong: err is a response error from Cassandra }); ### User defined types[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#user-defined-types) [User defined types (UDT)](https://cassandra.apache.org/doc/latest/cql/types.html#udts) are represented as JavaScript objects. For example: Consider the following UDT and table CREATE TYPE address ( street text, city text, state text, zip int, phones set ); CREATE TABLE users ( name text PRIMARY KEY, email text, address frozen
); You can retrieve the user address details as a regular JavaScript object. const query = 'SELECT name, address FROM users WHERE key = ?'; const result = await client.execute(query, [ key ], { prepare: true }); const row = result.first(); const address = row.address; console.log('User lives in %s, %s - %s', address.street, address.city, address.state); Read more information about using [UDTs with the Node.js Driver](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/udts/) . ### Paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#paging) All driver methods use a default `fetchSize` of 5000 rows, retrieving only first page of results up to a maximum of 5000 rows to shield an application against accidentally retrieving large result sets in a single response. `stream()` method automatically fetches the following page once the current one was read. You can also use `eachRow()` method to retrieve the following pages by using `autoPage` flag. See \[paging documentation for more information\]\[doc-paging\]. ### Batch multiple statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#batch-multiple-statements) You can execute multiple statements in a batch to update/insert several rows atomically even in different column families. const queries = [\ {\ query: 'UPDATE user_profiles SET email=? WHERE key=?',\ params: [ emailAddress, 'hendrix' ]\ }, {\ query: 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)',\ params: [ 'hendrix', 'Changed email', new Date() ]\ }\ ]; await client.batch(queries, { prepare: true }); console.log('Data updated on cluster'); Object Mapper[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#object-mapper) --------------------------------------------------------------------------------------------------- The driver provides a built-in [object mapper](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/) that lets you interact with your data like you would interact with a set of documents. Retrieving objects from the database: const videos = await videoMapper.find({ userId }); for (let video of videos) { console.log(video.name); } Updating an object from the database: await videoMapper.update({ id, userId, name, addedDate, description }); You can read more information about [getting started with the Mapper in our documentation](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/getting-started/) . * * * Data types[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#data-types) --------------------------------------------------------------------------------------------- There are few data types defined in the ECMAScript specification, this usually represents a problem when you are trying to deal with data types that come from other systems in JavaScript. The driver supports all the CQL data types in Apache Cassandra (3.0 and below) even for types with no built-in JavaScript representation, like decimal, varint and bigint. Check the documentation on working with [numerical values](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/numerical/) , [uuids](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/uuids/) and [collections](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/collections/) . Logging[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#logging) --------------------------------------------------------------------------------------- Instances of `Client()` are `EventEmitter` and emit `log` events: client.on('log', (level, loggerName, message, furtherInfo) => { console.log(`${level} - ${loggerName}: ${message}`); }); The `level` being passed to the listener can be `verbose`, `info`, `warning` or `error`. Visit the [logging documentation](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/logging/) for more information. Compatibility[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#compatibility) --------------------------------------------------------------------------------------------------- The driver supports all versions of Node.js, Cassandra, and DSE that are not EOL at the time of release. Only LTS eligible branches (i.e. even numbered releases) are supported for Node.js. See the [project documentation](https://github.com/nodejs/release#release-schedule) for more information about the Node.js release cycle. The current version of the driver offers support consistent with this policy for the following: * Apache Cassandra versions 3.0 and above. * DataStax Enterprise versions 5.1 and 6.8. * Node.js versions 18.x, 20.x, and 22.x. Note: DataStax products do not support big-endian systems. Credits[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#credits) --------------------------------------------------------------------------------------- This driver is based on the original work of [Jorge Bay](https://github.com/jorgebay) on [node-cassandra-cql](https://github.com/jorgebay/node-cassandra-cql) and adds a series of advanced features that are common across all other [DataStax drivers](https://github.com/datastax) for Apache Cassandra. The development effort to provide an up to date, high performance, fully featured Node.js Driver for Apache Cassandra will continue on this project, while [node-cassandra-cql](https://github.com/jorgebay/node-cassandra-cql) will be discontinued. License[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/index.html#license) --------------------------------------------------------------------------------------- © DataStax, Inc. Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- # DataStax Node.js Driver - CQL data types to JavaScript types [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/datatypes/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/datatypes/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/datatypes/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/datatypes/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/datatypes/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/datatypes/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/datatypes/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/datatypes/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/datatypes/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/datatypes/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/datatypes/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/datatypes/) * CQL data types to JavaScript types[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/index.html#cql-data-types-to-java-script-types) ================================================================================================================================================================= When retrieving the value of a column from a `Row` object, the value is typed according to the following table. | CQL data type | JavaScript type | | --- | --- | | ascii | String | | bigint | [Long / BigInt](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) | | blob | [Buffer](https://nodejs.org/api/buffer.html) | | boolean | Boolean | | counter | [Long / BigInt](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) | | date | [LocalDate](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/datetime) | | decimal | [BigDecimal](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) | | double | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) | | duration | [Duration](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.Duration/) | | float | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) | | inet | [InetAddress](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.InetAddress/) | | int | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) | | list | [Array](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/collections) | | map | [Object / ECMAScript 6 Map](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/collections) | | set | [Array / ECMAScript 6 Set](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/collections) | | smallint | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) | | text | String | | time | [LocalTime](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/datetime) | | timestamp | [Date](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/datetime) | | timeuuid | [TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/uuids) | | tinyint | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) | | tuple | [Tuple](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/tuples) | | uuid | [Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/uuids) | | varchar | String | | varint | [Integer](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) | | vector | [Vector](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/collections) | Encoding data[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/index.html#encoding-data) ---------------------------------------------------------------------------------------------------------------------- When encoding data, on a normal execute with parameters, the driver tries to guess the target type based on the input type. Values of type `Number` will be encoded as `double` (because `Number` is IEEE 754 double). Consider the following example: const key = 1000; client.execute('SELECT * FROM table1 where key = ?', [ key ]); If the key column is of type `int`, the execution fails. There are two possible ways to avoid this type of problem, as detailed below. ### Prepare your queries (recommended)[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/index.html#prepare-your-queries-recommended) Using prepared statements provides multiple benefits. Prepared statements are parsed and prepared on the Cassandra nodes and are ready for future execution. Also, the driver retrieves information about the parameter types which allows an **accurate mapping between a JavaScript type and a Cassandra type**. Using the previous example, setting the `prepare` flag in the queryOptions will fix it: // Prepare the query before execution client.execute('SELECT * FROM table1 where key = ?', [ key ], { prepare : true }); When using prepared statements, the driver prepares the statement once on each host to execute multiple times. ### Hinting the target data type[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/index.html#hinting-the-target-data-type) Providing parameter hints in the query options is another way around it. // Hint that the first parameter is an integer client.execute('SELECT * FROM table1 where key = ?', [ key ], { hints : ['int'] }); --- # DataStax Node.js Driver - Address resolution [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/address-resolution/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/address-resolution/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/address-resolution/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/address-resolution/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/address-resolution/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/address-resolution/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/address-resolution/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/address-resolution/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/address-resolution/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/address-resolution/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/address-resolution/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/address-resolution/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/address-resolution/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/address-resolution/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/address-resolution/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/address-resolution/) * Address resolution[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/address-resolution/index.html#address-resolution) ========================================================================================================================================= The driver auto-detects new Cassandra nodes when they are added to the cluster by means of server-side push notifications and checking the system tables. For each node, the address the driver receives the address set as [`rpc_address` in the node’s cassandra.yaml file](https://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configCassandra_yaml_r.html?scroll=reference_ds_qfg_n1r_1k__rpc_address) (or [`broadcast_rpc_address` when defined](https://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configCassandra_yaml_r.html?scroll=reference_ds_qfg_n1r_1k__rpc_address) ). In most cases, this is the correct value, however, sometimes the addresses received in this manner are either not reachable directly by the driver or are not the preferred address to use. A common such scenario is a multi-datacenter deployment with a client connecting using the private IP address to the local datacenter (to reduce network costs) and the public IP address for the remote datacenter nodes. The AddressTranslator interface[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/address-resolution/index.html#the-address-translator-interface) -------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `AddressTranslator` interface allows you to deal with such cases, by transforming the address sent by a Cassandra node to another address to be used by the driver for connection. class MyAddressTranslator extends AddressTranslator { translate(address, port, callback) { // Your custom translation logic } } You then configure the driver to use your AddressTranslator implementation in the client options. const client = new Client({ contactPoints, localDataCenter, policies: { addressResolution: new MyAddressTranslator() } }); Note: The contact points provided while creating the Client are not translated, only addresses retrieved from or sent by Cassandra nodes are. EC2 multi-region[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/address-resolution/index.html#ec2-multi-region) ------------------------------------------------------------------------------------------------------------------------------------- The `EC2MultiRegionTranslator` class is provided out of the box. It helps optimize network costs when your infrastructure (both Cassandra nodes and clients) is distributed across multiple Amazon EC2 regions: * a client communicating with a Cassandra node in the same EC2 region should use the node’s private IP address (which is less expensive); * a client communicating with a node in a different region should use the public IP address. To use this implementation, provide an instance when initializing the `Client` object. const cassandra = require('cassandra-driver'); const { EC2MultiRegionTranslator } = cassandra.policies.addressResolution; const client = new cassandra.Client({ contactPoints, localDataCenter, policies: { addressResolution: new EC2MultiRegionTranslator() } }); The `Client` class performs a reverse DNS lookup of the origin address to find the domain name of the target instance. Then it performs a forward DNS lookup of the domain name; the EC2 DNS does the private to public switch automatically based on location. --- # DataStax Node.js Driver - Features [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/) * Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/index.html#features) ================================================================================================== The DataStax Node.js Driver is feature-rich and highly tunable Node.js client library for Apache Cassandra, DSE and DataStax products. Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/index.html#usage) -------------------------------------------------------------------------------------------- * [Address resolution](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/address-resolution) * [Authentication](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth) * [Batch statements](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/batch) * [Cluster and schema metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/metadata) * [Concurrent execution API](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api) * [Connecting to DataStax Astra](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/cloud) * [Connection pooling](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling) * [CQL data types to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes) * [Execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles) * [Fetching large result sets](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/paging) * [Geospatial types support](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/geotypes) * [Graph support](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support) * [Logging](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/logging) * [Mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper) * [Native protocol](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/native-protocol) * [Parameterized queries](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/parameterized-queries) * [Promise and callback support](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/promise-callback) * [Query timestamps](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps) * [Query warnings](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-warnings) * [Speculative query executions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions) * [TLS/SSL](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tls) * [Tuning policies](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies) * [User-defined functions and aggregates](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/udfs) --- # DataStax Node.js Driver - Cluster and schema metadata [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/metadata/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/metadata/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/metadata/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/metadata/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/metadata/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/metadata/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/metadata/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/metadata/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/metadata/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/metadata/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/metadata/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/metadata/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/metadata/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/metadata/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/metadata/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/metadata/) * Cluster and schema metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/metadata/index.html#cluster-and-schema-metadata) ================================================================================================================================================= You can retrieve the cluster topology and the schema metadata information using the Node.js driver. After establishing the first connection, the driver retrieves the cluster topology details and exposes these through properties of the client object. This information is kept up to date using Cassandra event notifications. The following example outputs hosts information about your cluster: client.hosts.forEach(function (host) { console.log(host.address, host.datacenter, host.rack); }); Additionally, the keyspaces information is already loaded into the `Metadata` object, once the client is connected: console.log(Object.keys(client.metadata.keyspaces)); To retrieve the definition of a table, use the `Metadata#getTable()` method: client.metadata.getTable('ks1', 'table1') .then(function (tableInfo) { console.log('Table %s', table.name); table.columns.forEach(function (column) { console.log('Column %s with type %j', column.name, column.type); }); }); When retrieving the same table definition concurrently, the driver queries once and invokes all callbacks with the retrieved information. Schema agreement[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/metadata/index.html#schema-agreement) --------------------------------------------------------------------------------------------------------------------------- Schema changes need to be propagated to all nodes in the cluster. Once they have settled on a common version, we say that they are in agreement. the driver waits for schema agreement after executing a schema-altering query. This is to ensure that subsequent requests (which might get routed to different nodes) see an up-to-date version of the schema. ![Text Diagram]() The schema agreement wait is performed serially, so the `execute()` call will only return after it has completed. The check is implemented by repeatedly querying system tables for the schema version reported by each node, until they all converge to the same value. If that doesn’t happen within a given timeout, the driver will give up waiting. The default timeout is `10` seconds, it can be customized when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxSchemaAgreementWaitSeconds: 20 } }); After executing a statement, you can check whether schema agreement was successful or timed out: client.execute('CREATE TABLE table1 (id int PRIMARY KEY)') .then(rs => { console.log(`Is schema in agreement? ${rs.info.isSchemaInAgreement}`); }); Additionally, you can perform an on-demand check at any time: client.metadata.checkSchemaAgreement() .then(agreement => { console.log(`Is schema in agreement? ${agreement}`); }); Note that the on-demand check using `checkSchemaAgreement()` does not retry, it only queries system tables once. --- # DataStax Node.js Driver - Native protocol [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/native-protocol/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/native-protocol/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/native-protocol/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/native-protocol/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/native-protocol/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/native-protocol/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/native-protocol/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/native-protocol/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/native-protocol/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/native-protocol/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/native-protocol/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/native-protocol/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/native-protocol/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/native-protocol/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/native-protocol/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/native-protocol/) * Native protocol[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/native-protocol/index.html#native-protocol) ================================================================================================================================ The native protocol defines the format of the binary messages exchanged between the driver and Cassandra over TCP. As a driver user what you need to be aware of is that some Cassandra features are only available with a specific protocol version, but if you are interested in the technical details you can check [the specification in the Cassandra codebase](https://git-wip-us.apache.org/repos/asf?p=cassandra.git;a=tree;f=doc;hb=HEAD) . Controlling the protocol version[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/native-protocol/index.html#controlling-the-protocol-version) ------------------------------------------------------------------------------------------------------------------------------------------------------------------ By default, the driver uses the highest protocol version supported by the driver and the Cassandra cluster. If you want to limit the protocol version to use, you do so in the protocol options. const cassandra = require('cassandra-driver'); const protocolVersion = cassandra.types.protocolVersion; const client = new cassandra.Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.v3 } }); Mixed cluster versions and rolling upgrades[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/native-protocol/index.html#mixed-cluster-versions-and-rolling-upgrades) ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The protocol version used between the client and the Cassandra cluster is negotiated upon establishing the first connection. For clusters with nodes running mixed versions of Cassandra and during rolling upgrades this could represent an issue that could lead to limited availability. To exemplify the above, consider a mixed cluster having nodes running either Cassandra 2.1 or 2.0. * The first contact point is a 2.1 host, so the driver negotiates native protocol version 3 * While connecting to the rest of the cluster, the driver contacts a 2.0 host using native protocol version 3, which fails; an error is logged and this host will be permanently ignored. For these scenarios, mixed version clusters and rolling upgrades, it is strongly recommended to set the maximum protocol version when initializing the client: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.v2 } }); And switching it to the highest protocol version once the upgrade is completed, by leaving the maximum protocol version unspecified or by using `protocolVersion.maxSupported`: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.maxSupported } }); --- # DataStax Node.js Driver - Parameterized queries [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/parameterized-queries/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/parameterized-queries/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/parameterized-queries/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/parameterized-queries/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/parameterized-queries/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/parameterized-queries/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/parameterized-queries/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/parameterized-queries/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/parameterized-queries/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/parameterized-queries/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/parameterized-queries/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/parameterized-queries/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/parameterized-queries/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/parameterized-queries/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/parameterized-queries/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/parameterized-queries/) * Parameterized queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/parameterized-queries/index.html#parameterized-queries) ================================================================================================================================================== You can bind the values of parameters in a prepared statement either by position or by using named markers. Positional parameterized query[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/parameterized-queries/index.html#positional-parameterized-query) -------------------------------------------------------------------------------------------------------------------------------------------------------------------- When using positional parameters, the query parameters must be provided as an Array. const query = 'INSERT INTO artists (id, name) VALUES (?, ?)'; // Parameters by marker position const params = ['krichards', 'Keith Richards']; client.execute(query, params, { prepare: true }); Named parameterized query[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/parameterized-queries/index.html#named-parameterized-query) ---------------------------------------------------------------------------------------------------------------------------------------------------------- You declare the named markers in your queries and use a JavaScript object properties to define the parameters, with the `Object` property names matching the parameters names. const query = 'INSERT INTO artists (id, name) VALUES (:id, :name)'; // Parameters by marker name const params = { id: 'krichards', name: 'Keith Richards' }; client.execute(query, params, { prepare: true }); Defining named markers in your queries is supported in Cassandra 2.0 or greater for prepared statements and Cassandra 2.1 or greater for non-prepared statements. --- # DataStax Node.js Driver - Connection pooling [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/connection-pooling/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/connection-pooling/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/connection-pooling/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/connection-pooling/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/connection-pooling/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/connection-pooling/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/connection-pooling/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/connection-pooling/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/connection-pooling/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/connection-pooling/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/connection-pooling/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/connection-pooling/) * Connection pooling[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling/index.html#connection-pooling) ========================================================================================================================================= The driver maintains one or more connections opened to each Apache Cassandra node selected by the load-balancing policy. The amount of connections per host is defined in the pooling configuration. Default pooling configuration[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling/index.html#default-pooling-configuration) --------------------------------------------------------------------------------------------------------------------------------------------------------------- The default number of connections per host depends on the version of the Apache Cassandra cluster. When using the driver to connect to modern server versions (Apache Cassandra 2.1 and above), the driver uses one connection per host. Setting the number of connections per host[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling/index.html#setting-the-number-of-connections-per-host) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If needed, you can set the number of connections per host depending on the distance, relative to the driver instance, in the `pooling` configuration: const cassandra = require('cassandra-driver'); const distance = cassandra.types.distance; const options = { contactPoints, localDataCenter, pooling: { coreConnectionsPerHost: { [distance.local]: 2, [distance.remote]: 1 } } }; const client = new Client(options); Simultaneous requests per connection[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling/index.html#simultaneous-requests-per-connection) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The driver limits the amount of concurrent requests per connection to `2048` with modern protocol versions and `128` with older versions of the protocol (v1 and v2). You can throttle requests by setting the `maxRequestsPerConnection` value in the `poolingOptions`. When the limit is reached for all connections to a host, the driver will move to the next host according to the query plan. When the query plan is exhausted, the driver will yield a `NoHostAvailableError` containing `BusyConnectionError` instances per each host in the `innerErrors` property. Get status of the connection pool[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling/index.html#get-status-of-the-connection-pool) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can use `getState()` method to get a point-in-time information of the state of the connections pools to each host. const state = client.getState(); for (let host of state.getConnectedHosts()) { console.log('Host %s: open connections = %d; in flight queries = %d', host.address, state.getOpenConnections(host), state.getInFlightQueries(host)); } --- # DataStax Node.js Driver - Execution Profiles [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/execution-profiles/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/execution-profiles/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/execution-profiles/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/execution-profiles/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/execution-profiles/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/execution-profiles/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/execution-profiles/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/execution-profiles/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/execution-profiles/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/execution-profiles/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/execution-profiles/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Execution Profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/index.html#execution-profiles) ========================================================================================================================================= Execution profiles provide a mechanism to group together a set of configuration options and reuse them across different query executions. This feature is specially useful when dealing with different workloads like DSE Graph, Cql OLTP workloads, DSE search, … These options include: * Load balancing policy * Retry policy * Consistency levels * Per-host request timeout * Graph Options * Graph name * Graph traversal source * Graph read consistency * Graph write consistency Using Execution Profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/index.html#using-execution-profiles) ----------------------------------------------------------------------------------------------------------------------------------------------------- ### Initializing cluster with profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/index.html#initializing-cluster-with-profiles) Execution profiles should be created when creating the `Client` instance with a name that identifies it and the settings that apply to the profile. const aggregationProfile = new ExecutionProfile('aggregation', { consistency: consistency.localQuorum, loadBalancing: new DCAwareRoundRobinPolicy('us-west'), retry: myRetryPolicy, readTimeout: 30000, serialConsistency: consistency.localSerial }); const client = new Client({ contactPoints: ['host1'], localDataCenter, profiles: [ aggregationProfile ] }); Note that while the above options are all the supported settings on the execution profiles, you can specify only the ones that are required for the executions, using the `'default'` profile to fill the rest of the options. #### Default execution profile[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/index.html#default-execution-profile) You can define a default profile, using the name `'default'`: const client = new Client({ contactPoints: ['host1'], localDataCenter, profiles: [ \ new ExecutionProfile('default', {\ consistency: consistency.one,\ readTimeout: 10000\ }),\ new ExecutionProfile('graph-oltp', {\ consistency: consistency.localQuorum,\ graphOptions: { name: 'myGraph' }\ })\ ] }); The default profile will be used to fill the unspecified options in the rest of the profiles. In the above example, the read timeout for the profile named `'graph-oltp'` will be the one defined in the default profile (10,000 ms). For the settings that are not specified in the default profile, the driver will use the default `Client` options. ### Using an execution profile by name[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/index.html#using-an-execution-profile-by-name) Use the name to specify which profile you want to use for the execution. client.execute(query, params, { executionProfile: 'aggregation' }); ### Using an execution profile by instance[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/index.html#using-an-execution-profile-by-instance) You can also use the `ExecutionProfile` instance. client.execute(query, params, { executionProfile: aggregationProfile }); ### Using default execution profile[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/index.html#using-default-execution-profile) When the execution profile is not provided in the options, the default execution profile is used. client.execute(query, params, null); --- # DataStax Node.js Driver - Graph support [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/graph-support/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Graph support[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/index.html#graph-support) ========================================================================================================================== `Client` includes the `executeGraph()` method to execute graph queries: const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'dc1', graphOptions: { name: 'demo' } }); // executeGraph() method returns a Promise client.executeGraph('g.V()') .then(function (result) { const vertex = result.first(); console.log(vertex.label); }); Alternatively, you can use the callback-based execution: client.executeGraph('g.V()', function (err, result) { assert.ifError(err); const vertex = result.first(); // ... }); Graph Options[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/index.html#graph-options) -------------------------------------------------------------------------------------------------------------------------- You can set default graph options when initializing `Client` which will be used for all graph statements. For example, to avoid providing a `graphName` option in each `executeGraph()` call: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'dc1', graphOptions: { name: 'demo' } }); These options may be overridden by specifying the [execution profile](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles) when calling `executeGraph()`: // Use a different graph name than the one provided when creating the client instance const result = await client.executeGraph(query, params, { executionProfile: 'graph-oltp' }); const vertex = result.first(); console.log(vertex.label); You can check out more info on [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles) . Handling Results[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/index.html#handling-results) -------------------------------------------------------------------------------------------------------------------------------- Graph queries return a `GraphResultSet`, which is an [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable) of items. The format of the data returned is dependent on the data requested. Retrieving property values: const result = await client.executeGraph('g.V().hasLabel("person").values("name")'); for (const name of result) { console.log(name); } Retrieving vertices: const result = await client.executeGraph('g.V().hasLabel("person")'); for (const vertex of result) { console.log(vertex.label); } Retrieving edges: const result = await client.executeGraph('g.E()'); for (const edge of result) { console.log(edge.label); } ### Parameters[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/index.html#parameters) Graph traversal execution supports named parameters. Parameters must be passed in as an object: const traversal = 'g.addV(vertexLabel).property("name", username)'; await client.executeGraph(traversal, { vertexLabel: 'person', username: 'marko' }); ### Graph types[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/index.html#graph-types) The DataStax Node.js driver supports a wide variety of TinkerPop types and [DSE types](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/) . For graph types that don’t have a native JavaScript representation, the driver provides the [`types` module](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/) . For example: const { types } = require('cassandra-driver'); const { Uuid, InetAddress } = types; const traversal = 'g.addV("sample").property("uid", uid).property("ip_address", address)'; await client.execute(traversal, { uid: Uuid.random(), address: InetAddress.fromString('10.0.0.100') }); The same types are also supported for traversal execution results: const rs = await client.execute('g.V().hasLabel("sample").values("ip_address")'); for (const ip of rs) { console.log(ip instanceof InetAddress); // true } #### User-defined types[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/index.html#user-defined-types) User-defined types (UDTs) are supported in the Node.js driver using JavaScript objects. const rs = await client.execute('g.V().hasLabel("sample").values("user_address")'); for (const address of rs) { console.log(`User address is ${address.street}, ${address.city} ${address.state}`); } In order to use a UDT as a parameter, you must wrap the object instance using `asUdt()` function to provide additional information to properly represent the UDT on the server. const { datastax } = require('cassandra-driver'); const { asUdt } = datastax.graph; // Get the UDT metadata const udtInfo = await client.metadata.getUdt(graphName, 'address'); // Build the UDT const address = asUdt({ street: '123 Priam St.', city: 'My City', state: 'MY' }, udtInfo); const traversal = 'g.addV("sample").property("uid", uid).property("user_address", address)'; // Use the UDT as parameter await client.execute(traversal, { uid: Uuid.random(), address }); --- # DataStax Node.js Driver - Mapper [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/mapper/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/mapper/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/mapper/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/mapper/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/mapper/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Mapper[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/index.html#mapper) ===================================================================================================== The driver provides an object mapper that lets you interact with your data like you would interact with a set of documents. Mapper Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/index.html#mapper-features) ----------------------------------------------------------------------------------------------------------------------- * No / minimal configuration required: no need to specify the schema manually, it uses the driver schema metadata * Support denormalized schemas and materialized views: one model can be mapped to multiple tables * Convention-based mapping * Support bypassing query generation / bring your own queries and map results * Minimal performance impact compared to the core driver Basic Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/index.html#basic-usage) --------------------------------------------------------------------------------------------------------------- Retrieving objects from the database: const videos = await videoMapper.find({ userId }); for (let video of videos) { console.log(video.name); } Updating an object from the database: await videoMapper.update({ id, userId, name, addedDate, description }); Note that execution methods return a `Promise`, to simplify the code examples in the documentation [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) are used. You can continue by reading the [Getting Started Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/getting-started/) or other topics in the Mapper documentation: * [Getting Started Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/getting-started/) * [Queries](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/queries/) * [Defining Mappings](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/defining-mappings/) * [Limitations and FAQ](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/limitations-and-faq/) --- # DataStax Node.js Driver - Concurrent Execution API [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/concurrent-api/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/concurrent-api/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/concurrent-api/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/concurrent-api/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Concurrent Execution API[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/index.html#concurrent-execution-api) ================================================================================================================================================= The DataStax Node.js driver provides a set of [utilities for concurrent query execution](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.concurrent/) , to facilitate executing multiple queries in parallel while controlling the concurrency level. The concurrent execution API can useful when, for example, you want to insert a large group of rows from an `Array` or a `Stream` and evaluate failures, if any, at the end. Usage samples[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/index.html#usage-samples) --------------------------------------------------------------------------------------------------------------------------- ### Using a fixed query and an Array of arrays as parameters[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/index.html#using-a-fixed-query-and-an-array-of-arrays-as-parameters) When an `Array` of arrays is provided, one query per each item in the `Array` will be executed, using each item as parameters. const query = 'INSERT INTO table1 (id, value) VALUES (?, ?)'; const parameters = [[1, 'a'], [2, 'b'], [3, 'c'], ]; // ... const result = await executeConcurrent(client, query, parameters); You can visit the [code examples in the driver repository](https://github.com/datastax/nodejs-driver/tree/master/examples) to check out a working example. ### Using a fixed query and a readable stream[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/index.html#using-a-fixed-query-and-a-readable-stream) When a `Stream` instance is provided the driver will read from the input stream and execute one query per item emitted. The driver will throttle reads of the input stream based on the concurrency level configured and the amount of current in-flight requests. The `Stream` instance should be a readable, in object mode, and emit `Array` instances. Per each item emitted, one query will be executed. const stream = csvStream.pipe(transformLineToArrayStream); const result = await executeConcurrent(client, query, stream); ### Using a different queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/index.html#using-a-different-queries) const queryAndParameters = [\ { query: 'INSERT INTO videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ { query: 'INSERT INTO user_videos (user_id, id, name) VALUES (?, ?, ?)',\ params: [ userId, id, name ] },\ { query: 'INSERT INTO latest_videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ ]; const result = await executeConcurrent(client, queryAndParameters); ### Execute all queries and deal with execution errors at the end[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/index.html#execute-all-queries-and-deal-with-execution-errors-at-the-end) When setting `raiseOnFirstError` to `false`, the driver will continue to execute the queries even when one or more errors are encountered. The returned `Promise` will be resolved and you can inspect the property `errors` to obtain each individual error information. const result = await executeConcurrent(client, query, parameters, { raiseOnFirstError: false }); for (let err of result.errors) { // ... } ### Defining concurrency level[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/index.html#defining-concurrency-level) Use the `concurrencyLevel` option property to set the maximum amount of requests that can be executed simultaneously. It defaults to `100`. const result = await executeConcurrent(client, query, parameters, { concurrencyLevel: 200 }); Note that increasing the amount of simultaneous requests will result in further queueing at the driver level and the server nodes level. You should find the optimal to get high throughput and low latency, based on your cluster size and hardware specifications. Using a higher concurrency level setting than optimal might result in query timeouts. ### Collecting all the ResultSet instances of each individual execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/index.html#collecting-all-the-result-set-instances-of-each-individual-execution) In the case you want the driver to collect each individual `ResultSet` instance, you can use the `collectResults` flag. const result = await executeConcurrent(client, query, parameters, { collectResults: true }); for (let rs of result.resultItems) { // ... } --- # DataStax Node.js Driver - Query timestamps [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/query-timestamps/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/query-timestamps/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/query-timestamps/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/query-timestamps/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/query-timestamps/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/query-timestamps/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/query-timestamps/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/query-timestamps/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/query-timestamps/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/query-timestamps/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Query timestamps[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/index.html#query-timestamps) =================================================================================================================================== In Cassandra, each mutation has a microsecond-precision timestamp, which is used to order operations relative to each other. The timestamp can be provided by the client or assigned server-side based on the time the server processes the request. Letting the server assign the timestamp can be a problem when the order of the writes matter: with unlucky timing (different coordinators, network latency, etc.), two successive requests from the same client might be processed in a different order server-side, and end up with out-of-order timestamps. Client-side generation[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/index.html#client-side-generation) ----------------------------------------------------------------------------------------------------------------------------------------------- ### Using a timestamp generator[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/index.html#using-a-timestamp-generator) The operation timestamp can be sent as part of the request. The driver uses [`MonotonicTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) by default to generate the request timestamps. You can provide a different generator when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, policies: { timestampGeneration: new MyCustomTimestampGenerator() } }); To implement a custom timestamp generator, you must implement `TimestampGenerator` base class. In addition, you can also set the default timestamp on a per-execution basis in the query options: session.execute(query, params, { timestamp: timestamp }); #### Accuracy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/index.html#accuracy) As defined by ECMAScript, the `Date` object has millisecond resolution. The [`MononoticTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) uses a incremental counter to generate the sub-millisecond part of the timestamp until the next clock tick. #### Monotonicity[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/index.html#monotonicity) The [`MononoticTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) implementation also guarantees that the returned timestamps will always be monotonically increasing, even if multiple updates happen under the same millisecond. Note that to guarantee such monotonicity, if more than one thousand timestamps are generated within the same millisecond, or in the event of a system clock skew, the implementation might return timestamps that drift out into the future. When this happens, the built-in generator logs a periodic warning message. See their non-default constructors for ways to control the warning interval. ### Provide the timestamp in the query[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/index.html#provide-the-timestamp-in-the-query) Alternatively, if you are using an old server version, you can explicitly provide the timestamp in your CQL query (not recommended): client.execute('INSERT INTO my_table(c1, c2) VALUES (1, 1) USING TIMESTAMP 1482156745633040'); --- # DataStax Node.js Driver - Promise and callback-based API [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/promise-callback/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/promise-callback/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/promise-callback/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/promise-callback/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/promise-callback/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/promise-callback/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/promise-callback/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/promise-callback/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/promise-callback/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/promise-callback/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/promise-callback/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/promise-callback/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/promise-callback/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/promise-callback/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Promise and callback-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/promise-callback/index.html#promise-and-callback-based-api) =============================================================================================================================================================== The driver supports both [promises](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) and callbacks for the asynchronous methods exposed in the `Client` and `Metadata` prototypes, you can choose the approach that suits your needs. Promise-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/promise-callback/index.html#promise-based-api) ------------------------------------------------------------------------------------------------------------------------------------- client.execute('SELECT name, email FROM users') .then(result => console.log('User with email %s', result.rows[0].email)); When a `callback` is not provided as the last argument, the driver will return a `Promise`, without the need to promisify the driver module. Returned promises are instances of [`Promise` global object](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) and are created using the default constructor: `new Promise(executor)`. In case you want the driver to use a third party `Promise` module (ie: [bluebird](http://bluebirdjs.com/) ) to create the `Promise` instances, you can optionally provide your own factory method when creating the `Client` instance, for example: const BbPromise = require('bluebird'); const client = new Client({ contactPoints, localDataCenter, promiseFactory: BbPromise.fromCallback }); Callback-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/promise-callback/index.html#callback-based-api) --------------------------------------------------------------------------------------------------------------------------------------- All asynchronous methods of the driver supports an optional `callback` as the last argument. client.execute('SELECT name, email FROM users', function(err, result) { assert.ifError(err); console.log('User with email %s', result.rows[0].email); }); --- # DataStax Node.js Driver - Fetching large result sets [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/paging/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/paging/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/paging/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/paging/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/paging/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/paging/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/paging/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/paging/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/paging/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/paging/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/paging/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/paging/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/paging/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/paging/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/paging/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/paging/) * Fetching large result sets[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/paging/index.html#fetching-large-result-sets) ============================================================================================================================================= When dealing with a large number of rows, the driver breaks the result into pages, only requesting a limited number of rows each time (`5000` being the default `fetchSize`). To retrieve the rows beyond this default size, use one of the following paging mechanisms. Automatic paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/paging/index.html#automatic-paging) ------------------------------------------------------------------------------------------------------------------------- The driver supports asynchronous iteration of the `ResultSet` using the built-in [Async Iterator](https://github.com/tc39/proposal-async-iteration) , fetching the following result pages after the previous one has been yielded. Large result sets can be iterated using the [`for await ... of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) statement: const result = await client.execute(query, params, { prepare: true }); for await (const row of result) { console.log(row[columnName]); } Under the hood, the driver will get all the rows of the query result using multiple requests. Initially, when calling `execute()` it will retrieve the first page of results according to the fetch size (defaults to `5000`). If there are additional rows, those will be retrieved once the async iterator yielded the rows from the previous page. If needed, you can use `isPaged()` method of `ResultSet` instance to determine whether there are more pages of results than initially fetched. Note that using the async iterator will not affect the internal state of the `ResultSet` instance. You should avoid using both `rows` property that contains the row instances of the first page of results, and the async iterator, that will yield all the rows in the result regardless on the number of pages. Manual paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/paging/index.html#manual-paging) ------------------------------------------------------------------------------------------------------------------- Sometimes it is convenient to save the paging state in order to restore it later. For example, consider a stateless web service that displays a list of results with a link to the next page. When the user clicks that link, we want to run the exact same query, except that the iteration should start where we stopped on the previous page. To do so, the driver exposes a `pagingState` object that represents where we were in the result set when the last page was fetched: const options = { prepare: true , fetchSize: 1000 }; const result = await client.execute(query, parameters, options); // Property 'rows' will contain only the amount of items of the first page (max 1000 in this case) const rows = result.rows; // Store the page state let pageState = result.pageState; In the next request, use the `pageState` to fetch the following rows. // Use the pageState in the queryOptions to continue where you left it. const options = { pageState, prepare: true, fetchSize: 1000 }; const result = await client.execute(query, parameters, options); // Following rows up to fetch size (1000) const rows = result.rows; // Store the next paging state. pageState = result.pageState; Saving the paging state works well when you only let the user move from one page to the next. But it doesn’t allow arbitrary jumps (like “go directly to page 10”), because you can’t fetch a page unless you have the paging state of the previous one. Such a feature would require offset queries, which are not natively supported by Apache Cassandra. **Note**: The page state token can be manipulated to retrieve other results within the same column family, so it is not safe to expose it to the users in plain text. Row streams[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/paging/index.html#row-streams) --------------------------------------------------------------------------------------------------------------- If you want to handle a large result set as a [`Stream`](https://nodejs.org/api/stream.html) of rows, you can use `stream()` method of the `Client` instance. The `stream()` method automatically fetches the following pages, yielding the rows as they come through the network and retrieving the following page only after the previous rows were read (throttling). client.stream(query, parameters, options) .on('readable', function () { // readable is emitted as soon a row is received and parsed let row; while (row = this.read()) { // process row } }) .on('end', function () { // emitted when all rows have been retrieved and read }); --- # DataStax Node.js Driver - Connecting to your DataStax Astra database using a secure connection bundle [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/cloud/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/cloud/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/cloud/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/cloud/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/cloud/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/cloud/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Connecting to your DataStax Astra database using a secure connection bundle[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/cloud/index.html#connecting-to-your-data-stax-astra-database-using-a-secure-connection-bundle) =============================================================================================================================================================================================================================================== Quickstart[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/cloud/index.html#quickstart) ------------------------------------------------------------------------------------------------------------ Use the `ClientOptions` property `cloud` to connect to your [DataStax Astra database](https://www.datastax.com/products/datastax-astra) using your secure connection bundle (`secure-connect-DATABASE_NAME.zip`) and `credentials` property to provide your [CQL credentials](https://cassandra.apache.org/doc/latest/cql/security.html#cql-roles) . Here is an example of the minimum configuration needed to connect to your DataStax Astra database using the secure connection bundle: const client = new Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); Configurable settings when using a secure connection bundle[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/cloud/index.html#configurable-settings-when-using-a-secure-connection-bundle) -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can configure your `Client` instance using other `ClientOptions` properties, for example: const client = new Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' }, keyspace: 'my_ks' }); Note that `contactPoints` and `sslOptions` should not be set when using `secureConnectBundle`. --- # DataStax Node.js Driver - User-defined functions and aggregates [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/udfs/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/udfs/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/udfs/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/udfs/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/udfs/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/udfs/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/udfs/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/udfs/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/udfs/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/udfs/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/udfs/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/udfs/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/udfs/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/udfs/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/udfs/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/udfs/) * User-defined functions and aggregates[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/udfs/index.html#user-defined-functions-and-aggregates) ================================================================================================================================================================= Cassandra 2.2 introduced [user-defined functions](https://issues.apache.org/jira/browse/CASSANDRA-7395) (UDF) and aggregates support. You access UDF and aggregate values in your queries like regular columns: const query = 'SELECT avg(salary) as salary FROM employees'; client.execute(query) .then(function (result) { const row = result.first(); console.log('Average salary %d', row.salary); }); The driver also exposes [UDFs and aggregates metadata information](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/) , for example let’s see how to retrieve the metadata information of a UDF named iif, that takes a boolean and int parameter. client.metadata.getFunction('ks1', 'iif', ['boolean', 'int']) .then(function (err, udf) { console.log('Function metadata %j', udf); }); --- # DataStax Node.js Driver - Logging [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/logging/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/logging/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/logging/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/logging/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/logging/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/logging/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/logging/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/logging/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/logging/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Logging[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/logging/index.html#logging) ======================================================================================================== The DataStax Node.js driver uses [events](https://nodejs.org/api/events.html) to expose logging information decoupled from any specific logging framework. The driver’s `Client` inherits from [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) and it triggers `'log'` events. client.on('log', (level, loggerName, message, furtherInfo) => { console.log(`${level} - ${loggerName}: ${message}`); }); The level being passed to the listener can be `'verbose'`, `'info'`, `'warning'` or `'error'`. `verbose` level is only suitable for debugging and it’s usually too noisy. We recommend that you gather logging events from `info` and above on production environments. Tracking query latency and size[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/logging/index.html#tracking-query-latency-and-size) -------------------------------------------------------------------------------------------------------------------------------------------------------- The `RequestLogger` logs queries executed by the driver and it allows tracking requests considered slow and/or large. A request is considered “slow” when it takes longer to complete than a configured threshold in milliseconds. A request is considered to be large when the request size is greater than a configured threshold in bytes. To turn on this feature, you first need to create an instance of `RequestLogger` and use it when creating the `Client` instance: const cassandra = require('cassandra-driver'); const requestTracker = new cassandra.tracker.RequestLogger({ slowThreshold: 1000 }); const client = new Client({ contactPoints, localDataCenter, requestTracker }); You can subscribe to `'slow'`, `'large'`, `'normal'` and `'failure'` events using the emitter object instance: requestTracker.emitter.on('slow', message => console.log(message)); An example message would be: [10.1.1.1:9042] Slow request, took 305 ms (request size 35 bytes / response size 1 KB): SELECT col1, col2 FROM table1 WHERE id = ? [1] Note that events will be emitted only when certain options are defined: * `'slow'` events will only be emitted if `slowThreshold` is set. * `'large'` events will only be emitted if `requestSizeThreshold` is set. * `'normal'` events will only be emitted if `logNormalRequests` is set to `true`. This setting can be changed at runtime using the `RequestLogger` property of the same name. * `'failure'` events will only be emitted if `logErroredRequests` is set to `true`. This setting can be changed at runtime using the property of the same name. You can provide your own tracker implementing `RequestTracker` interface. --- # DataStax Node.js Driver - Geospatial types [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/geotypes/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/geotypes/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/geotypes/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/geotypes/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/geotypes/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Geospatial types[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/geotypes/index.html#geospatial-types) --------------------------------------------------------------------------------------------------------------------------- [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) comes with a set of additional CQL types to represent geospatial data: * `PointType` * `LineStringType` * `PolygonType`. cqlsh> CREATE TABLE points_of_interest(name text PRIMARY KEY, coords 'PointType'); cqlsh> INSERT INTO points_of_interest (name, coords) VALUES ('Eiffel Tower', 'POINT(48.8582 2.2945)'); The driver includes encoders and representations of these types in the `geometry` module that can be used directly as parameters in queries. All Javascript geospatial types implement `toString()`, that returns the string representation in [Well-known text](https://en.wikipedia.org/wiki/Well-known_text) format, and `toJSON()`, that returns the JSON representation in [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) format. Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/geotypes/index.html#usage) ----------------------------------------------------------------------------------------------------- const cassandra = require('cassandra-driver'); const Point = cassandra.geometry.Point; const insertQuery = 'INSERT INTO points_of_interest (name, coords) VALUES (?, ?)'; const selectQuery = 'SELECT coords FROM points_of_interest WHERE name = ?'; await client.execute(insertQuery, [ 'Eiffel Tower', new Point(48.8582, 2.2945) ]); const result = await client.execute(selectQuery, [ 'Eiffel Tower' ]); const row = result.first(); const point = row['coords']; console.log(point instanceof Point); // true console.log('x: %d, y: %d', point.x, point.y); // x: 48.8582, y: 2.2945 console.log(point.toString()); // 'POINT (48.8582 2.2945)' --- # DataStax Node.js Driver - TLS/SSL [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tls/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tls/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tls/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tls/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/tls/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/tls/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/tls/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/tls/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/tls/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * TLS/SSL[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tls/index.html#tls-ssl) ==================================================================================================== You can secure traffic between the driver and Apache Cassandra with TLS/SSL. There are two aspects to that: * Client-to-node encryption, where the traffic is encrypted and the client verifies the identity of the Apache Cassandra nodes it connects to. * Optional client certificate authentication, where Apache Cassandra nodes also verify the identity of the client. This section describes the driver-side configuration, it assumes that you’ve already configured SSL encryption in Apache Cassandra, you can checkout the [server documentation that covers the basic procedures](https://docs.datastax.com/en/cassandra/3.0/cassandra/configuration/secureSSLClientToNode.html) . Driver configuration[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tls/index.html#driver-configuration) ------------------------------------------------------------------------------------------------------------------------------ Use `sslOptions` property in the [`ClientOptions`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) to enable client TLS/SSL encryption: const client = new Client({ contactPoints, localDataCenter, sslOptions: { rejectUnauthorized: true }}); await client.connect(); You can define the same object properties as the options in the [standard Node.js `tls.connect()` method](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) . The main difference is that server certificate validation against the list of supplied CAs is disabled by default. You should specify `rejectUnauthorized: true` in your settings to enable it. ### Enabling client certificate authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tls/index.html#enabling-client-certificate-authentication) Much like in [Node.js standard tls module](https://nodejs.org/api/tls.html) , you can use `cert` and `key` properties to provide the certificate chain and private key. Additionally, you can override the trusted CA certificates using `ca` property: const sslOptions = { // Necessary only if the server requires client certificate authentication. key: fs.readFileSync('client-key.pem'), cert: fs.readFileSync('client-cert.pem'), // Necessary only if the server uses a self-signed certificate. ca: [ fs.readFileSync('server-cert.pem') ], rejectUnauthorized: true }; const client = new Client({ contactPoints, localDataCenter, sslOptions }); --- # DataStax Node.js Driver - Query warnings [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-warnings/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-warnings/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-warnings/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-warnings/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/query-warnings/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/query-warnings/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/query-warnings/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/query-warnings/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/query-warnings/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/query-warnings/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/query-warnings/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/query-warnings/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/query-warnings/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/query-warnings/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/query-warnings/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/query-warnings/) * Query warnings[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-warnings/index.html#query-warnings) ============================================================================================================================= When a query is considered to be harmful for the overall cluster, Cassandra issues a warning that is written to the Cassandra logs. From Cassandra 2.2, [these warnings are also returned to the client drivers](https://issues.apache.org/jira/browse/CASSANDRA-8930) . In the driver, these warnings are [returned in the ResultSet property information](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.ResultSet/) . The warning is still written to the [driver logs](https://docs.datastax.com/en/developer/nodejs-driver/4.8/#logging) . --- # DataStax Node.js Driver - auth [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.auth/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.auth/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.auth/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.auth/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.auth/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.auth/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.auth/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.auth/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.auth/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.auth/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.auth/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.auth/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.auth/) * module auth[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/index.html#module-auth) =============================================================================================================== DSE Authentication module. Contains the classes used for connecting to a DSE cluster secured with DseAuthenticator. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/index.html#classes) ------------------------------------------------------------------------------------------------------- * `[DseGssapiAuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/class.DseGssapiAuthProvider/) ` * `[DsePlainTextAuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/class.DsePlainTextAuthProvider/) ` * `[PlainTextAuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/class.PlainTextAuthProvider/) ` * `[AuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/class.AuthProvider/) ` * `[Authenticator](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/class.Authenticator/) ` --- # DataStax Node.js Driver - types [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.types/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.types/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.types/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.types/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.types/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.types/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.types/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.types/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.types/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.types/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.types/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.types/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.types/) * module types[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#module-types) ================================================================================================================== Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#classes) -------------------------------------------------------------------------------------------------------- * `[BigDecimal](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.BigDecimal/) ` * `[Duration](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.Duration/) ` * `[Long](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.Long/) ` * `[InetAddress](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.InetAddress/) ` * `[Integer](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.Integer/) ` * `[LocalDate](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.LocalDate/) ` * `[LocalTime](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.LocalTime/) ` * `[ResultSet](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.ResultSet/) ` * `[ResultStream](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.ResultStream/) ` * `[Row](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.Row/) ` * `[TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.TimeUuid/) ` * `[Tuple](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.Tuple/) ` * `[Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.Uuid/) ` * `[Vector](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.Vector/) ` Constants[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#constants) ------------------------------------------------------------------------------------------------------------ ### consistencies[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#consistencies) Consistency levels Properties: | Name | Type | Description | | --- | --- | --- | | any | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Writing: A write must be written to at least one node. If all replica nodes for the given row key are down, the write can still succeed after a hinted handoff has been written. If all replica nodes are down at write time, an ANY write is not readable until the replica nodes for that row have recovered. | | one | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns a response from the closest replica, as determined by the snitch. | | two | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the most recent data from two of the closest replicas. | | three | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the most recent data from three of the closest replicas. | | quorum | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record with the most recent timestamp after a quorum of replicas has responded regardless of data center. Writing: A write must be written to the commit log and memory table on a quorum of replica nodes. | | all | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record with the most recent timestamp after all replicas have responded. The read operation will fail if a replica does not respond. Writing: A write must be written to the commit log and memory table on all replica nodes in the cluster for that row. | | localQuorum | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record with the most recent timestamp once a quorum of replicas in the current data center as the coordinator node has reported. Writing: A write must be written to the commit log and memory table on a quorum of replica nodes in the same data center as the coordinator node. Avoids latency of inter-data center communication. | | eachQuorum | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record once a quorum of replicas in each data center of the cluster has responded. Writing: Strong consistency. A write must be written to the commit log and memtable on a quorum of replica nodes in all data centers. | | serial | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Achieves linearizable consistency for lightweight transactions by preventing unconditional updates. | | localSerial | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Same as serial but confined to the data center. A write must be written conditionally to the commit log and memtable on a quorum of replica nodes in the same data center. | | localOne | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Similar to One but only within the DC the coordinator is in. | ### consistencyToString[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#consistency-tostring) Mapping of consistency level codes to their string representation. ### dataTypes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#data-types) CQL data types Properties: | Name | Type | Description | | --- | --- | --- | | custom | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A custom type. | | ascii | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | ASCII character string. | | bigint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 64-bit signed long. | | blob | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Arbitrary bytes (no validation). | | boolean | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | true or false. | | counter | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Counter column (64-bit signed value). | | decimal | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Variable-precision decimal. | | double | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 64-bit IEEE-754 floating point. | | float | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 32-bit IEEE-754 floating point. | | int | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 32-bit signed integer. | | text | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | UTF8 encoded string. | | timestamp | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A timestamp. | | uuid | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Type 1 or type 4 UUID. | | varchar | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | UTF8 encoded string. | | varint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Arbitrary-precision integer. | | timeuuid | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Type 1 UUID. | | inet | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | An IP address. It can be either 4 bytes long (IPv4) or 16 bytes long (IPv6). | | date | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A date without a time-zone in the ISO-8601 calendar system. | | time | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A value representing the time portion of the day. | | smallint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 16-bit two’s complement integer. | | tinyint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 8-bit two’s complement integer. | | list | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A collection of elements. | | map | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Key/value pairs. | | set | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A collection that contains no duplicate elements. | | udt | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | User-defined type. | | tuple | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A sequence of values. | ### distance[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#distance) Represents the distance of Cassandra node as assigned by a LoadBalancingPolicy relatively to the driver instance. Properties: | Name | Type | Description | | --- | --- | --- | | local | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A local node. | | remote | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A remote node. | | ignored | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A node that is meant to be ignored. | ### protocolVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#protocol-version) Contains information for the different protocol versions supported by the driver. Properties: | Name | Type | Description | | --- | --- | --- | | v1 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v1, supported in Apache Cassandra 1.2–>2.2. | | v2 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v2, supported in Apache Cassandra 2.0–>2.2. | | v3 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v3, supported in Apache Cassandra 2.1–>3.x. | | v4 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v4, supported in Apache Cassandra 2.2–>3.x. | | v5 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v5, in beta from Apache Cassandra 3.x+. Currently not supported by the driver. | | dseV1 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | DataStax Enterprise protocol v1, DSE 5.1+ | | dseV2 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | DataStax Enterprise protocol v2, DSE 6.0+ | | maxSupported | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the higher protocol version that is supported by this driver. | | minSupported | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the lower protocol version that is supported by this driver. | | isSupported | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | A function that returns a boolean determining whether a given protocol version is supported. | ### responseErrorCodes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#response-error-codes) Server error codes returned by Cassandra Properties: | Name | Type | Description | | --- | --- | --- | | serverError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Something unexpected happened. | | protocolError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Some client message triggered a protocol violation. | | badCredentials | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Authentication was required and failed. | | unavailableException | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Raised when coordinator knows there is not enough replicas alive to perform a query with the requested consistency level. | | overloaded | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The request cannot be processed because the coordinator is overloaded. | | isBootstrapping | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The request was a read request but the coordinator node is bootstrapping. | | truncateError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Error encountered during a truncate request. | | writeTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Timeout encountered on write query on coordinator waiting for response(s) from replicas. | | readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Timeout encountered on read query on coordinator waitign for response(s) from replicas. | | readFailure | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A non-timeout error encountered during a read request. | | functionFailure | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A (user defined) function encountered during execution. | | writeFailure | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A non-timeout error encountered during a write request. | | syntaxError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The submitted query has a syntax error. | | unauthorized | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The logged user doesn’t have the right to perform the query. | | invalid | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The query is syntactically correct but invalid. | | configError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The query is invalid because of some configuration issue. | | alreadyExists | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The query attempted to create a schema element (i.e. keyspace, table) that already exists. | | unprepared | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Can be thrown while a prepared statement tries to be executed if the provided statement is not known by the coordinator. | ### unset[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#unset) Unset representation. Use this field if you want to set a parameter to `unset`. Valid for Cassandra 2.2 and above. Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#functions) ------------------------------------------------------------------------------------------------------------ ### generateTimestamp[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#generate-timestamp) (\[`[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) ` date\], \[`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` microseconds\]) Generates a value representing the timestamp for the query in microseconds based on the date and the microseconds provided Parameters: | Name | Type | Description | | --- | --- | --- | | date optional | `[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) ` | The date to generate the value, if not provided it will use the current date. | | microseconds optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A number from 0 to 999 used to build the microseconds part of the date. | Returns: | Type | Description | | --- | --- | | `Long` | | ### timeuuid[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#timeuuid) (\[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` options\], \[`Buffer` buffer\], \[`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` offset\]) **Backward compatibility only, use `[TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.TimeUuid/) ` instead**. Generates and returns a RFC4122 v1 (timestamp based) UUID in a string representation. Parameters: | Name | Type | Description | | --- | --- | --- | | options optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | buffer optional | `Buffer` | | | offset optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### uuid[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/index.html#uuid) () **Backward compatibility only, use `[Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.Uuid/) ` class instead**. Generate and return a RFC4122 v4 UUID in a string representation. --- # DataStax Node.js Driver - Speculative query execution [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/speculative-executions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/speculative-executions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/speculative-executions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/speculative-executions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/speculative-executions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/speculative-executions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/speculative-executions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/speculative-executions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/speculative-executions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Speculative query execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/index.html#speculative-query-execution) =============================================================================================================================================================== Sometimes a server node might be experiencing difficulties (for example, long GC pause) and take longer than usual to reply. Queries sent to that node experience higher latencies than expected. One thing we can do to improve that is preemptively start a second execution of the query against another node, before the first node has replied or errored out. If that second node replies faster, we can send the response back to the client (we also cancel the first query): ![Text Diagram]() Or the first node could reply just after the second execution was started. In this case, we cancel the second execution. In other words, whichever node replies faster wins and completes the client query: ![Text Diagram]() Note that “cancelling” in this context simply means marking the operation to discard the response when it later arrives. Speculative executions are disabled by default. The following sections cover the practical details and how to enable them. Query idempotence[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/index.html#query-idempotence) ------------------------------------------------------------------------------------------------------------------------------------------- One important aspect to consider is whether queries are idempotent, (that is, whether they can be applied multiple times without changing the result beyond the initial application). If a query is not idempotent, the driver never schedules speculative executions for it, because there is no way to guarantee that only one node will apply the mutation. Examples of queries that are not idempotent are: * counter operations * prepending or appending to a list column * using non-idempotent CQL functions, like `now()` or `uuid()` In the driver, this is determined by [`isIdempotent` flag in the `QueryOptions`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) . Because the driver does not parse query strings, in most cases it has no information about what the query actually does. Therefore, for all other types of statements, it defaults to `false`. You must set it manually with one of the mechanisms described below. You can override the value for each execution: const query = 'SELECT * FROM users WHERE key = ?'; client.execute(query, [ 'usr1' ], { prepare: true, isIdempotent: true }); Additionally, if you know for a fact that your application does not use any of the non-idempotent CQL queries listed above, you can change the default cluster-wide: // Make all statements idempotent by default: const client = new Client({ contactPoints, localDataCenter, queryOptions: { isIdempotent: true } }); Enabling speculative execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/index.html#enabling-speculative-execution) --------------------------------------------------------------------------------------------------------------------------------------------------------------------- Speculative executions are controlled by an instance of `SpeculativeExecutionPolicy` provided when initializing the `Client`. This policy defines the threshold after which a new speculative execution is triggered. The driver provides a `ConstantSpeculativeExecutionPolicy` that schedules a given number of speculative executions, separated by a fixed delay, the policy is exported under the `.policies.speculativeExecution` module. This simple policy uses a constant threshold: const { Client, policies } = require('cassandra-driver'); const ConstantSpeculativeExecutionPolicy = policies.speculativeExecution.ConstantSpeculativeExecutionPolicy; const client = new Client({ contactPoints, policies: { speculativeExecution: new ConstantSpeculativeExecutionPolicy( 200, // delay before a new execution is launched 2) // maximum amount of additional executions } }); Given the configuration above, an idempotent query would be handled this way: * start the initial execution at t0 * if no response has been received at t0 + 200 milliseconds, start a speculative execution on another node * if no response has been received at t0 + 400 milliseconds, start another speculative execution on a third node As with the rest of policies in the driver, you can provide your own implementation by extending the `SpeculativeExecutionPolicy` prototype. How speculative executions affect retries[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/index.html#how-speculative-executions-affect-retries) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Regardless of speculative executions, the driver has a retry mechanism: * on an internal error, it will try the next host * if the consistency level cannot be reached (for example, unavailable error or read or write timeout), it delegates the decision to the `RetryPolicy`, which might trigger a retry on the same host Turning speculative executions on does not change this behavior. Each parallel execution trigger retries independently: ![Text Diagram]() The only impact is that all executions of the same query always share the same query plan, so each host is used by at most one execution. Tuning and practical details[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/index.html#tuning-and-practical-details) ----------------------------------------------------------------------------------------------------------------------------------------------------------------- The goal of speculative executions is to improve overall latency (the time between `execute(query)` and `complete` in the diagrams above) at high percentiles. On the flipside, they cause the driver to send more individual requests, so throughput does not necessarily improve. One side-effect of speculative executions is that many requests are cancelled, which can lead to a phenomenon called stream id exhaustion: each TCP connection can handle multiple simultaneous requests, identified by a unique number called stream id. When a request gets cancelled, we can’t reuse its stream id immediately because we might still receive a response from the server later. If this happens often, the number of available stream ids diminishes over time, and when it goes below a given threshold we close the connection and create a new one. If requests are often cancelled, so will see connections being recycled at a high rate. This problem is more likely to happen with old server versions (Apache Cassandra version 2.0 or below and DSE 4.6 or below) which only support version 1 and 2 of the native protocol where each TCP connection only has 128 available stream ids. With modern server versions, there are 32K stream ids per connection, so higher cancellation rates can be sustained. Another issue that might arise is that you get unintuitive results because of request ordering. Suppose you run the following query with speculative executions enabled: insert into my_table (k, v) values (1, 1); The first execution is a bit too slow, so a second execution gets triggered. Finally, the first execution completes, so the client code gets back an acknowledgement, and the second execution is cancelled. However, cancelling only means that the driver stops waiting for the server’s response, the request could still be on the wire; let us assume that this is the case. Now you run the following query, which completes successfully: delete from my_table where k = 1; But now the second execution of the first query finally reaches its target node, which applies the mutation. The row that you’ve just deleted is back! **Using [query timestamps](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps) **, which are enabled by default, prevents this issue to appear as each request will have a client-level timestamp which will define the order to apply the mutations. --- # DataStax Node.js Driver - Tuning policies [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/tuning-policies/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/tuning-policies/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/tuning-policies/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/tuning-policies/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/tuning-policies/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/tuning-policies/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/tuning-policies/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/tuning-policies/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/tuning-policies/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/tuning-policies/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/tuning-policies/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/tuning-policies/) * Tuning policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/index.html#tuning-policies) ================================================================================================================================ Load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/index.html#load-balancing-policy) -------------------------------------------------------------------------------------------------------------------------------------------- The load balancing policy interface consists of three methods: * `#distance(Host host)`: determines the distance to the specified host. The values are `distance.ignored`, `distance.local`, and `distance.remote`. * `#init(client, hosts, callback)`: initializes the policy. The driver calls this method only once and before any other method calls are made. * `#newQueryPlan(keyspace, queryOptions, callback)`: executes a callback with the iterator of hosts to use for a query. Each new query calls this method. The policies are responsible for yielding a group of nodes in an specific order for the driver to use (if the first node fails, it uses the next one). There are four load-balancing policies implemented in the driver: * `DCAwareRoundRobinPolicy`: a datacenter-aware, round-robin, load-balancing policy. This policy provides round-robin queries over the node of the local datacenter. It also includes in the query plans returned a configurable number of hosts in the remote data centers, but those are always tried after the local nodes. * `RoundRobinPolicy`: a policy that yields nodes in a round-robin fashion. * `TokenAwarePolicy`: a policy that yields replica nodes for a given partition key and keyspace. The token-aware policy uses a child policy to retrieve the next nodes in case the replicas for a partition key are not available. * `AllowListPolicy`: a policy that wraps the provided child policy but only “allow” hosts from the provided list. Keep in mind however that this policy defeats somewhat the host auto-detection of the driver. As such, this policy is only useful in a few special cases or for testing, but is not optimal in general. ### Default load-balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/index.html#default-load-balancing-policy) The default load-balancing policy is `DefaultLoadBalancingPolicy`. The policy yields local replicas for a given key and, if not available, it yields nodes of the local datacenter in a round-robin manner. Reconnection policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/index.html#reconnection-policy) ---------------------------------------------------------------------------------------------------------------------------------------- The reconnection policy consists of one method: * `#newSchedule()`: creates a new schedule to use in reconnection attempts. By default, the driver uses an exponential reconnection policy. The driver includes these two policy classes: * `ConstantReconnectionPolicy` * `ExponentialReconnectionPolicy` Retry policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/index.html#retry-policy) -------------------------------------------------------------------------------------------------------------------------- A client may send requests to any node in a cluster whether or not it is a replica of the data being queried. This node is placed into the coordinator role temporarily. Which node is the coordinator is determined by the load balancing policy for the cluster. The coordinator is responsible for routing the request to the appropriate replicas. If a coordinator fails during a request, the driver connects to a different node and retries the request. If the coordinator knows before a request that a replica is down, it can throw an `UnavailableException`, but if the replica fails after the request is made, it throws a `TimeoutException`. Of course, this all depends on the consistency level set for the query before executing it. A retry policy centralizes the handling of query retries, minimizing the need for catching and handling of exceptions in your business code. The retry policy interface consists of four methods: * `#onReadTimeout(info, consistency, received, blockFor, isDataPresent)`: determines what to do when the driver gets a `ReadTimeoutException` response from a Cassandra node. * `#onUnavailable(info, consistency, required, alive)`: determines what to do when the driver gets an `UnavailableException` response from a Cassandra node. * `#onWriteTimeout(info, consistency, received, blockFor, writeType)`: determines what to do when the driver gets a `WriteTimeoutException` response from a Cassandra node * `#onRequestError(info, consistency, err)`: defines whether to retry and at which consistency level on an unexpected error, invoked in the following situations: * On a client timeout, while waiting for the server response , being the error an instance of `OperationTimedOutError`. * On a connection error (socket closed, etc.). * When the contacted host replies with an error, such as `overloaded`, `isBootstrapping`, `serverError`, etc. In this case, the error is instance of `ResponseError` The [operation info](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.retry/type.OperationInfo/) , passed as a parameter to the retry policy methods, exposes the `query` and query `options` as properties. A default and base retry policy are included. ### Query idempotence[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/index.html#query-idempotence) Note that as of version 2.0, the configured `RetryPolicy` is not engaged when a query errors with a `WriteTimeoutException` or request error and the query was not [idempotent](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/#query-idempotence) . --- # DataStax Node.js Driver - policies [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.policies/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.policies/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.policies/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.policies/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.policies/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.policies/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.policies/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.policies/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.policies/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.policies/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.policies/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.policies/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.policies/) * module policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/index.html#module-policies) =========================================================================================================================== Contains driver tuning policies to determine `[load balancing](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.loadBalancing/) `, `[retrying](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.retry/) ` queries, `[reconnecting](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.reconnection/) ` to a node, `[address resolution](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.addressResolution/) `, `[timestamp generation](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.timestampGeneration/) ` and `[speculative execution](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.speculativeExecution/) `. Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/index.html#modules) ----------------------------------------------------------------------------------------------------------- * `[addressResolution](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.addressResolution/) ` * `[loadBalancing](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.loadBalancing/) ` * `[reconnection](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.reconnection/) ` * `[retry](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.retry/) ` * `[speculativeExecution](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.speculativeExecution/) ` * `[timestampGeneration](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.timestampGeneration/) ` Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/index.html#functions) --------------------------------------------------------------------------------------------------------------- ### policies.defaultAddressTranslator[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/index.html#default-address-translator) () Returns a new instance of the default address translator policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `AddressTranslator` | | ### policies.defaultLoadBalancingPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/index.html#default-load-balancing-policy) (\[`string` localDc\]) Returns a new instance of the default load-balancing policy used by the driver. Static This function is static Parameters: | Name | Type | Description | | --- | --- | --- | | localDc optional | `string` | When provided, it sets the data center that is going to be used as local for the load-balancing policy instance.

When localDc is undefined, the load-balancing policy instance will use the `localDataCenter` provided in the `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) `. | Returns: | Type | Description | | --- | --- | | `LoadBalancingPolicy` | | ### policies.defaultReconnectionPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/index.html#default-reconnection-policy) () Returns a new instance of the default reconnection policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `ReconnectionPolicy` | | ### policies.defaultRetryPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/index.html#default-retry-policy) () Returns a new instance of the default retry policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `RetryPolicy` | | ### policies.defaultSpeculativeExecutionPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/index.html#default-speculative-execution-policy) () Returns a new instance of the default speculative execution policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `SpeculativeExecutionPolicy` | | ### policies.defaultTimestampGenerator[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/index.html#default-timestamp-generator) () Returns a new instance of the default timestamp generator used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `TimestampGenerator` | | --- # DataStax Node.js Driver - Frequently Asked Questions [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/faq/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/faq/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/faq/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/faq/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/faq/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/faq/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/faq/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/faq/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/faq/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/faq/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/faq/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/faq/) * Frequently Asked Questions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/index.html#frequently-asked-questions) ================================================================================================================================= ### Which versions of Apache Cassandra and DSE does the driver support?[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/index.html#which-versions-of-apache-cassandra-and-dse-does-the-driver-support) The driver supports all Apache Cassandra versions starting from 2.1 and [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) versions from 4.8 to the latest version. ### How do I generate a random uuid or a time-based uuid?[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/index.html#how-do-i-generate-a-random-uuid-or-a-time-based-uuid) Use the [Uuid and TimeUuid classes](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/uuids) inside the types module. ### Should I create one `Client` instance per module in my application?[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/index.html#should-i-create-one-client-instance-per-module-in-my-application) Normally you should use one `Client` instance per application. You should share that instance between modules within your application. ### Should I shut down the pool after executing a query?[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/index.html#should-i-shut-down-the-pool-after-executing-a-query) No, only call `client.shutdown()` once in your application’s lifetime, normally when you shutdown your application. ### How can I use a list of values with the IN operator in a WHERE clause?[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/index.html#how-can-i-use-a-list-of-values-with-the-in-operator-in-a-where-clause) To provide a dynamic list of values in a single parameter, use the `IN` operator followed by the question mark placeholder without parenthesis in the query. The parameter containing the list of values should be of an instance of Array. For example: const query = 'SELECT * FROM table1 WHERE key1 = ? AND key2 IN ?'; const key1 = 'param1'; const allKeys2 = [ 'val1', 'val2', 'val3' ]; client.execute(query, [ key1, allKeys2 ], { prepare: true }); ### Can I use a single `Client` instance for graph and CQL?[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/index.html#can-i-use-a-single-client-instance-for-graph-and-cql) Yes, you can. You should use [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/) to define your settings for CQL and graph workloads, for example: define which datacenter should be used for graph or for CQL. --- # DataStax Node.js Driver - Getting Started [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/getting-started/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/getting-started/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/getting-started/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/getting-started/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/getting-started/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/getting-started/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/getting-started/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/getting-started/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/getting-started/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/getting-started/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/getting-started/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/getting-started/) * Getting started[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/index.html#getting-started) ======================================================================================================================= Getting started with the DataStax Node.js driver for Apache Cassandra. Connecting to a cluster[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/index.html#connecting-to-a-cluster) --------------------------------------------------------------------------------------------------------------------------------------- To connect to an Apache Cassandra cluster, you need to provide the address or host name of at least one node in the cluster and the local data center (DC) name. The driver will discover all the nodes in the cluster and connect to all the nodes in the local data center. Typically, you should create only a single `Client` instance for a given Cassandra cluster and use it across your application. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); client.connect(); At this point, the driver will be connected to all the nodes in the local data center and discovered the rest of the nodes in your cluster. Even though calling `connect()` is not required (the `execute()` method internally calls to connect), it is recommended you call to `#connect()` on application startup, this way you can ensure that you start your app once your are connected to your cluster. When using [DataStax Astra](https://www.datastax.com/products/datastax-astra) you can configure your client by setting the secure bundle and the user credentials: const client = new cassandra.Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); Retrieving data[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/index.html#retrieving-data) ----------------------------------------------------------------------------------------------------------------------- The `execute()` method can be used to send a CQL query to a Cassandra node. const query = "SELECT name, email, birthdate FROM users WHERE key = 'mick-jagger'"; client.execute(query) .then(result => { const row = result.first(); // The row is an Object with column names as property keys. console.log('My name is %s and my email is %s', row['name'], row['email']); }); Execution methods in the driver return a `Promise`, you can await on the promise to be fulfilled using [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) . Note that for the rest of the documentation, Promise method `then()` and `await` will be used interchangeably. ### Using query parameters and prepared statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/index.html#using-query-parameters-and-prepared-statements) Instead of hard-coding your parameters in your query, you can use parameter markers in your queries and provide the parameters as an Array. const query = 'SELECT name, email, birthdate FROM users WHERE key = ?'; const result = await client.execute(query, ['mick-jagger']); This way you can reuse the query and forget about escaping / stringifying the parameters in your query. Additionally, if you plan to reuse a query within your application (it is generally the case, your parameter value changes but there is only a small number of different queries for a given schema), **you can benefit from using prepared statements**. Using prepared statements increases performance compared to plain executes, especially for repeated queries, as the query only needs to be parsed once by the Cassandra node. It has the **additional benefit of providing metadata of the parameters to the driver, allowing better type mapping between JavaScript and Cassandra** without the need of additional info (hints) from the user. // Recommended: use query markers for parameters const query = 'SELECT name, email, birthdate FROM users WHERE key = ?'; // Recommended: set the prepare flag in your queryOptions const result = await client.execute(query, ['mick-jagger'], { prepare: true }); See the [data types documentation to see how CQL types are mapped to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/) . Inserting data[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/index.html#inserting-data) --------------------------------------------------------------------------------------------------------------------- You can use the `#execute()` method to execute any CQL query. const query = 'INSERT INTO users (key, name, email, birthdate) VALUES (?, ?, ?)'; const params = ['mick-jagger', 'Sir Mick Jagger', 'mick@rollingstones.com', new Date(1943, 6, 26)]; await client.execute(query, params, { prepare: true }); The promise is fulfilled when the data is inserted. ### Setting the consistency level[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/index.html#setting-the-consistency-level) To specify how consistent the data must be for a given read or write operation, you can set the [consistency level](https://docs.datastax.com/en/dse/6.7/dse-arch/datastax_enterprise/dbInternals/dbIntConfigConsistency.html) per query. const { types } = cassandra; await client.execute(query, params, { consistency: types.consistencies.quorum }); The promise is fulfilled when the data has been written in the number of replicas satisfying the consistency level specified. You can also provide a default consistency level for all your queries when creating the `Client` instance (defaults to `localOne`). const client = new Client({ queryOptions: { consistency: types.consistencies.localQuorum }, // ... rest of the options }); Mapper (optional)[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/index.html#mapper-optional) ------------------------------------------------------------------------------------------------------------------------- The driver provides [a built-in object mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/) that lets you interact with your data like you would interact with a set of documents. const userVideos = await videoMapper.find({ userId }); for (let video of userVideos) { console.log(video.name); } Visit the [Getting Started with the Mapper Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/getting-started/) for more information. Authentication (optional)[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/index.html#authentication-optional) ----------------------------------------------------------------------------------------------------------------------------------------- Using an authentication provider on an auth-enabled Cassandra cluster: const authProvider = new cassandra.auth.PlainTextAuthProvider('my_user', 'p@ssword1!'); //Set the auth provider in the clientOptions when creating the Client instance const client = new Client({ contactPoints, localDataCenter, authProvider }); Working with mixed workloads[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/index.html#working-with-mixed-workloads) ------------------------------------------------------------------------------------------------------------------------------------------------- The driver features [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles) that provide a mechanism to group together a set of configuration options and reuse them across different query executions. [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles) are specially useful when dealing with different workloads like Graph and CQL workloads, allowing you to use a single `Client` instance for all workloads, for example: const client = new cassandra.Client({ contactPoints: ['host1'], localDataCenter: 'oltp-us-west', profiles: [\ new ExecutionProfile('time-series', {\ consistency: consistency.localOne,\ readTimeout: 30000,\ serialConsistency: consistency.localSerial\ }),\ new ExecutionProfile('graph', {\ loadBalancing: new DefaultLoadBalancingPolicy('graph-us-west'),\ consistency: consistency.localQuorum,\ readTimeout: 10000,\ graphOptions: { name: 'myGraph' }\ })\ ] }); // Use an execution profile for a CQL query client.execute('SELECT * FROM system.local', null, { executionProfile: 'time-series' }); // Use an execution profile for a gremlin query client.executeGraph('g.V().count()', null, { executionProfile: 'graph' }); --- # DataStax Node.js Driver - Upgrade Guide [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/upgrade-guide/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/upgrade-guide/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/upgrade-guide/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/upgrade-guide/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/upgrade-guide/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Upgrade guide[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#upgrade-guide) ================================================================================================================= The purpose of this guide is to detail the changes made by the successive versions of the DataStax Node.js Driver that are relevant to for an upgrade from prior versions. If you have any questions or comments, you can [post them on the mailing list](https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user) . 4.4[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#4-4) --------------------------------------------------------------------------------------------- ### New default load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#new-default-load-balancing-policy) The driver uses the new `DefaultLoadBalancingPolicy` implementation as default load balancing policy. The new policy attempts to fairly distribute the load based on the amount of in-flight request per hosts. The local replicas are initially shuffled and [between the first two nodes in the shuffled list, the one with fewer in-flight requests is selected as coordinator](https://www.eecs.harvard.edu/%7Emichaelm/postscripts/mythesis.pdf) . ### Upgrade guide for DSE driver users[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#upgrade-guide-for-dse-driver-users) The DSE driver and the Apache Cassandra driver have been merged into a single package. There’s a dedicated [guide for DSE driver users that plan to migrate to the `cassandra-driver`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/upgrade-from-dse-driver) . * * * 4.2[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#4-2) --------------------------------------------------------------------------------------------- ### Tuple constructor with one parameter[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#tuple-constructor-with-one-parameter) The `Tuple` constructor had an undocumented behaviour when invoked with a single parameter which was an `Array`, the driver used the `Array` instance as `Tuple` elements. We removed this behaviour that was used internally. `Tuple.fromArray()` method should be used to build a `Tuple` from an `Array` of elements. 4.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#4-0) --------------------------------------------------------------------------------------------- The following is a list of changes made in version 4.0 of the driver that are relevant when upgrading from version 3.x. ### localDataCenter is now a required Client option[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#local-data-center-is-now-a-required-client-option) When using `DCAwareRoundRobinPolicy`, which is used by default, a local data center must now be provided to the `Client` options parameter as `localDataCenter`. This is necessary to prevent routing requests to nodes in remote data centers. ### Selection of contact points is now evaluated in random order[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#selection-of-contact-points-is-now-evaluated-in-random-order) The list of contact points provided as a Client option is now shuffled before selecting a node to connect to as part of initialization. This change was made for instances where configuration is shared between many clients. In this case, it is better to distribute initial connections to different nodes in the cluster instead of choosing the same node each time as the initial connection makes a number of queries to discover cluster topology and schema. ### Changes to the retry and load-balancing policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#changes-to-the-retry-and-load-balancing-policies) `ExecutionOptions` is introduced as a wrapper around the `QueryOptions`. The `ExecutionOptions` contains getter methods to obtain the values of each option, defaulting to the execution profile options or the ones defined in the `ClientOptions`. Previously, a shallow copy of the provided `QueryOptions` was used, resulting in unnecessary allocations and evaluations. The `LoadBalancingPolicy` and `RetryPolicy` base classes changed method signatures to take `ExecutionOptions` instances as argument instead of `QueryOptions`. Note that no breaking change was introduced for execution methods such as `Client#execute()`, `Client#batch()`, `Client#eachRow()` and `Client#stream()`. This change only affects custom implementations of the policies. ### Query idempotency and retries[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#query-idempotency-and-retries) The configured `RetryPolicy` is not engaged when a query errors with a `WriteTimeoutException` or request error and the query was not idempotent. In order to control the possibility of retrying when an timeout/error is encountered, you must mark the query as idempotent. You can define it at `QueryOptions` level when calling the execution methods. client.execute(query, params, { prepare: true, isIdempotent: true }) Additionally, you can define the default idempotence for all executions when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, queryOptions: { isIdempotent: true } }); Previously, a similar behaviour was available using `IdempotenceAwareRetryPolicy`, that is now marked as deprecated. ### Removed `retryOnTimeout` property of `QueryOptions`[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#removed-retry-ontimeout-property-of-query-options) `retryOnTimeout`, the property that controlled whether a request should be tried when a response wasn’t obtained after a period of time is no longer available. The behaviour should be now controlled using `onRequestError()` method on the `RetryPolicy` for idempotent queries. ### Changes on `OperationInfo` of the retry module[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#changes-on-operation-info-of-the-retry-module) The retry policy methods takes [`OperationInfo`](https://docs.datastax.com/en/developer/nodejs-driver/latest/api/module.policies/module.retry/type.OperationInfo/) as a parameter. Some `OperationInfo` properties changes or were removed. * Deprecated properties `handler`, `request` and `retryOnTimeout` were removed. * `options` property was replaced by `executionOptions` which is an instance of `ExecutionOptions`. ### Removed `meta` property from `ResultSet`[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#removed-meta-property-from-result-set) On earlier versions of the driver, the `ResultSet` exposed the property `meta` which contained the raw result metadata. This property was removed in the latest version. ### Removed `DCAwareRoundRobinPolicy` `usedHostsPerRemoteDC` constructor parameter[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#removed-dc-aware-round-robin-policy-used-hosts-per-remotedc-constructor-parameter) `DCAwareRoundRobinPolicy` no longer supports routing queries to hosts in remote data centers. Because of this `usedHostsPerRemoteDC` has been removed as a constructor parameter. This change was made because handling data center outages is better suited at a service level rather than within an application client. * * * 3.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#3-0) --------------------------------------------------------------------------------------------- ### Changes in CQL aggregates metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#changes-in-cql-aggregates-metadata) The `initCondition` property of `Aggregate`, the class that represents the metadata information of a CQL aggregate, changes from `Object` to `String`. * * * 2.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#2-0) --------------------------------------------------------------------------------------------- The following is a list of changes made in version 2.0 of the driver that are relevant when upgrading from version 1.x. ### API Changes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/index.html#api-changes) 1. `uuid` and `timeuuid` values are decoded as [`Uuid`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/uuids) and [`TimeUuid`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/uuids) instances. 2. `decimal` values are decoded as [`BigDecimal`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) instances. 3. `varint` values are decoded as [`Integer`](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/numerical) instances. 4. `inet` values are decoded as `InetAddress` instances. --- # DataStax Node.js Driver - Three simple rules for coding with the driver [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/coding-rules/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/coding-rules/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/coding-rules/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/coding-rules/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/coding-rules/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/coding-rules/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/coding-rules/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/coding-rules/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/coding-rules/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/coding-rules/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/coding-rules/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/coding-rules/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/coding-rules/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/coding-rules/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/coding-rules/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/coding-rules/) * Three simple rules for coding with the driver[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/coding-rules/index.html#three-simple-rules-for-coding-with-the-driver) ================================================================================================================================================================================ When writing code that uses the driver, there are three simple rules that you should follow that make your code efficient: * Only use one `Client` instance per keyspace or use a single Client and explicitly specify the keyspace in your queries and reuse it in across your modules in the application lifetime. * If you execute a statement more than once, use a prepared statement. * In some situations you can reduce the number of network roundtrips and also have atomic operations by using batches. Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/coding-rules/index.html#client) -------------------------------------------------------------------------------------------------- The `Client` instance allows you to configure different important aspects of the way connections and queries are handled. At this level, you can configure everything from contact points (address of the nodes to be contacted initially before the driver performs node discovery), the request routing policy, retry and reconnection policies, and so on. Generally such settings are set once at the application level. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['10.1.1.3', '10.1.1.4', '10.1.1.5'], localDataCenter: 'us-east-1' }); A `Client` instance is a long-lived object, your code should share the same `Client` instance across your application. Prepared statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/coding-rules/index.html#prepared-statements) ---------------------------------------------------------------------------------------------------------------------------- Using prepared statements provides multiple benefits. A prepared statement is parsed and prepared on the Cassandra nodes and is ready for future execution. When binding parameters are provided, only they (and the query id) are sent over the wire. These performance gains add up when using the same queries (with different parameters) repeatedly. Additionally, when preparing, the driver retrieves information about the parameter types which allows an accurate mapping between a JavaScript type and a CQL type. Preparing and executing statements in the driver does not require two chained asynchronous calls. You can set the `prepare` flag in the query options and the driver handles the rest. const query = 'SELECT id, name FROM users WHERE id = ?'; client.execute(query, [ id ], { prepare: true }); Batch statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/coding-rules/index.html#batch-statements) ---------------------------------------------------------------------------------------------------------------------- The batch statement combines multiple data modification statements (`INSERT`, `UPDATE`, or `DELETE`) into a single logical operation that is sent to the server in a single request. Batching together multiple operations also ensures that they are executed in an atomic way, (that is, either all succeed or none). To make the best use of `batch()`, read about [atomic batches in Cassandra 1.2](http://www.datastax.com/dev/blog/atomic-batches-in-cassandra-1-2) , [static columns and batching of conditional updates](http://www.datastax.com/dev/dev/blog/cql-in-2-0-6) , and [CQL documentation](https://docs.datastax.com/en/cql/3.3/cql/cql_using/useBatchTOC.html) . But take into account that incorrect use of batch statements may increase load to servers. Batch queries should be prepared, by setting the `prepare` flag, when possible. const queries = [\ { query: 'UPDATE user_profiles SET email=? WHERE key=?',\ params: [emailAddress, 'hendrix']},\ { query: 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)',\ params: ['hendrix', 'Changed email', new Date()]}\ ]; const queryOptions = { prepare: true, consistency: cassandra.types.consistencies.localQuorum }; client.batch(queries, queryOptions) .then(() => console.log('Data updated on cluster')); --- # DataStax Node.js Driver - Upgrading from the DSE Driver [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/upgrade-from-dse-driver/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/upgrade-from-dse-driver/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/upgrade-from-dse-driver/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/upgrade-from-dse-driver/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/upgrade-guide/upgrade-from-dse-driver/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Upgrading from the DSE Driver[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/upgrade-from-dse-driver/index.html#upgrading-from-the-dse-driver) ========================================================================================================================================================================= This guide is intended for users of the DSE driver that plan to migrate to the `cassandra-driver`. The `cassandra-driver` now supports all DataStax products and features, such as Unified Authentication, Kerberos, geo types and graph traversal executions, allowing you to use a single driver for Apache Cassandra, DSE or other DataStax products. Upgrading from `dse-driver` to `cassandra-driver` can be as simple as changing the import statement to point to the dse package: const { Client } = require('dse-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); Becomes: const { Client } = require('cassandra-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); Submodules[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/upgrade-from-dse-driver/index.html#submodules) ----------------------------------------------------------------------------------------------------------------------------------- Most of the child modules are in the same path. const { auth, types, geometry, policies, mapping } = require('dse-driver'); Becomes: const { auth, types, geometry, policies, mapping } = require('cassandra-driver'); The only notable module path distinctions are Graph and Search types that are under `datastax` module. const { graph, search } = require('dse-driver'); Becomes: const { datastax } = require('cassandra-driver'); const { graph, search } = datastax; Load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/upgrade-from-dse-driver/index.html#load-balancing-policy) --------------------------------------------------------------------------------------------------------------------------------------------------------- The default load balancing policy on the `dse-driver` was `DseLoadBalancingPolicy`. In the `cassandra-driver`, a policy with the same behaviour is called `DefaultLoadBalancingPolicy`, which is the default. --- # DataStax Node.js Driver - metadata [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.metadata/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.metadata/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.metadata/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.metadata/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.metadata/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.metadata/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.metadata/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.metadata/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.metadata/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.metadata/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.metadata/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.metadata/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.metadata/) * module metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/index.html#module-metadata) =========================================================================================================================== Module containing classes and fields related to metadata. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/index.html#classes) ----------------------------------------------------------------------------------------------------------- * `[Aggregate](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.Aggregate/) ` * `[ClientState](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.ClientState/) ` * `[DataCollection](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.DataCollection/) ` * `[Metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.Metadata/) ` * `[MaterializedView](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.MaterializedView/) ` * `[SchemaFunction](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.SchemaFunction/) ` * `[Index](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.Index/) ` * `[TableMetadata](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.TableMetadata/) ` --- # DataStax Node.js Driver - geometry [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.geometry/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.geometry/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module geometry[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/index.html#module-geometry) =========================================================================================================================== Geometry module. Contains the classes to represent the set of additional CQL types for geospatial data that come with DSE 5.0. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/index.html#classes) ----------------------------------------------------------------------------------------------------------- * `[LineString](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/class.LineString/) ` * `[Point](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/class.Point/) ` * `[Polygon](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/class.Polygon/) ` --- # DataStax Node.js Driver - mapping [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.mapping/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.mapping/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.mapping/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.mapping/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.mapping/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.mapping/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module mapping[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/index.html#module-mapping) ======================================================================================================================== Module containing classes and fields related to the Mapper. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/index.html#classes) ---------------------------------------------------------------------------------------------------------- * `[Mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/class.Mapper/) ` * `[ModelBatchItem](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/class.ModelBatchItem/) ` * `[ModelMapper](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/class.ModelMapper/) ` * `[Result](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/class.Result/) ` * `[UnderscoreCqlToCamelCaseMappings](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/class.UnderscoreCqlToCamelCaseMappings/) ` * `[DefaultTableMappings](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/class.DefaultTableMappings/) ` Interfaces[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/index.html#interfaces) ---------------------------------------------------------------------------------------------------------------- * `[TableMappings](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/interface.TableMappings/) ` Types[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/index.html#types) ------------------------------------------------------------------------------------------------------ * `[MappingOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/type.MappingOptions/) ` * `[ModelOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/type.ModelOptions/) ` Constants[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/index.html#constants) -------------------------------------------------------------------------------------------------------------- ### q[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/index.html#q) Contains functions that represents operators in a query. Properties: | Name | Type | Description | | --- | --- | --- | | in\_ | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator “IN”. | | gt | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator greater than “>”. | | gte | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator greater than or equals to “>=” . | | lt | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator less than “<” . | | lte | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator less than or equals to “<=” . | | notEq | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator not equals to “!=” . | | and | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | When applied to a property, it represents two CQL conditions on the same column separated by the logical AND operator, e.g: “col1 >= x col < y” | | incr | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL increment assignment used for counters, e.g: “col = col + x” | | decr | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL decrement assignment used for counters, e.g: “col = col - x” | | append | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL append assignment used for collections, e.g: “col = col + x” | | prepend | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL prepend assignment used for lists, e.g: “col = x + col” | | remove | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL remove assignment used for collections, e.g: “col = col - x” | --- # DataStax Node.js Driver - QueryOptions [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.QueryOptions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/type.QueryOptions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/type.QueryOptions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/type.QueryOptions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/type.QueryOptions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/type.QueryOptions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/type.QueryOptions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/type.QueryOptions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/type.QueryOptions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/type.QueryOptions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/type.QueryOptions/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/type.QueryOptions/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/type.QueryOptions/) * type QueryOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/index.html#type-query-options) ================================================================================================================================== Query options Global This type is global Properties: | Name | Type | Description | | --- | --- | --- | | autoPage | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the driver must retrieve the following result pages automatically.

This setting is only considered by the `[Client#eachRow()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#function.each-row) ` method. For more information, check the `paging results documentation`. | | captureStackTrace | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the stack trace before the query execution should be maintained.

Useful for debugging purposes, it should be set to `false` under production environment as it adds an unnecessary overhead to each execution.

Default: false. | | consistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | `[Consistency level](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/#constant.consistencies) `.

Defaults to `localOne` for Apache Cassandra and DSE deployments. For DataStax Astra, it defaults to `localQuorum`. | | customPayload | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Key-value payload to be passed to the server. On the Cassandra side, implementations of QueryHandler can use this data. | | executeAs | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The user or role name to act as when executing this statement.

When set, it executes as a different user/role than the one currently authenticated (a.k.a. proxy execution).

This feature is only available in DSE 5.1+. | | executionProfile | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) ` | Name or instance of the `[profile](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) ` to be used for this execution. If not set, it will the use “default” execution profile. | | fetchSize | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Amount of rows to retrieve per page. | | hints | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\> | Type hints for parameters given in the query, ordered as for the parameters.

For batch queries, an array of such arrays, ordered as with the queries in the batch. | | host | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` | The host that should handle the query.

Use of this option is _heavily discouraged_ and should only be used in the following cases:

1. Querying node-local tables, such as tables in the `system` and `system_views` keyspaces.
2. Applying a series of schema changes, where it may be advantageous to execute schema changes in sequence on the same node.

Configuring a specific host causes the configured `[LoadBalancingPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.loadBalancing/class.LoadBalancingPolicy/) ` to be completely bypassed. However, if the load balancing policy dictates that the host is at a `[distance of ignored](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/#constant.distance) ` or there is no active connectivity to the host, the request will fail with a `[NoHostAvailableError](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/class.NoHostAvailableError/) `. | | isIdempotent | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Defines whether the query can be applied multiple times without changing the result beyond the initial application.

The query execution idempotence can be used at `[RetryPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.retry/class.RetryPolicy/) ` level to determine if an statement can be retried in case of request error or write timeout.

Default: `false`. | | keyspace | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Specifies the keyspace for the query. It is used for the following:

1. To indicate what keyspace the statement is applicable to (protocol V5+ only). This is useful when the query does not provide an explicit keyspace and you want to override the current `[keyspace](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#member.keyspace) `.
2. For query routing when the query operates on a different keyspace than the current `[keyspace](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#member.keyspace) `. | | logged | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the batch should be written to the batchlog. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#function.batch) `, it will be ignored by other methods. Default: true. | | counter | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if its a counter batch. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#function.batch) `, it will be ignored by other methods. Default: false. | | pageState | `Buffer` or `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Buffer or string token representing the paging state.

Useful for manual paging, if provided, the query will be executed starting from a given paging state. | | prepare | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the query must be executed as a prepared statement. | | readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | When defined, it overrides the default read timeout (`socketOptions.readTimeout`) in milliseconds for this execution per coordinator.

Suitable for statements for which the coordinator may allow a longer server-side timeout, for example aggregation queries.

A value of `0` disables client side read timeout for the execution. Default: `undefined`. | | retry | `RetryPolicy` | Retry policy for the query.

This property can be used to specify a different `[retry policy](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.retry/) ` to the one specified in the `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) `.policies. | | routingIndexes | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | Index of the parameters that are part of the partition key to determine the routing. | | routingKey | `Buffer` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | Partition key(s) to determine which coordinator should be used for the query. | | routingNames | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | Array of the parameters names that are part of the partition key to determine the routing. Only valid for non-prepared requests, it’s recommended that you use the prepare flag instead. | | serialConsistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Serial consistency is the consistency level for the serial phase of conditional updates. This option will be ignored for anything else that a conditional update/insert. | | timestamp | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` or `Long` | The default timestamp for the query in microseconds from the unix epoch (00:00:00, January 1st, 1970).

If provided, this will replace the server side assigned timestamp as default timestamp.

Use `[generateTimestamp()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/#function.generate-timestamp) ` utility method to generate a valid timestamp based on a Date and microseconds parts. | | traceQuery | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Enable query tracing for the execution. Use query tracing to diagnose performance problems related to query executions. Default: false.

To retrieve trace, you can call `[Metadata.getTrace()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.Metadata/#function.get-trace) ` method. | | graphOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Default options for graph query executions.

These options are meant to provide defaults for all graph query executions. Consider using `[execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) ` if you plan to reuse different set of options across different query executions. | | graphOptions.language | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph language to use in graph queries. Default: `'gremlin-groovy'`. | | graphOptions.name | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph name to be used in all graph queries.

This property is required but there is no default value for it. This value can be overridden at query level. | | graphOptions.readConsistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Overrides the `[consistency level](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/#constant.consistencies) ` defined in the query options for graph read queries. | | graphOptions.readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Overrides the default per-host read timeout (in milliseconds) for all graph queries. Default: `0`.

Use `null` to reset the value and use the default on `socketOptions.readTimeout` . | | graphOptions.source | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph traversal source name to use in graph queries. Default: `'g'`. | | graphOptions.writeConsistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Overrides the \[consistency level\]`[consistencies](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/#constant.consistencies) ` defined in the query options for graph write queries. | --- # DataStax Node.js Driver - ClientOptions [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.ClientOptions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/type.ClientOptions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/type.ClientOptions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/type.ClientOptions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/type.ClientOptions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/type.ClientOptions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/type.ClientOptions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/type.ClientOptions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/type.ClientOptions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/type.ClientOptions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/type.ClientOptions/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/type.ClientOptions/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/type.ClientOptions/) * type ClientOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/index.html#type-client-options) ===================================================================================================================================== Client options. While the driver provides lots of extensibility points and configurability, few client options are required. Default values for all settings are designed to be suitable for the majority of use cases, you should avoid fine tuning it when not needed. See `[Client constructor](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` documentation for recommended options. Global This type is global Properties: | Name | Type | Description | | --- | --- | --- | | contactPoints | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> | Array of addresses or host names of the nodes to add as contact points.

Contact points are addresses of Cassandra nodes that the driver uses to discover the cluster topology.

Only one contact point is required (the driver will retrieve the address of the other nodes automatically), but it is usually a good idea to provide more than one contact point, because if that single contact point is unavailable, the driver will not be able to initialize correctly. | | localDataCenter | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The local data center to use.

If using DCAwareRoundRobinPolicy (default), this option is required and only hosts from this data center are connected to and used in query plans. | | keyspace | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The logged keyspace for all the connections created within the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` instance. | | credentials | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | An object containing the username and password for plain-text authentication. It configures the authentication provider to be used against Apache Cassandra’s PasswordAuthenticator or DSE’s DseAuthenticator, when default auth scheme is plain-text.

Note that you should configure either `credentials` or `authProvider` to connect to an auth-enabled cluster, but not both. | | credentials.username | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The username to use for plain-text authentication. | | credentials.password | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The password to use for plain-text authentication. | | id | `Uuid` | A unique identifier assigned to a `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` object, that will be communicated to the server (DSE 6.0+) to identify the client instance created with this options. When not defined, the driver will generate a random identifier. | | applicationName | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | An optional setting identifying the name of the application using the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` instance.

This value is passed to DSE and is useful as metadata for describing a client connection on the server side. | | applicationVersion | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | An optional setting identifying the version of the application using the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` instance.

This value is passed to DSE and is useful as metadata for describing a client connection on the server side. | | monitorReporting | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Options for reporting mechanism from the client to the DSE server, for versions that support it. | | monitorReporting.enabled | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether the reporting mechanism is enabled. Defaults to `true`. | | cloud | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | The options to connect to a cloud instance. | | cloud.secureConnectBundle | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `URL` | Determines the file path for the credentials file bundle. | | refreshSchemaDelay | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The default window size in milliseconds used to debounce node list and schema refresh metadata requests. Default: 1000. | | isMetadataSyncEnabled | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether client-side schema metadata retrieval and update is enabled.

Setting this value to `false` will cause keyspace information not to be automatically loaded, affecting replica calculation per token in the different keyspaces. When disabling metadata synchronization, use `[Metadata.refreshKeyspaces()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.Metadata/#function.refresh-keyspaces) ` to keep keyspace information up to date or token-awareness will not work correctly.

Default: `true`. | | prepareOnAllHosts | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the driver should prepare queries on all hosts in the cluster. Default: `true`. | | rePrepareOnUp | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the driver should re-prepare all cached prepared queries on a host when it marks it back up. Default: `true`. | | maxPrepared | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Determines the maximum amount of different prepared queries before evicting items from the internal cache. Reaching a high threshold hints that the queries are not being reused, like when hard-coding parameter values inside the queries. Default: `500`. | | policies | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | policies.loadBalancing | `LoadBalancingPolicy` | The load balancing policy instance to be used to determine the coordinator per query. | | policies.retry | `RetryPolicy` | The retry policy. | | policies.reconnection | `ReconnectionPolicy` | The reconnection policy to be used. | | policies.addressResolution | `AddressTranslator` | The address resolution policy. | | policies.speculativeExecution | `SpeculativeExecutionPolicy` | The `SpeculativeExecutionPolicy` instance to be used to determine if the client should send speculative queries when the selected host takes more time than expected.

Default: `` `[NoSpeculativeExecutionPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.speculativeExecution/class.NoSpeculativeExecutionPolicy/) ` `` | | policies.timestampGeneration | `TimestampGenerator` | The client-side `[query timestamp generator](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.timestampGeneration/class.TimestampGenerator/) `.

Default: `` `[MonotonicTimestampGenerator](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) ` ``

Use `null` to disable client-side timestamp generation. | | queryOptions | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` | Default options for all queries. | | pooling | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Pooling options. | | pooling.heartBeatInterval | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The amount of idle time in milliseconds that has to pass before the driver issues a request on an active connection to avoid idle time disconnections. Default: 30000. | | pooling.coreConnectionsPerHost | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Associative array containing amount of connections per host distance. | | pooling.maxRequestsPerConnection | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The maximum number of requests per connection. The default value is:

* For modern protocol versions (v3 and above): 2048
* For older protocol versions (v1 and v2): 128 | | pooling.warmup | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if all connections to hosts in the local datacenter must be opened on connect. Default: true. | | protocolOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | protocolOptions.port | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The port to use to connect to the Cassandra host. If not set through this method, the default port (9042) will be used instead. | | protocolOptions.maxSchemaAgreementWaitSeconds | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The maximum time in seconds to wait for schema agreement between nodes before returning from a DDL query. Default: 10. | | protocolOptions.maxVersion | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | When set, it limits the maximum protocol version used to connect to the nodes. Useful for using the driver against a cluster that contains nodes with different major/minor versions of Cassandra. | | protocolOptions.noCompact | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | When set to true, enables the NO\_COMPACT startup option.

When this option is supplied `SELECT`, `UPDATE`, `DELETE`, and `BATCH` statements on `COMPACT STORAGE` tables function in “compatibility” mode which allows seeing these tables as if they were “regular” CQL tables.

This option only effects interactions with interactions with tables using `COMPACT STORAGE` and is only supported by C\* 3.0.16+, 3.11.2+, 4.0+ and DSE 6.0+. | | socketOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | socketOptions.connectTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Connection timeout in milliseconds. Default: 5000. | | socketOptions.defunctReadTimeoutThreshold | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Determines the amount of requests that simultaneously have to timeout before closing the connection. Default: 64. | | socketOptions.keepAlive | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Whether to enable TCP keep-alive on the socket. Default: true. | | socketOptions.keepAliveDelay | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | TCP keep-alive delay in milliseconds. Default: 0. | | socketOptions.readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Per-host read timeout in milliseconds.

Please note that this is not the maximum time a call to `[execute](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#function.execute) ` may have to wait; this is the maximum time that call will wait for one particular Cassandra host, but other hosts will be tried if one of them timeout. In other words, a `[execute](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#function.execute) ` call may theoretically wait up to `readTimeout * number_of_cassandra_hosts` (though the total number of hosts tried for a given query also depends on the LoadBalancingPolicy in use).

When setting this value, keep in mind the following:

* the timeout settings used on the Cassandra side (\*\_request\_timeout\_in\_ms in cassandra.yaml) should be taken into account when picking a value for this read timeout. You should pick a value a couple of seconds greater than the Cassandra timeout settings.
* the read timeout is only approximate and only control the timeout to one Cassandra host, not the full query.

Setting a value of 0 disables read timeouts. Default: `12000`. | | socketOptions.tcpNoDelay | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | When set to true, it disables the Nagle algorithm. Default: true. | | socketOptions.coalescingThreshold | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Buffer length in bytes use by the write queue before flushing the frames. Default: 8000. | | authProvider | `AuthProvider` | Provider to be used to authenticate to an auth-enabled cluster. | | requestTracker | `RequestTracker` | The instance of RequestTracker used to monitor or log requests executed with this instance. | | sslOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Client-to-node ssl options. When set the driver will use the secure layer. You can specify cert, ca, … options named after the Node.js `tls.connect()` options.

It uses the same default values as Node.js `tls.connect()` except for `rejectUnauthorized` which is set to `false` by default (for historical reasons). This setting is likely to change in upcoming versions to enable validation by default. | | encoding | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Encoding options. | | encoding.map | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Map constructor to use for Cassandra map type encoding and decoding. If not set, it will default to Javascript Object with map keys as property names. | | encoding.set | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Set constructor to use for Cassandra set type encoding and decoding. If not set, it will default to Javascript Array. | | encoding.copyBuffer | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the network buffer should be copied for buffer based data types (blob, uuid, timeuuid and inet).

Setting it to true will cause that the network buffer is copied for each row value of those types, causing additional allocations but freeing the network buffer to be reused. Setting it to true is a good choice for cases where the Row and ResultSet returned by the queries are long-lived objects.

Setting it to false will cause less overhead and the reference of the network buffer to be maintained until the row / result set are de-referenced. Default: true. | | encoding.useUndefinedAsUnset | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Valid for Cassandra 2.2 and above. Determines that, if a parameter is set to `undefined` it should be encoded as `unset`.

By default, ECMAScript `undefined` is encoded as `null` in the driver. Cassandra 2.2 introduced the concept of unset. At driver level, you can set a parameter to unset using the field `types.unset`. Setting this flag to true allows you to use ECMAScript undefined as Cassandra `unset`.

Default: true. | | encoding.useBigIntAsLong | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Use [BigInt ECMAScript type](https://tc39.github.io/proposal-bigint/)
to represent CQL bigint and counter data types. | | encoding.useBigIntAsVarint | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Use [BigInt ECMAScript type](https://tc39.github.io/proposal-bigint/)
to represent CQL varint data type. | | profiles | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) `\> | The array of `[execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) `. | | promiseFactory | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Function to be used to create a `Promise` from a callback-style function.

Promise libraries often provide different methods to create a promise. For example, you can use Bluebird’s `Promise.fromCallback()` method.

By default, the driver will use the `Promise constructor`. | --- # DataStax Node.js Driver - ResultCallback [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ResultCallback/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ResultCallback/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ResultCallback/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.ResultCallback/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/type.ResultCallback/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/type.ResultCallback/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/type.ResultCallback/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/type.ResultCallback/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/type.ResultCallback/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/type.ResultCallback/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/type.ResultCallback/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/type.ResultCallback/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/type.ResultCallback/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/type.ResultCallback/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/type.ResultCallback/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/type.ResultCallback/) * type ResultCallback[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ResultCallback/index.html#type-result-callback) ======================================================================================================================================== Callback used by execution methods. Global This type is global --- # DataStax Node.js Driver - errors [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.errors/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.errors/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.errors/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.errors/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.errors/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.errors/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.errors/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.errors/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.errors/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.errors/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.errors/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.errors/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.errors/) * module errors[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/index.html#module-errors) ===================================================================================================================== Contains the error classes exposed by the driver. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/index.html#classes) --------------------------------------------------------------------------------------------------------- * `[NoHostAvailableError](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/class.NoHostAvailableError/) ` * `[ResponseError](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/class.ResponseError/) ` * `[DriverInternalError](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/class.DriverInternalError/) ` * `[AuthenticationError](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/class.AuthenticationError/) ` * `[ArgumentError](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/class.ArgumentError/) ` * `[OperationTimedOutError](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/class.OperationTimedOutError/) ` * `[NotSupportedError](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/class.NotSupportedError/) ` * `[BusyConnectionError](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/class.BusyConnectionError/) ` Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/index.html#functions) ------------------------------------------------------------------------------------------------------------- ### VIntOutOfRangeException[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/index.html#v-int-out-ofrange-exception) (`Long` long) Parameters: | Name | Type | Description | | --- | --- | --- | | long | `Long` | | --- # DataStax Node.js Driver - concurrent [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.concurrent/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.concurrent/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.concurrent/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.concurrent/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.concurrent/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.concurrent/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.concurrent/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.concurrent/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module concurrent[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.concurrent/index.html#module-concurrent) ================================================================================================================================= Utilities for concurrent query execution with the DataStax Node.js Driver. Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.concurrent/index.html#functions) ----------------------------------------------------------------------------------------------------------------- ### concurrent.executeConcurrent[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.concurrent/index.html#execute-concurrent) (`[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` client, `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<{query, params}\> query, `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\>, `Stream` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` parameters, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` options\]) Executes multiple queries concurrently at the defined concurrency level. Static This function is static Examples: Using a fixed query and an Array of Arrays as parameters const query = 'INSERT INTO table1 (id, value) VALUES (?, ?)'; const parameters = [[1, 'a'], [2, 'b'], [3, 'c'], ]; // ... const result = await executeConcurrent(client, query, parameters); Using a fixed query and a readable stream const stream = csvStream.pipe(transformLineToArrayStream); const result = await executeConcurrent(client, query, stream); Using a different queries const queryAndParameters = [\ { query: 'INSERT INTO videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ { query: 'INSERT INTO user_videos (user_id, id, name) VALUES (?, ?, ?)',\ params: [ userId, id, name ] },\ { query: 'INSERT INTO latest_videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ ]; const result = await executeConcurrent(client, queryAndParameters); Parameters: | Name | Type | Description | | --- | --- | --- | | client | `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` | The `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` instance. | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<{query, params}\> | The query to execute per each parameter item. | | parameters | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\>, `Stream` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | An `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or a readable `Stream` composed of `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` items representing each individual set of parameters. Per each item in the `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `Stream`, an execution is going to be made. | | options optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | The execution options. | | options.executionProfile optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The execution profile to be used. | | options.concurrencyLevel optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The concurrency level to determine the maximum amount of in-flight operations at any given time

(default: `100`) | | options.raiseOnFirstError optional | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether execution should stop after the first failed execution and the corresponding exception will be raised.

(default: `true`) | | options.collectResults optional | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether each individual `[ResultSet](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.ResultSet/) ` instance should be collected in the grouped result.

(default: `false`) | | options.maxErrors optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The maximum amount of errors to be collected before ignoring the rest of the error results.

(default: `100`) | Returns: | Type | Description | | --- | --- | | `Promise`<`ResultSetGroup`\> | A `Promise` of `ResultSetGroup` that is resolved when all the executions completed and it’s rejected when `raiseOnFirstError` is `true` and there is one or more failures. | --- # DataStax Node.js Driver - datastax [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.datastax/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.datastax/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.datastax/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.datastax/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.datastax/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module datastax[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.datastax/index.html#module-datastax) =========================================================================================================================== DataStax module. Contains modules and classes to represent functionality that is specific to DataStax products. Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.datastax/index.html#modules) ----------------------------------------------------------------------------------------------------------- * `[graph](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.datastax/module.graph/) ` * `[search](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.datastax/module.search/) ` --- # DataStax Node.js Driver - Encoder [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.Encoder/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.Encoder/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.Encoder/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.Encoder/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.Encoder/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.Encoder/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.Encoder/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.Encoder/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.Encoder/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.Encoder/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.Encoder/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.Encoder/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.Encoder/) * class Encoder[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/index.html#class-encoder) ===================================================================================================================== Global This class is global Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/index.html#constructor) ----------------------------------------------------------------------------------------------------------------- new ### Encoder[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/index.html#encoder) (`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` protocolVersion) Serializes and deserializes to and from a CQL type and a Javascript Type. Parameters: | Name | Type | Description | | --- | --- | --- | | protocolVersion | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/index.html#methods) --------------------------------------------------------------------------------------------------------- ### decode[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/index.html#decode) (`Buffer` buffer, `ColumnInfo` type) Decodes Cassandra bytes into Javascript values. This is part of an **experimental** API, this can be changed future releases. Parameters: | Name | Type | Description | | --- | --- | --- | | buffer | `Buffer` | Raw buffer to be decoded. | | type | `ColumnInfo` | | ### encode[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/index.html#encode) (`*` value, `ColumnInfo`, `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` or `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` typeInfo) Encodes Javascript types into Buffer according to the Cassandra protocol. This is part of an **experimental** API, this can be changed future releases. Parameters: | Name | Type | Description | | --- | --- | --- | | value | `*` | The value to be converted. | | typeInfo | `ColumnInfo`, `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` or `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The type information.

It can be either a:

* A `String` representing the data type.
* A `Number` with one of the values of `[dataTypes](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/#constant.data-types) `.
* An `Object` containing the `type.code` as one of the values of `[dataTypes](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/#constant.data-types) ` and `type.info`. | Returns: | Type | Description | | --- | --- | | `Buffer` | | --- # DataStax Node.js Driver - HostMap [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.HostMap/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.HostMap/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.HostMap/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.HostMap/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.HostMap/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.HostMap/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.HostMap/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.HostMap/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.HostMap/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.HostMap/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.HostMap/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.HostMap/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.HostMap/) * class HostMap[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#class-host-map) ====================================================================================================================== Represents an associative-array of `[hosts](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` that can be iterated. It creates an internal copy when adding or removing, making it safe to iterate using the values() method within async operations. Global This class is global Augments[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#augments) ----------------------------------------------------------------------------------------------------------- * `events.EventEmitter` Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#constructor) ----------------------------------------------------------------------------------------------------------------- new ### HostMap[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#host-map) () Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#methods) --------------------------------------------------------------------------------------------------------- ### clear[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#clear) () Removes all items from the map. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) `\> | The previous items | ### forEach[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#for-each) (callback) Executes a provided function once per map element. Parameters: | Name | Type | Description | | --- | --- | --- | | callback | | | ### get[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#get) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` key) Gets a `[host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` by key or undefined if not found. Parameters: | Name | Type | Description | | --- | --- | --- | | key | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | Returns: | Type | Description | | --- | --- | | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` | | ### keys[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#keys) () Returns an array of host addresses. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) `\> | | ### remove[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#remove) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` key) Removes an item from the map. Parameters: | Name | Type | Description | | --- | --- | --- | | key | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The key of the host | ### removeMultiple[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#remove-multiple) (`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) `\> keys) Removes multiple hosts from the map. Parameters: | Name | Type | Description | | --- | --- | --- | | keys | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) `\> | | ### set[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#set) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` key, `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` value) Adds a new item to the map. Parameters: | Name | Type | Description | | --- | --- | --- | | key | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The key of the host | | value | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` | The host to be added | ### values[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/index.html#values) () Returns a shallow copy of the values of the map. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) `\> | | --- # DataStax Node.js Driver - Host [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.Host/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.Host/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.Host/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.Host/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.Host/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.Host/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.Host/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.Host/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.Host/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.Host/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.Host/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.Host/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.Host/) * class Host[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#class-host) ============================================================================================================ Represents a Cassandra node. Global This class is global Augments[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#augments) -------------------------------------------------------------------------------------------------------- * `[EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) ` Members[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#members) ------------------------------------------------------------------------------------------------------ `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### address[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#address) Gets ip address and port number of the node separated by `:`. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### cassandraVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#cassandra-version) Gets string containing the Cassandra version. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### datacenter[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#datacenter) Gets data center name of the node. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### dseVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#dse-version) Gets string containing the DSE version or null if not set. `Uuid` ### hostId[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#host-id) Gets the id of the host. This identifier is used by the server for internal communication / gossip. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### rack[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#rack) Gets rack name of the node. `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` ### tokens[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#tokens) Gets the tokens assigned to the node. `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> ### workloads[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#workloads) Gets the DSE Workloads the host is running. This is based on the “workload” or “workloads” columns in {@code system.local} and {@code system.peers}. Workload labels may vary depending on the DSE version in use;e.g. DSE 5.1 may report two distinct workloads: `Search` and `Analytics`, while DSE 5.0 would report a single `SearchAnalytics` workload instead. The driver simply returns the workload labels as reported by DSE, without any form of pre-processing. When the information is unavailable, this property returns an empty array. Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#constructor) -------------------------------------------------------------------------------------------------------------- new ### Host[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#host) () Creates a new Host instance. Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#methods) ------------------------------------------------------------------------------------------------------ ### canBeConsideredAsUp[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#can-beconsidered-asup) () Determines if the host can be considered as UP. Deprecated: Use `Host#isUp()` instead. Returns: | Type | Description | | --- | --- | | `boolean` | | ### getCassandraVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#get-cassandra-version) () Returns an array containing the Cassandra Version as an Array of Numbers having the major version in the first position. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) `\> | | ### getDseVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#get-dse-version) () Gets the DSE version of the host as an Array, containing the major version in the first position. In case the cluster is not a DSE cluster, it returns an empty Array. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | | ### isUp[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/index.html#is-up) () Determines if the node is UP now (seen as UP by the driver). Returns: | Type | Description | | --- | --- | | `boolean` | | --- # DataStax Node.js Driver - TransitionalModePlainTextAuthenticator [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.TransitionalModePlainTextAuthenticator/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.TransitionalModePlainTextAuthenticator/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.TransitionalModePlainTextAuthenticator/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * class TransitionalModePlainTextAuthenticator[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.TransitionalModePlainTextAuthenticator/index.html#class-transitional-mode-plain-text-authenticator) ====================================================================================================================================================================================================================== Authenticator that accounts for DSE authentication configured with transitional mode: normal. In this situation, the client is allowed to connect without authentication, but DSE would still send an AUTHENTICATE response. This Authenticator handles this situation by sending back a dummy credential. Global This class is global Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.TransitionalModePlainTextAuthenticator/index.html#constructor) ------------------------------------------------------------------------------------------------------------------------------------------------ new ### TransitionalModePlainTextAuthenticator[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.TransitionalModePlainTextAuthenticator/index.html#transitional-mode-plain-text-authenticator) () --- # DataStax Node.js Driver - Address resolution [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/address-resolution/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/address-resolution/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/address-resolution/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/address-resolution/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/address-resolution/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/address-resolution/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/address-resolution/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/address-resolution/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/address-resolution/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/address-resolution/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/address-resolution/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/address-resolution/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/address-resolution/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/address-resolution/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/address-resolution/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/address-resolution/) * Address resolution[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/address-resolution/index.html#address-resolution) ========================================================================================================================================= The driver auto-detects new Cassandra nodes when they are added to the cluster by means of server-side push notifications and checking the system tables. For each node, the address the driver receives the address set as [`rpc_address` in the node’s cassandra.yaml file](https://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configCassandra_yaml_r.html?scroll=reference_ds_qfg_n1r_1k__rpc_address) (or [`broadcast_rpc_address` when defined](https://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configCassandra_yaml_r.html?scroll=reference_ds_qfg_n1r_1k__rpc_address) ). In most cases, this is the correct value, however, sometimes the addresses received in this manner are either not reachable directly by the driver or are not the preferred address to use. A common such scenario is a multi-datacenter deployment with a client connecting using the private IP address to the local datacenter (to reduce network costs) and the public IP address for the remote datacenter nodes. The AddressTranslator interface[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/address-resolution/index.html#the-address-translator-interface) -------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `AddressTranslator` interface allows you to deal with such cases, by transforming the address sent by a Cassandra node to another address to be used by the driver for connection. class MyAddressTranslator extends AddressTranslator { translate(address, port, callback) { // Your custom translation logic } } You then configure the driver to use your AddressTranslator implementation in the client options. const client = new Client({ contactPoints, localDataCenter, policies: { addressResolution: new MyAddressTranslator() } }); Note: The contact points provided while creating the Client are not translated, only addresses retrieved from or sent by Cassandra nodes are. EC2 multi-region[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/address-resolution/index.html#ec2-multi-region) ------------------------------------------------------------------------------------------------------------------------------------- The `EC2MultiRegionTranslator` class is provided out of the box. It helps optimize network costs when your infrastructure (both Cassandra nodes and clients) is distributed across multiple Amazon EC2 regions: * a client communicating with a Cassandra node in the same EC2 region should use the node’s private IP address (which is less expensive); * a client communicating with a node in a different region should use the public IP address. To use this implementation, provide an instance when initializing the `Client` object. const cassandra = require('cassandra-driver'); const { EC2MultiRegionTranslator } = cassandra.policies.addressResolution; const client = new cassandra.Client({ contactPoints, localDataCenter, policies: { addressResolution: new EC2MultiRegionTranslator() } }); The `Client` class performs a reverse DNS lookup of the origin address to find the domain name of the target instance. Then it performs a forward DNS lookup of the domain name; the EC2 DNS does the private to public switch automatically based on location. --- # DataStax Node.js Driver - Connection pooling [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/connection-pooling/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/connection-pooling/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/connection-pooling/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/connection-pooling/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/connection-pooling/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/connection-pooling/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/connection-pooling/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/connection-pooling/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/connection-pooling/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/connection-pooling/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/connection-pooling/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/connection-pooling/) * Connection pooling[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling/index.html#connection-pooling) ========================================================================================================================================= The driver maintains one or more connections opened to each Apache Cassandra node selected by the load-balancing policy. The amount of connections per host is defined in the pooling configuration. Default pooling configuration[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling/index.html#default-pooling-configuration) --------------------------------------------------------------------------------------------------------------------------------------------------------------- The default number of connections per host depends on the version of the Apache Cassandra cluster. When using the driver to connect to modern server versions (Apache Cassandra 2.1 and above), the driver uses one connection per host. Setting the number of connections per host[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling/index.html#setting-the-number-of-connections-per-host) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If needed, you can set the number of connections per host depending on the distance, relative to the driver instance, in the `pooling` configuration: const cassandra = require('cassandra-driver'); const distance = cassandra.types.distance; const options = { contactPoints, localDataCenter, pooling: { coreConnectionsPerHost: { [distance.local]: 2, [distance.remote]: 1 } } }; const client = new Client(options); Simultaneous requests per connection[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling/index.html#simultaneous-requests-per-connection) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The driver limits the amount of concurrent requests per connection to `2048` with modern protocol versions and `128` with older versions of the protocol (v1 and v2). You can throttle requests by setting the `maxRequestsPerConnection` value in the `poolingOptions`. When the limit is reached for all connections to a host, the driver will move to the next host according to the query plan. When the query plan is exhausted, the driver will yield a `NoHostAvailableError` containing `BusyConnectionError` instances per each host in the `innerErrors` property. Get status of the connection pool[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling/index.html#get-status-of-the-connection-pool) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can use `getState()` method to get a point-in-time information of the state of the connections pools to each host. const state = client.getState(); for (let host of state.getConnectedHosts()) { console.log('Host %s: open connections = %d; in flight queries = %d', host.address, state.getOpenConnections(host), state.getInFlightQueries(host)); } --- # DataStax Node.js Driver - Batch statements [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/batch/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/batch/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/batch/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/batch/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/batch/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/batch/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/batch/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/batch/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/batch/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/batch/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/batch/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/batch/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/batch/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/batch/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/batch/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/batch/) * Batch statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/batch/index.html#batch-statements) ------------------------------------------------------------------------------------------------------------------------ It’s common for applications to require atomic batching of multiple `INSERT`, `UPDATE`, or `DELETE` statements, even in different partitions or column families. Thanks to the Cassandra protocol changes introduced in Cassandra 2.0, the driver allows you to execute multiple statements efficiently without the need to concatenate multiple queries. The method `batch()` accepts the queries as first parameter: const query1 = 'UPDATE user_profiles SET email = ? WHERE key = ?'; const query2 = 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)'; const queries = [\ { query: query1, params: [emailAddress, 'hendrix'] },\ { query: query2, params: ['hendrix', 'Changed email', new Date()] } \ ]; // Promise-based call client.batch(queries, { prepare: true }) .then(function() { // All queries have been executed successfully }) .catch(function(err) { // None of the changes have been applied }); Or using the callback-based invocation client.batch(queries, { prepare: true }, function (err) { // All queries have been executed successfully // Or none of the changes have been applied, check err }); By preparing your queries, you will get the best performance and your JavaScript parameters correctly mapped to Cassandra types. The driver will prepare each query once on each host and execute the batch every time with the different parameters provided. Note that Cassandra batches are not suitable for bulk loading, there are dedicated tools for that. Batches allow you to group related updates in a single request, so keep the batch size small (in the order of tens). Starting from Cassandra version 2.0.8, the server issues a warning if the batch size is greater than 5K. Refer to [CQL documentation](https://docs.datastax.com/en/cql/3.3/cql/cql_using/useBatchTOC.html) for information about correct and incorrect use of batches. --- # DataStax Node.js Driver - Client [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.Client/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.Client/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.Client/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.Client/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.Client/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.Client/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.Client/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.Client/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.Client/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.Client/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.Client/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.Client/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.Client/) * class Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#class-client) ================================================================================================================== Represents a database client that maintains multiple connections to the cluster nodes, providing methods to execute CQL statements. The `Client` uses `[policies](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/) ` to decide which nodes to connect to, which node to use per each query execution, when it should retry failed or timed-out executions and how reconnection to down nodes should be made. Global This class is global Augments[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#augments) ---------------------------------------------------------------------------------------------------------- * `[EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) ` Events[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#events) ------------------------------------------------------------------------------------------------------ ### hostAdd[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#host-add) Emitted when a new host is added to the cluster. * `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` The host being added. ### hostDown[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#host-down) Emitted when a host in the cluster changed status from up to down. * `[host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` The host that changed the status. ### hostRemove[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#host-remove) Emitted when a host is removed from the cluster * `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` The host being removed. ### hostUp[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#host-up) Emitted when a host in the cluster changed status from down to up. * `[host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` The host that changed the status. Members[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#members) -------------------------------------------------------------------------------------------------------- `[HostMap](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/) ` ### hosts[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#hosts) Gets an associative array of cluster hosts. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### keyspace[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#keyspace) Gets the name of the active keyspace. `Metadata` ### metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#metadata) Gets the schema and cluster metadata information. `ClientMetrics` ### metrics[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#metrics) The `[ClientMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/interface.ClientMetrics/) ` instance used to expose measurements of its internal behavior and of the server as seen from the driver side. By default, a `[DefaultMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/class.DefaultMetrics/) ` instance is used. Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#constructor) ---------------------------------------------------------------------------------------------------------------- new ### Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#client) (`[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) ` options) Creates a new instance of `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) `. Examples: Creating a new client instance const client = new Client({ contactPoints: ['10.0.1.101', '10.0.1.102'], localDataCenter: 'datacenter1' }); Executing a query const result = await client.connect(); console.log(`Connected to ${client.hosts.length} nodes in the cluster: ${client.hosts.keys().join(', ')}`); Executing a query const result = await client.execute('SELECT key FROM system.local'); const row = result.first(); console.log(row['key']); Parameters: | Name | Type | Description | | --- | --- | --- | | options | `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) ` | The options for this instance. | Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#methods) -------------------------------------------------------------------------------------------------------- ### batch[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#batch) (`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<{query, params}\> queries, \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` options\], \[`[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ResultCallback/) ` callback\]) Executes batch of queries on an available connection to a host. It returns a `Promise` when a `callback` is not provided. Parameters: | Name | Type | Description | | --- | --- | --- | | queries | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` | The query options. | | callback optional | `[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ResultCallback/) ` | Executes callback(err, result) when the batch was executed | ### connect[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#connect) (\[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Attempts to connect to one of the `[contactPoints](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) ` and discovers the rest the nodes of the cluster. When the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` is already connected, it resolves immediately. It returns a `Promise` when a `callback` is not provided. Examples: Usage example await client.connect(); Parameters: | Name | Type | Description | | --- | --- | --- | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | The optional callback that is invoked when the pool is connected or it failed to connect. | ### eachRow[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#each-row) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params\], \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` options\], `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` rowCallback, \[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Executes the query and calls `rowCallback` for each row as soon as they are received. Calls the final `callback` after all rows have been sent, or when there is an error. The query can be prepared (recommended) or not depending on the `[prepare](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` flag. 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); Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The query to execute | | params optional | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Array of parameter values or an associative array (object) containing parameter names as keys and its value. | | options optional | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` | The query options. | | rowCallback | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Executes `rowCallback(n, row)` per each row received, where n is the row index and row is the current Row. | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Executes `callback(err, result)` after all rows have been received.

When dealing with paged results, `[ResultSet#nextPage()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/class.ResultSet/#member.next-page) ` 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. | ### execute[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#execute) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params\], \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` options\], \[`[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ResultCallback/) ` callback\]) Executes a query on an available connection. The query can be prepared (recommended) or not depending on the `[prepare](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` flag. Some execution failures can be handled transparently by the driver, according to the `[RetryPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.retry/class.RetryPolicy/) ` or the `[SpeculativeExecutionPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.speculativeExecution/) ` used. It returns a `Promise` when a `callback` is not provided. Examples: 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']); 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']); }); Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The query to execute. | | params optional | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Array of parameter values or an associative array (object) containing parameter names as keys and its value. | | options optional | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` | The query options for the execution. | | callback optional | `[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ResultCallback/) ` | Executes callback(err, result) when execution completed. When not defined, the method will return a promise. | ### executeGraph[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#execute-graph) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` parameters\], \[`GraphQueryOptions` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` options\], \[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Executes a graph query. It returns a `Promise` when a `callback` is not provided. 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 client.executeGraph('g.V()', (err, result) => { const vertex = result.first(); console.log(vertex.label); }); Iterating through the results const result = await client.executeGraph('g.E()'); for (let edge of result) { console.log(edge.label); // created }); 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 }); Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The gremlin query. | | parameters optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` | An associative array containing the key and values of the parameters. | | options optional | `GraphQueryOptions` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` | The graph query options. | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Function to execute when the response is retrieved, taking two arguments: `err` and `result`. When not defined, the method will return a promise. | ### getReplicas[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#get-replicas) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` keyspace, `Buffer` token) Gets the host that are replicas of a given token. Parameters: | Name | Type | Description | | --- | --- | --- | | keyspace | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | | token | `Buffer` | | Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) `\> | | ### getState[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#get-state) () Gets a snapshot containing information on the connections pools held by this Client at the current time. The information provided in the returned object only represents the state at the moment this method was called and it’s not maintained in sync with the driver metadata. Returns: | Type | Description | | --- | --- | | `ClientState` | A `[ClientState](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/class.ClientState/) ` instance. | ### shutdown[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#shutdown) (\[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Closes all connections to all hosts. It returns a `Promise` when a `callback` is not provided. Parameters: | Name | Type | Description | | --- | --- | --- | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Optional callback to be invoked when finished closing all connections. | ### stream[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/index.html#stream) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params\], \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` options\], \[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Executes the query and pushes the rows to the result stream as soon as they received. The stream is a `ReadableStream` object that emits rows. 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](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) `.prepare flag. Retries on multiple hosts if needed. Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The query to prepare and execute. | | params optional | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Array of parameter values or an associative array (object) containing parameter names as keys and its value | | options optional | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` | The query options. | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | executes callback(err) after all rows have been received or if there is an error | Returns: | Type | Description | | --- | --- | | `ResultStream` | | --- # DataStax Node.js Driver - ExecutionProfile [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.ExecutionProfile/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.ExecutionProfile/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.ExecutionProfile/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.ExecutionProfile/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.ExecutionProfile/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.ExecutionProfile/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.ExecutionProfile/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.ExecutionProfile/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.ExecutionProfile/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.ExecutionProfile/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.ExecutionProfile/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.ExecutionProfile/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * class ExecutionProfile[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#class-execution-profile) ================================================================================================================================================= Represents a set configurations to be used in a statement execution to be used for a single `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` instance. An `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) ` instance should not be shared across different `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` instances. Global This class is global Members[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#members) ------------------------------------------------------------------------------------------------------------------ `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` ### consistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#consistency) Consistency level. `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` ### graphOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#graph-options) The graph options for this profile. Properties: | Name | Type | Description | | --- | --- | --- | | language | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph language. | | name | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph name. | | readConsistency | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The consistency to use for graph write queries. | | source | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph traversal source. | | writeConsistency | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The consistency to use for graph write queries. | `LoadBalancingPolicy` ### loadBalancing[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#load-balancing) Load-balancing policy `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### name[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#name) Name of the execution profile. `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` ### readTimeout[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#read-timeout) Client read timeout. `RetryPolicy` ### retry[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#retry) Retry policy. `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` ### serialConsistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#serial-consistency) Serial consistency level. Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#constructor) -------------------------------------------------------------------------------------------------------------------------- new ### ExecutionProfile[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/index.html#execution-profile) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` name, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` options\]) Creates a new instance of `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) `. Examples: const { Client, ExecutionProfile } = require('cassandra-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], profiles: [\ new ExecutionProfile('metrics-oltp', {\ consistency: consistency.localQuorum,\ retry: myRetryPolicy\ })\ ] }); client.execute(query, params, { executionProfile: 'metrics-oltp' }, callback); Parameters: | Name | Type | Description | | --- | --- | --- | | name | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Name of the execution profile.

Use `'default'` to specify that the new instance should be the default `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) ` if no profile is specified in the execution. | | options optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Profile options, when any of the options is not specified the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` will the use the ones defined in the default profile. | | options.consistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The consistency level to use for this profile. | | options.loadBalancing optional | `LoadBalancingPolicy` | The load-balancing policy to use for this profile. | | options.readTimeout optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The client per-host request timeout to use for this profile. | | options.retry optional | `RetryPolicy` | The retry policy to use for this profile. | | options.serialConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The serial consistency level to use for this profile. | | options.graphOptions optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | options.graphOptions.language optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph language to use for graph queries.

Note that this setting should normally be `undefined` or set by a utility method and it’s not expected to be defined manually by the user. | | options.graphOptions.results optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The protocol to use for serializing and deserializing graph results.

Note that this setting should normally be `undefined` or set by a utility method and it’s not expected to be defined manually by the user. | | options.graphOptions.name optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph name to use for graph queries. | | options.graphOptions.readConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The consistency level to use for graph read queries. | | options.graphOptions.source optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph traversal source name to use for graph queries. | | options.graphOptions.writeConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The consistency level to use for graph write queries. | | options.loadBalancing optional | `LoadBalancingPolicy` | The load-balancing policy to use for this profile. | | options.readTimeout optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The client per-host request timeout to use for this profile. | | options.retry optional | `RetryPolicy` | The retry policy to use for this profile. | | options.serialConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The serial consistency level to use for this profile. | --- # DataStax Node.js Driver - Parameterized queries [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/parameterized-queries/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/parameterized-queries/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/parameterized-queries/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/parameterized-queries/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/parameterized-queries/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/parameterized-queries/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/parameterized-queries/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/parameterized-queries/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/parameterized-queries/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/parameterized-queries/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/parameterized-queries/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/parameterized-queries/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/parameterized-queries/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/parameterized-queries/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/parameterized-queries/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/parameterized-queries/) * Parameterized queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/parameterized-queries/index.html#parameterized-queries) ================================================================================================================================================== You can bind the values of parameters in a prepared statement either by position or by using named markers. Positional parameterized query[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/parameterized-queries/index.html#positional-parameterized-query) -------------------------------------------------------------------------------------------------------------------------------------------------------------------- When using positional parameters, the query parameters must be provided as an Array. const query = 'INSERT INTO artists (id, name) VALUES (?, ?)'; // Parameters by marker position const params = ['krichards', 'Keith Richards']; client.execute(query, params, { prepare: true }); Named parameterized query[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/parameterized-queries/index.html#named-parameterized-query) ---------------------------------------------------------------------------------------------------------------------------------------------------------- You declare the named markers in your queries and use a JavaScript object properties to define the parameters, with the `Object` property names matching the parameters names. const query = 'INSERT INTO artists (id, name) VALUES (:id, :name)'; // Parameters by marker name const params = { id: 'krichards', name: 'Keith Richards' }; client.execute(query, params, { prepare: true }); Defining named markers in your queries is supported in Cassandra 2.0 or greater for prepared statements and Cassandra 2.1 or greater for non-prepared statements. --- # DataStax Node.js Driver - Native protocol [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/native-protocol/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/native-protocol/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/native-protocol/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/native-protocol/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/native-protocol/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/native-protocol/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/native-protocol/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/native-protocol/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/native-protocol/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/native-protocol/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/native-protocol/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/native-protocol/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/native-protocol/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/native-protocol/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/native-protocol/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/native-protocol/) * Native protocol[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/native-protocol/index.html#native-protocol) ================================================================================================================================ The native protocol defines the format of the binary messages exchanged between the driver and Cassandra over TCP. As a driver user what you need to be aware of is that some Cassandra features are only available with a specific protocol version, but if you are interested in the technical details you can check [the specification in the Cassandra codebase](https://git-wip-us.apache.org/repos/asf?p=cassandra.git;a=tree;f=doc;hb=HEAD) . Controlling the protocol version[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/native-protocol/index.html#controlling-the-protocol-version) ------------------------------------------------------------------------------------------------------------------------------------------------------------------ By default, the driver uses the highest protocol version supported by the driver and the Cassandra cluster. If you want to limit the protocol version to use, you do so in the protocol options. const cassandra = require('cassandra-driver'); const protocolVersion = cassandra.types.protocolVersion; const client = new cassandra.Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.v3 } }); Mixed cluster versions and rolling upgrades[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/native-protocol/index.html#mixed-cluster-versions-and-rolling-upgrades) ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The protocol version used between the client and the Cassandra cluster is negotiated upon establishing the first connection. For clusters with nodes running mixed versions of Cassandra and during rolling upgrades this could represent an issue that could lead to limited availability. To exemplify the above, consider a mixed cluster having nodes running either Cassandra 2.1 or 2.0. * The first contact point is a 2.1 host, so the driver negotiates native protocol version 3 * While connecting to the rest of the cluster, the driver contacts a 2.0 host using native protocol version 3, which fails; an error is logged and this host will be permanently ignored. For these scenarios, mixed version clusters and rolling upgrades, it is strongly recommended to set the maximum protocol version when initializing the client: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.v2 } }); And switching it to the highest protocol version once the upgrade is completed, by leaving the maximum protocol version unspecified or by using `protocolVersion.maxSupported`: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.maxSupported } }); --- # DataStax Node.js Driver - CQL data types to JavaScript types [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/datatypes/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/datatypes/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/datatypes/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/datatypes/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/datatypes/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/datatypes/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/datatypes/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/datatypes/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/datatypes/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/datatypes/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/datatypes/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/datatypes/) * CQL data types to JavaScript types[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/index.html#cql-data-types-to-java-script-types) ================================================================================================================================================================= When retrieving the value of a column from a `Row` object, the value is typed according to the following table. | CQL data type | JavaScript type | | --- | --- | | ascii | String | | bigint | [Long / BigInt](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) | | blob | [Buffer](https://nodejs.org/api/buffer.html) | | boolean | Boolean | | counter | [Long / BigInt](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) | | date | [LocalDate](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/datetime) | | decimal | [BigDecimal](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) | | double | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) | | duration | [Duration](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.Duration/) | | float | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) | | inet | [InetAddress](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.InetAddress/) | | int | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) | | list | [Array](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/collections) | | map | [Object / ECMAScript 6 Map](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/collections) | | set | [Array / ECMAScript 6 Set](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/collections) | | smallint | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) | | text | String | | time | [LocalTime](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/datetime) | | timestamp | [Date](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/datetime) | | timeuuid | [TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/uuids) | | tinyint | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) | | tuple | [Tuple](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/tuples) | | uuid | [Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/uuids) | | varchar | String | | varint | [Integer](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) | | vector | [Float32Array](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/collections) | Encoding data[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/index.html#encoding-data) ---------------------------------------------------------------------------------------------------------------------- When encoding data, on a normal execute with parameters, the driver tries to guess the target type based on the input type. Values of type `Number` will be encoded as `double` (because `Number` is IEEE 754 double). Consider the following example: const key = 1000; client.execute('SELECT * FROM table1 where key = ?', [ key ]); If the key column is of type `int`, the execution fails. There are two possible ways to avoid this type of problem, as detailed below. ### Prepare your queries (recommended)[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/index.html#prepare-your-queries-recommended) Using prepared statements provides multiple benefits. Prepared statements are parsed and prepared on the Cassandra nodes and are ready for future execution. Also, the driver retrieves information about the parameter types which allows an **accurate mapping between a JavaScript type and a Cassandra type**. Using the previous example, setting the `prepare` flag in the queryOptions will fix it: // Prepare the query before execution client.execute('SELECT * FROM table1 where key = ?', [ key ], { prepare : true }); When using prepared statements, the driver prepares the statement once on each host to execute multiple times. ### Hinting the target data type[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/index.html#hinting-the-target-data-type) Providing parameter hints in the query options is another way around it. // Hint that the first parameter is an integer client.execute('SELECT * FROM table1 where key = ?', [ key ], { hints : ['int'] }); --- # DataStax Node.js Driver - tracker [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.tracker/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.tracker/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.tracker/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.tracker/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.tracker/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.tracker/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.tracker/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.tracker/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.tracker/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module tracker[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.tracker/index.html#module-tracker) ======================================================================================================================== Tracker module. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.tracker/index.html#classes) ---------------------------------------------------------------------------------------------------------- * `[RequestLogger](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.tracker/class.RequestLogger/) ` Interfaces[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.tracker/index.html#interfaces) ---------------------------------------------------------------------------------------------------------------- * `[RequestTracker](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.tracker/interface.RequestTracker/) ` --- # DataStax Node.js Driver - Query timestamps [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/query-timestamps/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/query-timestamps/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/query-timestamps/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/query-timestamps/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/query-timestamps/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/query-timestamps/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/query-timestamps/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/query-timestamps/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/query-timestamps/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/query-timestamps/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Query timestamps[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/index.html#query-timestamps) =================================================================================================================================== In Cassandra, each mutation has a microsecond-precision timestamp, which is used to order operations relative to each other. The timestamp can be provided by the client or assigned server-side based on the time the server processes the request. Letting the server assign the timestamp can be a problem when the order of the writes matter: with unlucky timing (different coordinators, network latency, etc.), two successive requests from the same client might be processed in a different order server-side, and end up with out-of-order timestamps. Client-side generation[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/index.html#client-side-generation) ----------------------------------------------------------------------------------------------------------------------------------------------- ### Using a timestamp generator[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/index.html#using-a-timestamp-generator) The operation timestamp can be sent as part of the request. The driver uses [`MonotonicTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) by default to generate the request timestamps. You can provide a different generator when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, policies: { timestampGeneration: new MyCustomTimestampGenerator() } }); To implement a custom timestamp generator, you must implement `TimestampGenerator` base class. In addition, you can also set the default timestamp on a per-execution basis in the query options: session.execute(query, params, { timestamp: timestamp }); #### Accuracy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/index.html#accuracy) As defined by ECMAScript, the `Date` object has millisecond resolution. The [`MononoticTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) uses a incremental counter to generate the sub-millisecond part of the timestamp until the next clock tick. #### Monotonicity[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/index.html#monotonicity) The [`MononoticTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) implementation also guarantees that the returned timestamps will always be monotonically increasing, even if multiple updates happen under the same millisecond. Note that to guarantee such monotonicity, if more than one thousand timestamps are generated within the same millisecond, or in the event of a system clock skew, the implementation might return timestamps that drift out into the future. When this happens, the built-in generator logs a periodic warning message. See their non-default constructors for ways to control the warning interval. ### Provide the timestamp in the query[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/index.html#provide-the-timestamp-in-the-query) Alternatively, if you are using an old server version, you can explicitly provide the timestamp in your CQL query (not recommended): client.execute('INSERT INTO my_table(c1, c2) VALUES (1, 1) USING TIMESTAMP 1482156745633040'); --- # DataStax Node.js Driver - Cluster and schema metadata [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/metadata/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/metadata/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/metadata/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/metadata/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/metadata/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/metadata/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/metadata/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/metadata/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/metadata/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/metadata/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/metadata/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/metadata/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/metadata/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/metadata/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/metadata/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/metadata/) * Cluster and schema metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/metadata/index.html#cluster-and-schema-metadata) ================================================================================================================================================= You can retrieve the cluster topology and the schema metadata information using the Node.js driver. After establishing the first connection, the driver retrieves the cluster topology details and exposes these through properties of the client object. This information is kept up to date using Cassandra event notifications. The following example outputs hosts information about your cluster: client.hosts.forEach(function (host) { console.log(host.address, host.datacenter, host.rack); }); Additionally, the keyspaces information is already loaded into the `Metadata` object, once the client is connected: console.log(Object.keys(client.metadata.keyspaces)); To retrieve the definition of a table, use the `Metadata#getTable()` method: client.metadata.getTable('ks1', 'table1') .then(function (tableInfo) { console.log('Table %s', table.name); table.columns.forEach(function (column) { console.log('Column %s with type %j', column.name, column.type); }); }); When retrieving the same table definition concurrently, the driver queries once and invokes all callbacks with the retrieved information. Schema agreement[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/metadata/index.html#schema-agreement) --------------------------------------------------------------------------------------------------------------------------- Schema changes need to be propagated to all nodes in the cluster. Once they have settled on a common version, we say that they are in agreement. the driver waits for schema agreement after executing a schema-altering query. This is to ensure that subsequent requests (which might get routed to different nodes) see an up-to-date version of the schema. ![Text Diagram]() The schema agreement wait is performed serially, so the `execute()` call will only return after it has completed. The check is implemented by repeatedly querying system tables for the schema version reported by each node, until they all converge to the same value. If that doesn’t happen within a given timeout, the driver will give up waiting. The default timeout is `10` seconds, it can be customized when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxSchemaAgreementWaitSeconds: 20 } }); After executing a statement, you can check whether schema agreement was successful or timed out: client.execute('CREATE TABLE table1 (id int PRIMARY KEY)') .then(rs => { console.log(`Is schema in agreement? ${rs.info.isSchemaInAgreement}`); }); Additionally, you can perform an on-demand check at any time: client.metadata.checkSchemaAgreement() .then(agreement => { console.log(`Is schema in agreement? ${agreement}`); }); Note that the on-demand check using `checkSchemaAgreement()` does not retry, it only queries system tables once. --- # DataStax Node.js Driver - Fetching large result sets [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/paging/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/paging/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/paging/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/paging/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/paging/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/paging/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/paging/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/paging/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/paging/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/paging/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/paging/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/paging/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/paging/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/paging/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/paging/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/paging/) * Fetching large result sets[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/paging/index.html#fetching-large-result-sets) ============================================================================================================================================= When dealing with a large number of rows, the driver breaks the result into pages, only requesting a limited number of rows each time (`5000` being the default `fetchSize`). To retrieve the rows beyond this default size, use one of the following paging mechanisms. Automatic paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/paging/index.html#automatic-paging) ------------------------------------------------------------------------------------------------------------------------- The driver supports asynchronous iteration of the `ResultSet` using the built-in [Async Iterator](https://github.com/tc39/proposal-async-iteration) , fetching the following result pages after the previous one has been yielded. Large result sets can be iterated using the [`for await ... of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) statement: const result = await client.execute(query, params, { prepare: true }); for await (const row of result) { console.log(row[columnName]); } Under the hood, the driver will get all the rows of the query result using multiple requests. Initially, when calling `execute()` it will retrieve the first page of results according to the fetch size (defaults to `5000`). If there are additional rows, those will be retrieved once the async iterator yielded the rows from the previous page. If needed, you can use `isPaged()` method of `ResultSet` instance to determine whether there are more pages of results than initially fetched. Note that using the async iterator will not affect the internal state of the `ResultSet` instance. You should avoid using both `rows` property that contains the row instances of the first page of results, and the async iterator, that will yield all the rows in the result regardless on the number of pages. Manual paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/paging/index.html#manual-paging) ------------------------------------------------------------------------------------------------------------------- Sometimes it is convenient to save the paging state in order to restore it later. For example, consider a stateless web service that displays a list of results with a link to the next page. When the user clicks that link, we want to run the exact same query, except that the iteration should start where we stopped on the previous page. To do so, the driver exposes a `pagingState` object that represents where we were in the result set when the last page was fetched: const options = { prepare: true , fetchSize: 1000 }; const result = await client.execute(query, parameters, options); // Property 'rows' will contain only the amount of items of the first page (max 1000 in this case) const rows = result.rows; // Store the page state let pageState = result.pageState; In the next request, use the `pageState` to fetch the following rows. // Use the pageState in the queryOptions to continue where you left it. const options = { pageState, prepare: true, fetchSize: 1000 }; const result = await client.execute(query, parameters, options); // Following rows up to fetch size (1000) const rows = result.rows; // Store the next paging state. pageState = result.pageState; Saving the paging state works well when you only let the user move from one page to the next. But it doesn’t allow arbitrary jumps (like “go directly to page 10”), because you can’t fetch a page unless you have the paging state of the previous one. Such a feature would require offset queries, which are not natively supported by Apache Cassandra. **Note**: The page state token can be manipulated to retrieve other results within the same column family, so it is not safe to expose it to the users in plain text. Row streams[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/paging/index.html#row-streams) --------------------------------------------------------------------------------------------------------------- If you want to handle a large result set as a [`Stream`](https://nodejs.org/api/stream.html) of rows, you can use `stream()` method of the `Client` instance. The `stream()` method automatically fetches the following pages, yielding the rows as they come through the network and retrieving the following page only after the previous rows were read (throttling). client.stream(query, parameters, options) .on('readable', function () { // readable is emitted as soon a row is received and parsed let row; while (row = this.read()) { // process row } }) .on('end', function () { // emitted when all rows have been retrieved and read }); --- # DataStax Node.js Driver - metrics [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.metrics/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.metrics/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.metrics/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.metrics/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.metrics/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.metrics/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module metrics[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/index.html#module-metrics) ======================================================================================================================== The `metrics` module contains interfaces and implementations used by the driver to expose measurements of its internal behavior and of the server as seen from the driver side. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/index.html#classes) ---------------------------------------------------------------------------------------------------------- * `[DefaultMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/class.DefaultMetrics/) ` Interfaces[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/index.html#interfaces) ---------------------------------------------------------------------------------------------------------------- * `[ClientMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/interface.ClientMetrics/) ` --- # DataStax Node.js Driver - ExecutionOptions [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.ExecutionOptions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.ExecutionOptions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.ExecutionOptions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.ExecutionOptions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.ExecutionOptions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.ExecutionOptions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * class ExecutionOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#class-execution-options) ================================================================================================================================================= A base class that represents a wrapper around the user provided query options with getter methods and proper default values. Note that getter methods might return `undefined` when not set on the query options or default `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` options. Global This class is global Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#constructor) -------------------------------------------------------------------------------------------------------------------------- new ### ExecutionOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#execution-options) () Creates a new instance of `[ExecutionOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/) `. Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#methods) ------------------------------------------------------------------------------------------------------------------ ### getCaptureStackTrace[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-capture-stack-trace) () Determines if the stack trace before the query execution should be maintained. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | ### getConsistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-consistency) () Gets the `[Consistency level](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/#constant.consistencies) ` to be used for the execution. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getCustomPayload[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-custom-payload) () Key-value payload to be passed to the server. On the server side, implementations of QueryHandler can use this data. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | ### getFetchSize[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-fetch-size) () Gets the amount of rows to retrieve per page. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getFixedHost[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-fixed-host) () When a fixed host is set on the query options and the query plan for the load-balancing policy is not used, it gets the host that should handle the query. Returns: | Type | Description | | --- | --- | | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` | | ### getHints[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-hints) () Gets the type hints for parameters given in the query, ordered as for the parameters. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\> | | ### getKeyspace[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-keyspace) () Gets the keyspace for the query when set at query options level. Note that this method will return `undefined` when the keyspace is not set at query options level. It will only return the keyspace name when the user provided a different keyspace than the current `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` keyspace. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | ### getLoadBalancingPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-load-balancing-policy) () Gets the load balancing policy used for this execution. Returns: | Type | Description | | --- | --- | | `LoadBalancingPolicy` | A `LoadBalancingPolicy` instance, it can’t be `undefined`. | ### getPageState[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-page-state) () Gets the Buffer representing the paging state. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `Buffer` | | ### getRawQueryOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-raw-query-options) () Gets the query options as provided to the execution method without setting the default values. Returns: | Type | Description | | --- | --- | | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` | | ### getReadTimeout[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-read-timeout) () Gets the timeout in milliseconds to be used for the execution per coordinator. A value of `0` disables client side read timeout for the execution. Default: `undefined`. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getRetryPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-retry-policy) () Gets the `[retry policy](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/module.retry/) ` to be used. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `RetryPolicy` | A `RetryPolicy` instance, it can’t be `undefined`. | ### getRoutingKey[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-routing-key) () Gets the partition key(s) to determine which coordinator should be used for the query. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `Buffer` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`Buffer`\> | | ### getSerialConsistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-serial-consistency) () Gets the the consistency level to be used for the serial phase of conditional updates. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getTimestamp[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#get-timestamp) () Gets the provided timestamp for the execution in microseconds from the unix epoch (00:00:00, January 1st, 1970). When a timestamp generator is used, this method returns `undefined`. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) `, `Long`, `[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined) ` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` | | ### isAutoPage[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#is-auto-page) () Determines whether the driver must retrieve the following result pages automatically. This setting is only considered by the `[Client#eachRow()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#function.each-row) ` method. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | ### isBatchCounter[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#is-batch-counter) () Determines whether its a counter batch. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#function.batch) `, it will be ignored by other methods. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | A `Boolean` value, it can’t be `undefined`. | ### isBatchLogged[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#is-batch-logged) () Determines whether the batch should be written to the batchlog. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/#function.batch) `, it will be ignored by other methods. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | A `Boolean` value, it can’t be `undefined`. | ### isIdempotent[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#is-idempotent) () Determines whether the query can be applied multiple times without changing the result beyond the initial application. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | ### isPrepared[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#is-prepared) () Determines whether the query must be prepared beforehand. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | A `Boolean` value, it can’t be `undefined`. | ### isQueryTracing[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/index.html#is-query-tracing) () Determines whether query tracing is enabled for the execution. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | --- # DataStax Node.js Driver - Execution Profiles [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/execution-profiles/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/execution-profiles/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/execution-profiles/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/execution-profiles/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/execution-profiles/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/execution-profiles/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/execution-profiles/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/execution-profiles/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/execution-profiles/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/execution-profiles/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/execution-profiles/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Execution Profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/index.html#execution-profiles) ========================================================================================================================================= Execution profiles provide a mechanism to group together a set of configuration options and reuse them across different query executions. This feature is specially useful when dealing with different workloads like DSE Graph, Cql OLTP workloads, DSE search, … These options include: * Load balancing policy * Retry policy * Consistency levels * Per-host request timeout * Graph Options * Graph name * Graph traversal source * Graph read consistency * Graph write consistency Using Execution Profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/index.html#using-execution-profiles) ----------------------------------------------------------------------------------------------------------------------------------------------------- ### Initializing cluster with profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/index.html#initializing-cluster-with-profiles) Execution profiles should be created when creating the `Client` instance with a name that identifies it and the settings that apply to the profile. const aggregationProfile = new ExecutionProfile('aggregation', { consistency: consistency.localQuorum, loadBalancing: new DCAwareRoundRobinPolicy('us-west'), retry: myRetryPolicy, readTimeout: 30000, serialConsistency: consistency.localSerial }); const client = new Client({ contactPoints: ['host1'], localDataCenter, profiles: [ aggregationProfile ] }); Note that while the above options are all the supported settings on the execution profiles, you can specify only the ones that are required for the executions, using the `'default'` profile to fill the rest of the options. #### Default execution profile[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/index.html#default-execution-profile) You can define a default profile, using the name `'default'`: const client = new Client({ contactPoints: ['host1'], localDataCenter, profiles: [ \ new ExecutionProfile('default', {\ consistency: consistency.one,\ readTimeout: 10000\ }),\ new ExecutionProfile('graph-oltp', {\ consistency: consistency.localQuorum,\ graphOptions: { name: 'myGraph' }\ })\ ] }); The default profile will be used to fill the unspecified options in the rest of the profiles. In the above example, the read timeout for the profile named `'graph-oltp'` will be the one defined in the default profile (10,000 ms). For the settings that are not specified in the default profile, the driver will use the default `Client` options. ### Using an execution profile by name[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/index.html#using-an-execution-profile-by-name) Use the name to specify which profile you want to use for the execution. client.execute(query, params, { executionProfile: 'aggregation' }); ### Using an execution profile by instance[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/index.html#using-an-execution-profile-by-instance) You can also use the `ExecutionProfile` instance. client.execute(query, params, { executionProfile: aggregationProfile }); ### Using default execution profile[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/index.html#using-default-execution-profile) When the execution profile is not provided in the options, the default execution profile is used. client.execute(query, params, null); --- # DataStax Node.js Driver - Query warnings [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-warnings/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-warnings/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-warnings/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-warnings/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/query-warnings/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/query-warnings/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/query-warnings/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/query-warnings/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/query-warnings/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/query-warnings/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/query-warnings/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/query-warnings/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/query-warnings/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/query-warnings/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/query-warnings/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/query-warnings/) * Query warnings[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-warnings/index.html#query-warnings) ============================================================================================================================= When a query is considered to be harmful for the overall cluster, Cassandra issues a warning that is written to the Cassandra logs. From Cassandra 2.2, [these warnings are also returned to the client drivers](https://issues.apache.org/jira/browse/CASSANDRA-8930) . In the driver, these warnings are [returned in the ResultSet property information](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.ResultSet/) . The warning is still written to the [driver logs](https://docs.datastax.com/en/developer/nodejs-driver/4.7/#logging) . --- # DataStax Node.js Driver - Promise and callback-based API [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/promise-callback/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/promise-callback/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/promise-callback/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/promise-callback/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/promise-callback/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/promise-callback/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/promise-callback/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/promise-callback/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/promise-callback/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/promise-callback/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/promise-callback/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/promise-callback/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/promise-callback/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/promise-callback/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Promise and callback-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/promise-callback/index.html#promise-and-callback-based-api) =============================================================================================================================================================== The driver supports both [promises](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) and callbacks for the asynchronous methods exposed in the `Client` and `Metadata` prototypes, you can choose the approach that suits your needs. Promise-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/promise-callback/index.html#promise-based-api) ------------------------------------------------------------------------------------------------------------------------------------- client.execute('SELECT name, email FROM users') .then(result => console.log('User with email %s', result.rows[0].email)); When a `callback` is not provided as the last argument, the driver will return a `Promise`, without the need to promisify the driver module. Returned promises are instances of [`Promise` global object](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) and are created using the default constructor: `new Promise(executor)`. In case you want the driver to use a third party `Promise` module (ie: [bluebird](http://bluebirdjs.com/) ) to create the `Promise` instances, you can optionally provide your own factory method when creating the `Client` instance, for example: const BbPromise = require('bluebird'); const client = new Client({ contactPoints, localDataCenter, promiseFactory: BbPromise.fromCallback }); Callback-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/promise-callback/index.html#callback-based-api) --------------------------------------------------------------------------------------------------------------------------------------- All asynchronous methods of the driver supports an optional `callback` as the last argument. client.execute('SELECT name, email FROM users', function(err, result) { assert.ifError(err); console.log('User with email %s', result.rows[0].email); }); --- # DataStax Node.js Driver - User-defined functions and aggregates [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/udfs/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/udfs/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/udfs/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/udfs/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/udfs/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/udfs/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/udfs/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/udfs/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/udfs/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/udfs/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/udfs/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/udfs/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/udfs/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/udfs/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/udfs/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/udfs/) * User-defined functions and aggregates[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/udfs/index.html#user-defined-functions-and-aggregates) ================================================================================================================================================================= Cassandra 2.2 introduced [user-defined functions](https://issues.apache.org/jira/browse/CASSANDRA-7395) (UDF) and aggregates support. You access UDF and aggregate values in your queries like regular columns: const query = 'SELECT avg(salary) as salary FROM employees'; client.execute(query) .then(function (result) { const row = result.first(); console.log('Average salary %d', row.salary); }); The driver also exposes [UDFs and aggregates metadata information](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/) , for example let’s see how to retrieve the metadata information of a UDF named iif, that takes a boolean and int parameter. client.metadata.getFunction('ks1', 'iif', ['boolean', 'int']) .then(function (err, udf) { console.log('Function metadata %j', udf); }); --- # DataStax Node.js Driver - auth [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.auth/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.auth/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.auth/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.auth/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.auth/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.auth/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.auth/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.auth/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.auth/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.auth/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.auth/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.auth/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.auth/) * module auth[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/index.html#module-auth) =============================================================================================================== DSE Authentication module. Contains the classes used for connecting to a DSE cluster secured with DseAuthenticator. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/index.html#classes) ------------------------------------------------------------------------------------------------------- * `[DseGssapiAuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/class.DseGssapiAuthProvider/) ` * `[DsePlainTextAuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/class.DsePlainTextAuthProvider/) ` * `[PlainTextAuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/class.PlainTextAuthProvider/) ` * `[AuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/class.AuthProvider/) ` * `[Authenticator](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/class.Authenticator/) ` --- # DataStax Node.js Driver - Tuning policies [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/tuning-policies/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/tuning-policies/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/tuning-policies/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/tuning-policies/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/tuning-policies/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/tuning-policies/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/tuning-policies/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/tuning-policies/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/tuning-policies/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/tuning-policies/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/tuning-policies/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/tuning-policies/) * Tuning policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/index.html#tuning-policies) ================================================================================================================================ Load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/index.html#load-balancing-policy) -------------------------------------------------------------------------------------------------------------------------------------------- The load balancing policy interface consists of three methods: * `#distance(Host host)`: determines the distance to the specified host. The values are `distance.ignored`, `distance.local`, and `distance.remote`. * `#init(client, hosts, callback)`: initializes the policy. The driver calls this method only once and before any other method calls are made. * `#newQueryPlan(keyspace, queryOptions, callback)`: executes a callback with the iterator of hosts to use for a query. Each new query calls this method. The policies are responsible for yielding a group of nodes in an specific order for the driver to use (if the first node fails, it uses the next one). There are four load-balancing policies implemented in the driver: * `DCAwareRoundRobinPolicy`: a datacenter-aware, round-robin, load-balancing policy. This policy provides round-robin queries over the node of the local datacenter. It also includes in the query plans returned a configurable number of hosts in the remote data centers, but those are always tried after the local nodes. * `RoundRobinPolicy`: a policy that yields nodes in a round-robin fashion. * `TokenAwarePolicy`: a policy that yields replica nodes for a given partition key and keyspace. The token-aware policy uses a child policy to retrieve the next nodes in case the replicas for a partition key are not available. * `AllowListPolicy`: a policy that wraps the provided child policy but only “allow” hosts from the provided list. Keep in mind however that this policy defeats somewhat the host auto-detection of the driver. As such, this policy is only useful in a few special cases or for testing, but is not optimal in general. ### Default load-balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/index.html#default-load-balancing-policy) The default load-balancing policy is `DefaultLoadBalancingPolicy`. The policy yields local replicas for a given key and, if not available, it yields nodes of the local datacenter in a round-robin manner. Reconnection policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/index.html#reconnection-policy) ---------------------------------------------------------------------------------------------------------------------------------------- The reconnection policy consists of one method: * `#newSchedule()`: creates a new schedule to use in reconnection attempts. By default, the driver uses an exponential reconnection policy. The driver includes these two policy classes: * `ConstantReconnectionPolicy` * `ExponentialReconnectionPolicy` Retry policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/index.html#retry-policy) -------------------------------------------------------------------------------------------------------------------------- A client may send requests to any node in a cluster whether or not it is a replica of the data being queried. This node is placed into the coordinator role temporarily. Which node is the coordinator is determined by the load balancing policy for the cluster. The coordinator is responsible for routing the request to the appropriate replicas. If a coordinator fails during a request, the driver connects to a different node and retries the request. If the coordinator knows before a request that a replica is down, it can throw an `UnavailableException`, but if the replica fails after the request is made, it throws a `TimeoutException`. Of course, this all depends on the consistency level set for the query before executing it. A retry policy centralizes the handling of query retries, minimizing the need for catching and handling of exceptions in your business code. The retry policy interface consists of four methods: * `#onReadTimeout(info, consistency, received, blockFor, isDataPresent)`: determines what to do when the driver gets a `ReadTimeoutException` response from a Cassandra node. * `#onUnavailable(info, consistency, required, alive)`: determines what to do when the driver gets an `UnavailableException` response from a Cassandra node. * `#onWriteTimeout(info, consistency, received, blockFor, writeType)`: determines what to do when the driver gets a `WriteTimeoutException` response from a Cassandra node * `#onRequestError(info, consistency, err)`: defines whether to retry and at which consistency level on an unexpected error, invoked in the following situations: * On a client timeout, while waiting for the server response , being the error an instance of `OperationTimedOutError`. * On a connection error (socket closed, etc.). * When the contacted host replies with an error, such as `overloaded`, `isBootstrapping`, `serverError`, etc. In this case, the error is instance of `ResponseError` The [operation info](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.retry/type.OperationInfo/) , passed as a parameter to the retry policy methods, exposes the `query` and query `options` as properties. A default and base retry policy are included. ### Query idempotence[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/index.html#query-idempotence) Note that as of version 2.0, the configured `RetryPolicy` is not engaged when a query errors with a `WriteTimeoutException` or request error and the query was not [idempotent](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/#query-idempotence) . --- # DataStax Node.js Driver - policies [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.policies/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.policies/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.policies/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.policies/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.policies/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.policies/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.policies/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.policies/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.policies/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.policies/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.policies/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.policies/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.policies/) * module policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/index.html#module-policies) =========================================================================================================================== Contains driver tuning policies to determine `[load balancing](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.loadBalancing/) `, `[retrying](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.retry/) ` queries, `[reconnecting](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.reconnection/) ` to a node, `[address resolution](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.addressResolution/) `, `[timestamp generation](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.timestampGeneration/) ` and `[speculative execution](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.speculativeExecution/) `. Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/index.html#modules) ----------------------------------------------------------------------------------------------------------- * `[addressResolution](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.addressResolution/) ` * `[loadBalancing](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.loadBalancing/) ` * `[reconnection](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.reconnection/) ` * `[retry](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.retry/) ` * `[speculativeExecution](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.speculativeExecution/) ` * `[timestampGeneration](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.timestampGeneration/) ` Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/index.html#functions) --------------------------------------------------------------------------------------------------------------- ### policies.defaultAddressTranslator[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/index.html#default-address-translator) () Returns a new instance of the default address translator policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `AddressTranslator` | | ### policies.defaultLoadBalancingPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/index.html#default-load-balancing-policy) (\[`string` localDc\]) Returns a new instance of the default load-balancing policy used by the driver. Static This function is static Parameters: | Name | Type | Description | | --- | --- | --- | | localDc optional | `string` | When provided, it sets the data center that is going to be used as local for the load-balancing policy instance.

When localDc is undefined, the load-balancing policy instance will use the `localDataCenter` provided in the `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) `. | Returns: | Type | Description | | --- | --- | | `LoadBalancingPolicy` | | ### policies.defaultReconnectionPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/index.html#default-reconnection-policy) () Returns a new instance of the default reconnection policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `ReconnectionPolicy` | | ### policies.defaultRetryPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/index.html#default-retry-policy) () Returns a new instance of the default retry policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `RetryPolicy` | | ### policies.defaultSpeculativeExecutionPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/index.html#default-speculative-execution-policy) () Returns a new instance of the default speculative execution policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `SpeculativeExecutionPolicy` | | ### policies.defaultTimestampGenerator[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/index.html#default-timestamp-generator) () Returns a new instance of the default timestamp generator used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `TimestampGenerator` | | --- # DataStax Node.js Driver - Features [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/) * Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/index.html#features) ================================================================================================== The DataStax Node.js Driver is feature-rich and highly tunable Node.js client library for Apache Cassandra, DSE and DataStax products. Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/index.html#usage) -------------------------------------------------------------------------------------------- * [Address resolution](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/address-resolution) * [Authentication](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth) * [Batch statements](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/batch) * [Cluster and schema metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/metadata) * [Concurrent execution API](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api) * [Connecting to DataStax Astra](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/cloud) * [Connection pooling](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling) * [CQL data types to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes) * [Execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles) * [Fetching large result sets](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/paging) * [Geospatial types support](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/geotypes) * [Graph support](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support) * [Logging](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/logging) * [Mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper) * [Native protocol](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/native-protocol) * [Parameterized queries](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/parameterized-queries) * [Promise and callback support](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/promise-callback) * [Query timestamps](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps) * [Query warnings](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-warnings) * [Speculative query executions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions) * [TLS/SSL](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tls) * [Tuning policies](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies) * [User-defined functions and aggregates](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/udfs) --- # DataStax Node.js Driver - Concurrent Execution API [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/concurrent-api/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/concurrent-api/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/concurrent-api/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/concurrent-api/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Concurrent Execution API[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/index.html#concurrent-execution-api) ================================================================================================================================================= The DataStax Node.js driver provides a set of [utilities for concurrent query execution](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.concurrent/) , to facilitate executing multiple queries in parallel while controlling the concurrency level. The concurrent execution API can useful when, for example, you want to insert a large group of rows from an `Array` or a `Stream` and evaluate failures, if any, at the end. Usage samples[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/index.html#usage-samples) --------------------------------------------------------------------------------------------------------------------------- ### Using a fixed query and an Array of arrays as parameters[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/index.html#using-a-fixed-query-and-an-array-of-arrays-as-parameters) When an `Array` of arrays is provided, one query per each item in the `Array` will be executed, using each item as parameters. const query = 'INSERT INTO table1 (id, value) VALUES (?, ?)'; const parameters = [[1, 'a'], [2, 'b'], [3, 'c'], ]; // ... const result = await executeConcurrent(client, query, parameters); You can visit the [code examples in the driver repository](https://github.com/datastax/nodejs-driver/tree/master/examples) to check out a working example. ### Using a fixed query and a readable stream[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/index.html#using-a-fixed-query-and-a-readable-stream) When a `Stream` instance is provided the driver will read from the input stream and execute one query per item emitted. The driver will throttle reads of the input stream based on the concurrency level configured and the amount of current in-flight requests. The `Stream` instance should be a readable, in object mode, and emit `Array` instances. Per each item emitted, one query will be executed. const stream = csvStream.pipe(transformLineToArrayStream); const result = await executeConcurrent(client, query, stream); ### Using a different queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/index.html#using-a-different-queries) const queryAndParameters = [\ { query: 'INSERT INTO videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ { query: 'INSERT INTO user_videos (user_id, id, name) VALUES (?, ?, ?)',\ params: [ userId, id, name ] },\ { query: 'INSERT INTO latest_videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ ]; const result = await executeConcurrent(client, queryAndParameters); ### Execute all queries and deal with execution errors at the end[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/index.html#execute-all-queries-and-deal-with-execution-errors-at-the-end) When setting `raiseOnFirstError` to `false`, the driver will continue to execute the queries even when one or more errors are encountered. The returned `Promise` will be resolved and you can inspect the property `errors` to obtain each individual error information. const result = await executeConcurrent(client, query, parameters, { raiseOnFirstError: false }); for (let err of result.errors) { // ... } ### Defining concurrency level[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/index.html#defining-concurrency-level) Use the `concurrencyLevel` option property to set the maximum amount of requests that can be executed simultaneously. It defaults to `100`. const result = await executeConcurrent(client, query, parameters, { concurrencyLevel: 200 }); Note that increasing the amount of simultaneous requests will result in further queueing at the driver level and the server nodes level. You should find the optimal to get high throughput and low latency, based on your cluster size and hardware specifications. Using a higher concurrency level setting than optimal might result in query timeouts. ### Collecting all the ResultSet instances of each individual execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/index.html#collecting-all-the-result-set-instances-of-each-individual-execution) In the case you want the driver to collect each individual `ResultSet` instance, you can use the `collectResults` flag. const result = await executeConcurrent(client, query, parameters, { collectResults: true }); for (let rs of result.resultItems) { // ... } --- # DataStax Node.js Driver - metadata [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.metadata/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.metadata/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.metadata/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.metadata/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.metadata/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.metadata/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.metadata/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.metadata/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.metadata/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.metadata/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.metadata/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.metadata/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.metadata/) * module metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/index.html#module-metadata) =========================================================================================================================== Module containing classes and fields related to metadata. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/index.html#classes) ----------------------------------------------------------------------------------------------------------- * `[Aggregate](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.Aggregate/) ` * `[ClientState](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.ClientState/) ` * `[DataCollection](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.DataCollection/) ` * `[Metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.Metadata/) ` * `[MaterializedView](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.MaterializedView/) ` * `[SchemaFunction](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.SchemaFunction/) ` * `[Index](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.Index/) ` * `[TableMetadata](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.TableMetadata/) ` --- # DataStax Node.js Driver - types [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.types/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.types/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.types/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.types/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.types/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.types/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.types/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.types/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.types/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.types/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.types/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.types/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.types/) * module types[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#module-types) ================================================================================================================== Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#classes) -------------------------------------------------------------------------------------------------------- * `[BigDecimal](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.BigDecimal/) ` * `[Duration](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.Duration/) ` * `[Long](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.Long/) ` * `[InetAddress](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.InetAddress/) ` * `[Integer](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.Integer/) ` * `[LocalDate](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.LocalDate/) ` * `[LocalTime](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.LocalTime/) ` * `[ResultSet](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.ResultSet/) ` * `[ResultStream](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.ResultStream/) ` * `[Row](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.Row/) ` * `[TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.TimeUuid/) ` * `[Tuple](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.Tuple/) ` * `[Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.Uuid/) ` Constants[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#constants) ------------------------------------------------------------------------------------------------------------ ### consistencies[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#consistencies) Consistency levels Properties: | Name | Type | Description | | --- | --- | --- | | any | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Writing: A write must be written to at least one node. If all replica nodes for the given row key are down, the write can still succeed after a hinted handoff has been written. If all replica nodes are down at write time, an ANY write is not readable until the replica nodes for that row have recovered. | | one | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns a response from the closest replica, as determined by the snitch. | | two | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the most recent data from two of the closest replicas. | | three | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the most recent data from three of the closest replicas. | | quorum | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record with the most recent timestamp after a quorum of replicas has responded regardless of data center. Writing: A write must be written to the commit log and memory table on a quorum of replica nodes. | | all | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record with the most recent timestamp after all replicas have responded. The read operation will fail if a replica does not respond. Writing: A write must be written to the commit log and memory table on all replica nodes in the cluster for that row. | | localQuorum | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record with the most recent timestamp once a quorum of replicas in the current data center as the coordinator node has reported. Writing: A write must be written to the commit log and memory table on a quorum of replica nodes in the same data center as the coordinator node. Avoids latency of inter-data center communication. | | eachQuorum | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record once a quorum of replicas in each data center of the cluster has responded. Writing: Strong consistency. A write must be written to the commit log and memtable on a quorum of replica nodes in all data centers. | | serial | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Achieves linearizable consistency for lightweight transactions by preventing unconditional updates. | | localSerial | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Same as serial but confined to the data center. A write must be written conditionally to the commit log and memtable on a quorum of replica nodes in the same data center. | | localOne | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Similar to One but only within the DC the coordinator is in. | ### consistencyToString[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#consistency-tostring) Mapping of consistency level codes to their string representation. ### dataTypes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#data-types) CQL data types Properties: | Name | Type | Description | | --- | --- | --- | | custom | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A custom type. | | ascii | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | ASCII character string. | | bigint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 64-bit signed long. | | blob | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Arbitrary bytes (no validation). | | boolean | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | true or false. | | counter | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Counter column (64-bit signed value). | | decimal | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Variable-precision decimal. | | double | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 64-bit IEEE-754 floating point. | | float | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 32-bit IEEE-754 floating point. | | int | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 32-bit signed integer. | | text | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | UTF8 encoded string. | | timestamp | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A timestamp. | | uuid | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Type 1 or type 4 UUID. | | varchar | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | UTF8 encoded string. | | varint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Arbitrary-precision integer. | | timeuuid | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Type 1 UUID. | | inet | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | An IP address. It can be either 4 bytes long (IPv4) or 16 bytes long (IPv6). | | date | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A date without a time-zone in the ISO-8601 calendar system. | | time | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A value representing the time portion of the day. | | smallint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 16-bit two’s complement integer. | | tinyint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 8-bit two’s complement integer. | | list | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A collection of elements. | | map | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Key/value pairs. | | set | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A collection that contains no duplicate elements. | | udt | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | User-defined type. | | tuple | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A sequence of values. | ### distance[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#distance) Represents the distance of Cassandra node as assigned by a LoadBalancingPolicy relatively to the driver instance. Properties: | Name | Type | Description | | --- | --- | --- | | local | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A local node. | | remote | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A remote node. | | ignored | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A node that is meant to be ignored. | ### protocolVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#protocol-version) Contains information for the different protocol versions supported by the driver. Properties: | Name | Type | Description | | --- | --- | --- | | v1 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v1, supported in Apache Cassandra 1.2–>2.2. | | v2 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v2, supported in Apache Cassandra 2.0–>2.2. | | v3 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v3, supported in Apache Cassandra 2.1–>3.x. | | v4 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v4, supported in Apache Cassandra 2.2–>3.x. | | v5 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v5, in beta from Apache Cassandra 3.x+. Currently not supported by the driver. | | dseV1 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | DataStax Enterprise protocol v1, DSE 5.1+ | | dseV2 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | DataStax Enterprise protocol v2, DSE 6.0+ | | maxSupported | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the higher protocol version that is supported by this driver. | | minSupported | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the lower protocol version that is supported by this driver. | | isSupported | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | A function that returns a boolean determining whether a given protocol version is supported. | ### responseErrorCodes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#response-error-codes) Server error codes returned by Cassandra Properties: | Name | Type | Description | | --- | --- | --- | | serverError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Something unexpected happened. | | protocolError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Some client message triggered a protocol violation. | | badCredentials | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Authentication was required and failed. | | unavailableException | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Raised when coordinator knows there is not enough replicas alive to perform a query with the requested consistency level. | | overloaded | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The request cannot be processed because the coordinator is overloaded. | | isBootstrapping | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The request was a read request but the coordinator node is bootstrapping. | | truncateError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Error encountered during a truncate request. | | writeTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Timeout encountered on write query on coordinator waiting for response(s) from replicas. | | readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Timeout encountered on read query on coordinator waitign for response(s) from replicas. | | readFailure | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A non-timeout error encountered during a read request. | | functionFailure | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A (user defined) function encountered during execution. | | writeFailure | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A non-timeout error encountered during a write request. | | syntaxError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The submitted query has a syntax error. | | unauthorized | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The logged user doesn’t have the right to perform the query. | | invalid | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The query is syntactically correct but invalid. | | configError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The query is invalid because of some configuration issue. | | alreadyExists | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The query attempted to create a schema element (i.e. keyspace, table) that already exists. | | unprepared | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Can be thrown while a prepared statement tries to be executed if the provided statement is not known by the coordinator. | ### unset[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#unset) Unset representation. Use this field if you want to set a parameter to `unset`. Valid for Cassandra 2.2 and above. Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#functions) ------------------------------------------------------------------------------------------------------------ ### generateTimestamp[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#generate-timestamp) (\[`[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) ` date\], \[`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` microseconds\]) Generates a value representing the timestamp for the query in microseconds based on the date and the microseconds provided Parameters: | Name | Type | Description | | --- | --- | --- | | date optional | `[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) ` | The date to generate the value, if not provided it will use the current date. | | microseconds optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A number from 0 to 999 used to build the microseconds part of the date. | Returns: | Type | Description | | --- | --- | | `Long` | | ### timeuuid[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#timeuuid) (\[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` options\], \[`Buffer` buffer\], \[`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` offset\]) **Backward compatibility only, use `[TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.TimeUuid/) ` instead**. Generates and returns a RFC4122 v1 (timestamp based) UUID in a string representation. Parameters: | Name | Type | Description | | --- | --- | --- | | options optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | buffer optional | `Buffer` | | | offset optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### uuid[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/index.html#uuid) () **Backward compatibility only, use `[Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.Uuid/) ` class instead**. Generate and return a RFC4122 v4 UUID in a string representation. --- # DataStax Node.js Driver - Address resolution [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/address-resolution/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/address-resolution/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/address-resolution/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/address-resolution/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/address-resolution/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/address-resolution/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/address-resolution/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/address-resolution/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/address-resolution/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/address-resolution/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/address-resolution/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/address-resolution/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/address-resolution/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/address-resolution/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/address-resolution/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/address-resolution/) * Address resolution[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/address-resolution/index.html#address-resolution) ========================================================================================================================================= The driver auto-detects new Cassandra nodes when they are added to the cluster by means of server-side push notifications and checking the system tables. For each node, the address the driver receives the address set as [`rpc_address` in the node’s cassandra.yaml file](https://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configCassandra_yaml_r.html?scroll=reference_ds_qfg_n1r_1k__rpc_address) (or [`broadcast_rpc_address` when defined](https://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configCassandra_yaml_r.html?scroll=reference_ds_qfg_n1r_1k__rpc_address) ). In most cases, this is the correct value, however, sometimes the addresses received in this manner are either not reachable directly by the driver or are not the preferred address to use. A common such scenario is a multi-datacenter deployment with a client connecting using the private IP address to the local datacenter (to reduce network costs) and the public IP address for the remote datacenter nodes. The AddressTranslator interface[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/address-resolution/index.html#the-address-translator-interface) -------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `AddressTranslator` interface allows you to deal with such cases, by transforming the address sent by a Cassandra node to another address to be used by the driver for connection. class MyAddressTranslator extends AddressTranslator { translate(address, port, callback) { // Your custom translation logic } } You then configure the driver to use your AddressTranslator implementation in the client options. const client = new Client({ contactPoints, localDataCenter, policies: { addressResolution: new MyAddressTranslator() } }); Note: The contact points provided while creating the Client are not translated, only addresses retrieved from or sent by Cassandra nodes are. EC2 multi-region[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/address-resolution/index.html#ec2-multi-region) ------------------------------------------------------------------------------------------------------------------------------------- The `EC2MultiRegionTranslator` class is provided out of the box. It helps optimize network costs when your infrastructure (both Cassandra nodes and clients) is distributed across multiple Amazon EC2 regions: * a client communicating with a Cassandra node in the same EC2 region should use the node’s private IP address (which is less expensive); * a client communicating with a node in a different region should use the public IP address. To use this implementation, provide an instance when initializing the `Client` object. const cassandra = require('cassandra-driver'); const { EC2MultiRegionTranslator } = cassandra.policies.addressResolution; const client = new cassandra.Client({ contactPoints, localDataCenter, policies: { addressResolution: new EC2MultiRegionTranslator() } }); The `Client` class performs a reverse DNS lookup of the origin address to find the domain name of the target instance. Then it performs a forward DNS lookup of the domain name; the EC2 DNS does the private to public switch automatically based on location. --- # DataStax Node.js Driver - Authentication [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/auth/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/auth/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/auth/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth/index.html#authentication) =================================================================================================================== The driver includes three authentication providers: * `PlainTextAuthProvider`: Plain-text authentication for Apache Cassandra and DSE. * `DsePlainTextAuthProvider`: Plain-text authentication for DSE unified auth. * `DseGssapiAuthProvider`: GSSAPI authentication for DSE. In case you are using plain-text authentication on the server, you can set the `credentials` when creating the `Client` instance. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints, localDataCenter, credentials: { username: 'my_username', password: 'my_p@ssword1!' } }); Setting the authentication provider[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth/index.html#setting-the-authentication-provider) ------------------------------------------------------------------------------------------------------------------------------------------------------------- For other authentication methods, you can configure the provider in the `Client` options: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints, localDataCenter, authProvider: new cassandra.auth.DseGssapiAuthProvider() }); Note that to use the `DseGssapiAuthProvider` you need to add the dependency to `kerberos` version `~1.0.0` in your application. DSE Unified Authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth/index.html#dse-unified-authentication) ------------------------------------------------------------------------------------------------------------------------------------------- DSE Unified Authentication allows you to: * Proxy Login: Authenticate using a fixed set of authentication credentials but allow authorization of resources based on another user id. * Proxy Execute: Authenticate using a fixed set of authentication credentials but execute requests based on another user id. ### Proxy Login[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth/index.html#proxy-login) Proxy login allows you to authenticate with a user but act as another one. You need to ensure the authenticated user has the permission to use the authorization of resources of the other user. In the following example, we allow user “ben” to authenticate but use the authorization of “alice”. We grant login permission to “ben” by using a `GRANT` CQL query: GRANT PROXY.LOGIN ON ROLE 'alice' TO 'ben' Once “ben” is granted proxy login as “alice”: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: [ 'host1', 'host2' ], localDataCenter, authProvider: new cassandra.auth.DsePlainTextAuthProvider('ben', 'ben', 'alice') }); // All requests will be executed using the authorizationId 'alice' client.execute(query, params, { prepare: true }); ### Proxy Execute[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth/index.html#proxy-execute) Proxy execute allows you to execute requests as another user than the authenticated one. You need to ensure the authenticated user has the permission to use the authorization of resources of the specified user. In the following example will allow the user “ben” to execute requests as “alice”: We grant execute permission to “ben” by using a `GRANT` CQL query: GRANT PROXY.EXECUTE on role user1 to server Once “ben” is granted permission to execute queries as “alice”: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: [ 'host1', 'host2' ], localDataCenter, authProvider: new cassandra.auth.DsePlainTextAuthProvider('ben', 'ben') }); // The following requests will be executed as 'alice' client.execute(query, params, { prepare: true, executeAs: 'alice' }); Please see the [official documentation](https://docs.datastax.com/en/latest-dse/datastax_enterprise/unifiedAuth/unifiedAuthTOC.html) for more details. --- # DataStax Node.js Driver - Connecting to your DataStax Astra database using a secure connection bundle [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/cloud/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/cloud/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/cloud/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/cloud/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/cloud/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/cloud/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Connecting to your DataStax Astra database using a secure connection bundle[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/cloud/index.html#connecting-to-your-data-stax-astra-database-using-a-secure-connection-bundle) =============================================================================================================================================================================================================================================== Quickstart[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/cloud/index.html#quickstart) ------------------------------------------------------------------------------------------------------------ Use the `ClientOptions` property `cloud` to connect to your [DataStax Astra database](https://www.datastax.com/products/datastax-astra) using your secure connection bundle (`secure-connect-DATABASE_NAME.zip`) and `credentials` property to provide your [CQL credentials](https://cassandra.apache.org/doc/latest/cql/security.html#cql-roles) . Here is an example of the minimum configuration needed to connect to your DataStax Astra database using the secure connection bundle: const client = new Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); Configurable settings when using a secure connection bundle[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/cloud/index.html#configurable-settings-when-using-a-secure-connection-bundle) -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can configure your `Client` instance using other `ClientOptions` properties, for example: const client = new Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' }, keyspace: 'my_ks' }); Note that `contactPoints` and `sslOptions` should not be set when using `secureConnectBundle`. --- # DataStax Node.js Driver - TLS/SSL [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tls/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tls/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tls/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tls/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/tls/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/tls/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/tls/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/tls/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/tls/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * TLS/SSL[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tls/index.html#tls-ssl) ==================================================================================================== You can secure traffic between the driver and Apache Cassandra with TLS/SSL. There are two aspects to that: * Client-to-node encryption, where the traffic is encrypted and the client verifies the identity of the Apache Cassandra nodes it connects to. * Optional client certificate authentication, where Apache Cassandra nodes also verify the identity of the client. This section describes the driver-side configuration, it assumes that you’ve already configured SSL encryption in Apache Cassandra, you can checkout the [server documentation that covers the basic procedures](https://docs.datastax.com/en/cassandra/3.0/cassandra/configuration/secureSSLClientToNode.html) . Driver configuration[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tls/index.html#driver-configuration) ------------------------------------------------------------------------------------------------------------------------------ Use `sslOptions` property in the [`ClientOptions`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) to enable client TLS/SSL encryption: const client = new Client({ contactPoints, localDataCenter, sslOptions: { rejectUnauthorized: true }}); await client.connect(); You can define the same object properties as the options in the [standard Node.js `tls.connect()` method](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) . The main difference is that server certificate validation against the list of supplied CAs is disabled by default. You should specify `rejectUnauthorized: true` in your settings to enable it. ### Enabling client certificate authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tls/index.html#enabling-client-certificate-authentication) Much like in [Node.js standard tls module](https://nodejs.org/api/tls.html) , you can use `cert` and `key` properties to provide the certificate chain and private key. Additionally, you can override the trusted CA certificates using `ca` property: const sslOptions = { // Necessary only if the server requires client certificate authentication. key: fs.readFileSync('client-key.pem'), cert: fs.readFileSync('client-cert.pem'), // Necessary only if the server uses a self-signed certificate. ca: [ fs.readFileSync('server-cert.pem') ], rejectUnauthorized: true }; const client = new Client({ contactPoints, localDataCenter, sslOptions }); --- # DataStax Node.js Driver - Execution Profiles [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/execution-profiles/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/execution-profiles/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/execution-profiles/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/execution-profiles/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/execution-profiles/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/execution-profiles/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/execution-profiles/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/execution-profiles/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/execution-profiles/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/execution-profiles/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/execution-profiles/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Execution Profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/index.html#execution-profiles) ========================================================================================================================================= Execution profiles provide a mechanism to group together a set of configuration options and reuse them across different query executions. This feature is specially useful when dealing with different workloads like DSE Graph, Cql OLTP workloads, DSE search, … These options include: * Load balancing policy * Retry policy * Consistency levels * Per-host request timeout * Graph Options * Graph name * Graph traversal source * Graph read consistency * Graph write consistency Using Execution Profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/index.html#using-execution-profiles) ----------------------------------------------------------------------------------------------------------------------------------------------------- ### Initializing cluster with profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/index.html#initializing-cluster-with-profiles) Execution profiles should be created when creating the `Client` instance with a name that identifies it and the settings that apply to the profile. const aggregationProfile = new ExecutionProfile('aggregation', { consistency: consistency.localQuorum, loadBalancing: new DCAwareRoundRobinPolicy('us-west'), retry: myRetryPolicy, readTimeout: 30000, serialConsistency: consistency.localSerial }); const client = new Client({ contactPoints: ['host1'], localDataCenter, profiles: [ aggregationProfile ] }); Note that while the above options are all the supported settings on the execution profiles, you can specify only the ones that are required for the executions, using the `'default'` profile to fill the rest of the options. #### Default execution profile[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/index.html#default-execution-profile) You can define a default profile, using the name `'default'`: const client = new Client({ contactPoints: ['host1'], localDataCenter, profiles: [ \ new ExecutionProfile('default', {\ consistency: consistency.one,\ readTimeout: 10000\ }),\ new ExecutionProfile('graph-oltp', {\ consistency: consistency.localQuorum,\ graphOptions: { name: 'myGraph' }\ })\ ] }); The default profile will be used to fill the unspecified options in the rest of the profiles. In the above example, the read timeout for the profile named `'graph-oltp'` will be the one defined in the default profile (10,000 ms). For the settings that are not specified in the default profile, the driver will use the default `Client` options. ### Using an execution profile by name[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/index.html#using-an-execution-profile-by-name) Use the name to specify which profile you want to use for the execution. client.execute(query, params, { executionProfile: 'aggregation' }); ### Using an execution profile by instance[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/index.html#using-an-execution-profile-by-instance) You can also use the `ExecutionProfile` instance. client.execute(query, params, { executionProfile: aggregationProfile }); ### Using default execution profile[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/index.html#using-default-execution-profile) When the execution profile is not provided in the options, the default execution profile is used. client.execute(query, params, null); --- # DataStax Node.js Driver - Home [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * DataStax Node.js Driver for Apache Cassandra®[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#data-stax-node-js-driver-for-apache-cassandra) =================================================================================================================================================================== A modern, [feature-rich](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#features) and highly tunable Node.js client library for Apache Cassandra and [DSE](https://www.datastax.com/products/datastax-enterprise) using exclusively Cassandra’s binary protocol and Cassandra Query Language. Installation[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#installation) ------------------------------------------------------------------------------------------------- $ npm install cassandra-driver [![Build Status](https://api.travis-ci.com/datastax/nodejs-driver.svg?branch=master)](https://travis-ci.org/datastax/nodejs-driver) [![Build status](https://ci.appveyor.com/api/projects/status/m21t2tfdpmkjex1l/branch/master?svg=true)](https://ci.appveyor.com/project/datastax/nodejs-driver/branch/master) Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#features) ----------------------------------------------------------------------------------------- * Simple, Prepared, and [Batch](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/batch/) statements * Asynchronous IO, parallel execution, request pipelining * [Connection pooling](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/connection-pooling/) * Auto node discovery * Automatic reconnection * Configurable [load balancing](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#load-balancing-policy) and [retry policies](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#retry-policy) * Works with any cluster size * Built-in [object mapper](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/) * Both [promise and callback-based API](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/promise-callback/) * [Row streaming and pipes](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#row-streaming-and-pipes) * Built-in TypeScript support Documentation[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#documentation) --------------------------------------------------------------------------------------------------- * [Documentation index](https://docs.datastax.com/en/developer/nodejs-driver/latest/) * [CQL types to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/) * [API docs](https://docs.datastax.com/en/developer/nodejs-driver/latest/api/) * [FAQ](https://docs.datastax.com/en/developer/nodejs-driver/latest/faq/) Getting Help[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#getting-help) ------------------------------------------------------------------------------------------------- You can use the [project mailing list](https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user) or create a ticket on the [Jira issue tracker](https://datastax-oss.atlassian.net/projects/NODEJS/issues) . Basic usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#basic-usage) ----------------------------------------------------------------------------------------------- const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['h1', 'h2'], localDataCenter: 'datacenter1', keyspace: 'ks1' }); const query = 'SELECT name, email FROM users WHERE key = ?'; client.execute(query, [ 'someone' ]) .then(result => console.log('User with email %s', result.rows[0].email)); The driver supports both [promises and callbacks](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/promise-callback/) for the asynchronous methods, you can choose the approach that suits your needs. Note that in order to have concise code examples in this documentation, we will use the promise-based API of the driver along with the `await` keyword. If you are using [DataStax Astra](https://www.datastax.com/products/datastax-astra) you can configure your client by setting the secure bundle and the user credentials: const client = new cassandra.Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); ### Prepare your queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#prepare-your-queries) Using prepared statements provides multiple benefits. Prepared statements are parsed and prepared on the Cassandra nodes and are ready for future execution. Also, when preparing, the driver retrieves information about the parameter types which **allows an accurate mapping between a JavaScript type and a Cassandra type**. The driver will prepare the query once on each host and execute the statement with the bound parameters. // Use query markers (?) and parameters const query = 'UPDATE users SET birth = ? WHERE key=?'; const params = [ new Date(1942, 10, 1), 'jimi-hendrix' ]; // Set the prepare flag in the query options await client.execute(query, params, { prepare: true }); console.log('Row updated on the cluster'); ### Row streaming and pipes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#row-streaming-and-pipes) When using `#eachRow()` and `#stream()` methods, the driver parses each row as soon as it is received, yielding rows without buffering them. // Reducing a large result client.eachRow( 'SELECT time, val FROM temperature WHERE station_id=', ['abc'], (n, row) => { // The callback will be invoked per each row as soon as they are received minTemperature = Math.min(row.val, minTemperature); }, err => { // This function will be invoked when all rows where consumed or an error was encountered } ); The `#stream()` method works in the same way but instead of callback it returns a [Readable Streams2](https://nodejs.org/api/stream.html#stream_class_stream_readable) object in `objectMode` that emits instances of `Row`. It can be **piped** downstream and provides automatic pause/resume logic (it buffers when not read). client.stream('SELECT time, val FROM temperature WHERE station_id=', [ 'abc' ]) .on('readable', function () { // 'readable' is emitted as soon a row is received and parsed let row; while (row = this.read()) { console.log('time %s and value %s', row.time, row.val); } }) .on('end', function () { // Stream ended, there aren't any more rows }) .on('error', function (err) { // Something went wrong: err is a response error from Cassandra }); ### User defined types[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#user-defined-types) [User defined types (UDT)](https://cassandra.apache.org/doc/latest/cql/types.html#udts) are represented as JavaScript objects. For example: Consider the following UDT and table CREATE TYPE address ( street text, city text, state text, zip int, phones set ); CREATE TABLE users ( name text PRIMARY KEY, email text, address frozen
); You can retrieve the user address details as a regular JavaScript object. const query = 'SELECT name, address FROM users WHERE key = ?'; const result = await client.execute(query, [ key ], { prepare: true }); const row = result.first(); const address = row.address; console.log('User lives in %s, %s - %s', address.street, address.city, address.state); Read more information about using [UDTs with the Node.js Driver](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/udts/) . ### Paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#paging) All driver methods use a default `fetchSize` of 5000 rows, retrieving only first page of results up to a maximum of 5000 rows to shield an application against accidentally retrieving large result sets in a single response. `stream()` method automatically fetches the following page once the current one was read. You can also use `eachRow()` method to retrieve the following pages by using `autoPage` flag. See \[paging documentation for more information\]\[doc-paging\]. ### Batch multiple statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#batch-multiple-statements) You can execute multiple statements in a batch to update/insert several rows atomically even in different column families. const queries = [\ {\ query: 'UPDATE user_profiles SET email=? WHERE key=?',\ params: [ emailAddress, 'hendrix' ]\ }, {\ query: 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)',\ params: [ 'hendrix', 'Changed email', new Date() ]\ }\ ]; await client.batch(queries, { prepare: true }); console.log('Data updated on cluster'); Object Mapper[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#object-mapper) --------------------------------------------------------------------------------------------------- The driver provides a built-in [object mapper](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/) that lets you interact with your data like you would interact with a set of documents. Retrieving objects from the database: const videos = await videoMapper.find({ userId }); for (let video of videos) { console.log(video.name); } Updating an object from the database: await videoMapper.update({ id, userId, name, addedDate, description }); You can read more information about [getting started with the Mapper in our documentation](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/getting-started/) . * * * Data types[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#data-types) --------------------------------------------------------------------------------------------- There are few data types defined in the ECMAScript specification, this usually represents a problem when you are trying to deal with data types that come from other systems in JavaScript. The driver supports all the CQL data types in Apache Cassandra (3.0 and below) even for types with no built-in JavaScript representation, like decimal, varint and bigint. Check the documentation on working with [numerical values](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/numerical/) , [uuids](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/uuids/) and [collections](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/collections/) . Logging[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#logging) --------------------------------------------------------------------------------------- Instances of `Client()` are `EventEmitter` and emit `log` events: client.on('log', (level, loggerName, message, furtherInfo) => { console.log(`${level} - ${loggerName}: ${message}`); }); The `level` being passed to the listener can be `verbose`, `info`, `warning` or `error`. Visit the [logging documentation](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/logging/) for more information. Compatibility[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#compatibility) --------------------------------------------------------------------------------------------------- The driver supports all versions of Node.js, Cassandra, and DSE that are not EOL at the time of release. Only LTS eligible branches (i.e. even numbered releases) are supported for Node.js. See the [project documentation](https://github.com/nodejs/release#release-schedule) for more information about the Node.js release cycle. The current version of the driver offers support consistent with this policy for the following: * Apache Cassandra versions 3.0 and above. * DataStax Enterprise versions 5.1 and 6.8. * Node.js versions 18.x and 20.x. Note: DataStax products do not support big-endian systems. Credits[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#credits) --------------------------------------------------------------------------------------- This driver is based on the original work of [Jorge Bay](https://github.com/jorgebay) on [node-cassandra-cql](https://github.com/jorgebay/node-cassandra-cql) and adds a series of advanced features that are common across all other [DataStax drivers](https://github.com/datastax) for Apache Cassandra. The development effort to provide an up to date, high performance, fully featured Node.js Driver for Apache Cassandra will continue on this project, while [node-cassandra-cql](https://github.com/jorgebay/node-cassandra-cql) will be discontinued. License[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/index.html#license) --------------------------------------------------------------------------------------- © DataStax, Inc. Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- # DataStax Node.js Driver - Mapper [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/mapper/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/mapper/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/mapper/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/mapper/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/mapper/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Mapper[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/index.html#mapper) ===================================================================================================== The driver provides an object mapper that lets you interact with your data like you would interact with a set of documents. Mapper Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/index.html#mapper-features) ----------------------------------------------------------------------------------------------------------------------- * No / minimal configuration required: no need to specify the schema manually, it uses the driver schema metadata * Support denormalized schemas and materialized views: one model can be mapped to multiple tables * Convention-based mapping * Support bypassing query generation / bring your own queries and map results * Minimal performance impact compared to the core driver Basic Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/index.html#basic-usage) --------------------------------------------------------------------------------------------------------------- Retrieving objects from the database: const videos = await videoMapper.find({ userId }); for (let video of videos) { console.log(video.name); } Updating an object from the database: await videoMapper.update({ id, userId, name, addedDate, description }); Note that execution methods return a `Promise`, to simplify the code examples in the documentation [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) are used. You can continue by reading the [Getting Started Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/getting-started/) or other topics in the Mapper documentation: * [Getting Started Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/getting-started/) * [Queries](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/queries/) * [Defining Mappings](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/defining-mappings/) * [Limitations and FAQ](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/limitations-and-faq/) --- # DataStax Node.js Driver - Logging [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/logging/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/logging/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/logging/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/logging/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/logging/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/logging/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/logging/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/logging/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/logging/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Logging[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/logging/index.html#logging) ======================================================================================================== The DataStax Node.js driver uses [events](https://nodejs.org/api/events.html) to expose logging information decoupled from any specific logging framework. The driver’s `Client` inherits from [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) and it triggers `'log'` events. client.on('log', (level, loggerName, message, furtherInfo) => { console.log(`${level} - ${loggerName}: ${message}`); }); The level being passed to the listener can be `'verbose'`, `'info'`, `'warning'` or `'error'`. `verbose` level is only suitable for debugging and it’s usually too noisy. We recommend that you gather logging events from `info` and above on production environments. Tracking query latency and size[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/logging/index.html#tracking-query-latency-and-size) -------------------------------------------------------------------------------------------------------------------------------------------------------- The `RequestLogger` logs queries executed by the driver and it allows tracking requests considered slow and/or large. A request is considered “slow” when it takes longer to complete than a configured threshold in milliseconds. A request is considered to be large when the request size is greater than a configured threshold in bytes. To turn on this feature, you first need to create an instance of `RequestLogger` and use it when creating the `Client` instance: const cassandra = require('cassandra-driver'); const requestTracker = new cassandra.tracker.RequestLogger({ slowThreshold: 1000 }); const client = new Client({ contactPoints, localDataCenter, requestTracker }); You can subscribe to `'slow'`, `'large'`, `'normal'` and `'failure'` events using the emitter object instance: requestTracker.emitter.on('slow', message => console.log(message)); An example message would be: [10.1.1.1:9042] Slow request, took 305 ms (request size 35 bytes / response size 1 KB): SELECT col1, col2 FROM table1 WHERE id = ? [1] Note that events will be emitted only when certain options are defined: * `'slow'` events will only be emitted if `slowThreshold` is set. * `'large'` events will only be emitted if `requestSizeThreshold` is set. * `'normal'` events will only be emitted if `logNormalRequests` is set to `true`. This setting can be changed at runtime using the `RequestLogger` property of the same name. * `'failure'` events will only be emitted if `logErroredRequests` is set to `true`. This setting can be changed at runtime using the property of the same name. You can provide your own tracker implementing `RequestTracker` interface. --- # DataStax Node.js Driver - ClientOptions [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.ClientOptions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/type.ClientOptions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/type.ClientOptions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/type.ClientOptions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/type.ClientOptions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/type.ClientOptions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/type.ClientOptions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/type.ClientOptions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/type.ClientOptions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/type.ClientOptions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/type.ClientOptions/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/type.ClientOptions/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/type.ClientOptions/) * type ClientOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/index.html#type-client-options) ===================================================================================================================================== Client options. While the driver provides lots of extensibility points and configurability, few client options are required. Default values for all settings are designed to be suitable for the majority of use cases, you should avoid fine tuning it when not needed. See `[Client constructor](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` documentation for recommended options. Global This type is global Properties: | Name | Type | Description | | --- | --- | --- | | contactPoints | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> | Array of addresses or host names of the nodes to add as contact points.

Contact points are addresses of Cassandra nodes that the driver uses to discover the cluster topology.

Only one contact point is required (the driver will retrieve the address of the other nodes automatically), but it is usually a good idea to provide more than one contact point, because if that single contact point is unavailable, the driver will not be able to initialize correctly. | | localDataCenter | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The local data center to use.

If using DCAwareRoundRobinPolicy (default), this option is required and only hosts from this data center are connected to and used in query plans. | | keyspace | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The logged keyspace for all the connections created within the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` instance. | | credentials | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | An object containing the username and password for plain-text authentication. It configures the authentication provider to be used against Apache Cassandra’s PasswordAuthenticator or DSE’s DseAuthenticator, when default auth scheme is plain-text.

Note that you should configure either `credentials` or `authProvider` to connect to an auth-enabled cluster, but not both. | | credentials.username | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The username to use for plain-text authentication. | | credentials.password | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The password to use for plain-text authentication. | | id | `Uuid` | A unique identifier assigned to a `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` object, that will be communicated to the server (DSE 6.0+) to identify the client instance created with this options. When not defined, the driver will generate a random identifier. | | applicationName | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | An optional setting identifying the name of the application using the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` instance.

This value is passed to DSE and is useful as metadata for describing a client connection on the server side. | | applicationVersion | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | An optional setting identifying the version of the application using the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` instance.

This value is passed to DSE and is useful as metadata for describing a client connection on the server side. | | monitorReporting | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Options for reporting mechanism from the client to the DSE server, for versions that support it. | | monitorReporting.enabled | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether the reporting mechanism is enabled. Defaults to `true`. | | cloud | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | The options to connect to a cloud instance. | | cloud.secureConnectBundle | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `URL` | Determines the file path for the credentials file bundle. | | refreshSchemaDelay | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The default window size in milliseconds used to debounce node list and schema refresh metadata requests. Default: 1000. | | isMetadataSyncEnabled | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether client-side schema metadata retrieval and update is enabled.

Setting this value to `false` will cause keyspace information not to be automatically loaded, affecting replica calculation per token in the different keyspaces. When disabling metadata synchronization, use `[Metadata.refreshKeyspaces()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.Metadata/#function.refresh-keyspaces) ` to keep keyspace information up to date or token-awareness will not work correctly.

Default: `true`. | | prepareOnAllHosts | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the driver should prepare queries on all hosts in the cluster. Default: `true`. | | rePrepareOnUp | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the driver should re-prepare all cached prepared queries on a host when it marks it back up. Default: `true`. | | maxPrepared | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Determines the maximum amount of different prepared queries before evicting items from the internal cache. Reaching a high threshold hints that the queries are not being reused, like when hard-coding parameter values inside the queries. Default: `500`. | | policies | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | policies.loadBalancing | `LoadBalancingPolicy` | The load balancing policy instance to be used to determine the coordinator per query. | | policies.retry | `RetryPolicy` | The retry policy. | | policies.reconnection | `ReconnectionPolicy` | The reconnection policy to be used. | | policies.addressResolution | `AddressTranslator` | The address resolution policy. | | policies.speculativeExecution | `SpeculativeExecutionPolicy` | The `SpeculativeExecutionPolicy` instance to be used to determine if the client should send speculative queries when the selected host takes more time than expected.

Default: `` `[NoSpeculativeExecutionPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.speculativeExecution/class.NoSpeculativeExecutionPolicy/) ` `` | | policies.timestampGeneration | `TimestampGenerator` | The client-side `[query timestamp generator](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.timestampGeneration/class.TimestampGenerator/) `.

Default: `` `[MonotonicTimestampGenerator](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) ` ``

Use `null` to disable client-side timestamp generation. | | queryOptions | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` | Default options for all queries. | | pooling | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Pooling options. | | pooling.heartBeatInterval | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The amount of idle time in milliseconds that has to pass before the driver issues a request on an active connection to avoid idle time disconnections. Default: 30000. | | pooling.coreConnectionsPerHost | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Associative array containing amount of connections per host distance. | | pooling.maxRequestsPerConnection | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The maximum number of requests per connection. The default value is:

* For modern protocol versions (v3 and above): 2048
* For older protocol versions (v1 and v2): 128 | | pooling.warmup | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if all connections to hosts in the local datacenter must be opened on connect. Default: true. | | protocolOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | protocolOptions.port | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The port to use to connect to the Cassandra host. If not set through this method, the default port (9042) will be used instead. | | protocolOptions.maxSchemaAgreementWaitSeconds | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The maximum time in seconds to wait for schema agreement between nodes before returning from a DDL query. Default: 10. | | protocolOptions.maxVersion | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | When set, it limits the maximum protocol version used to connect to the nodes. Useful for using the driver against a cluster that contains nodes with different major/minor versions of Cassandra. | | protocolOptions.noCompact | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | When set to true, enables the NO\_COMPACT startup option.

When this option is supplied `SELECT`, `UPDATE`, `DELETE`, and `BATCH` statements on `COMPACT STORAGE` tables function in “compatibility” mode which allows seeing these tables as if they were “regular” CQL tables.

This option only effects interactions with interactions with tables using `COMPACT STORAGE` and is only supported by C\* 3.0.16+, 3.11.2+, 4.0+ and DSE 6.0+. | | socketOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | socketOptions.connectTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Connection timeout in milliseconds. Default: 5000. | | socketOptions.defunctReadTimeoutThreshold | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Determines the amount of requests that simultaneously have to timeout before closing the connection. Default: 64. | | socketOptions.keepAlive | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Whether to enable TCP keep-alive on the socket. Default: true. | | socketOptions.keepAliveDelay | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | TCP keep-alive delay in milliseconds. Default: 0. | | socketOptions.readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Per-host read timeout in milliseconds.

Please note that this is not the maximum time a call to `[execute](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#function.execute) ` may have to wait; this is the maximum time that call will wait for one particular Cassandra host, but other hosts will be tried if one of them timeout. In other words, a `[execute](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#function.execute) ` call may theoretically wait up to `readTimeout * number_of_cassandra_hosts` (though the total number of hosts tried for a given query also depends on the LoadBalancingPolicy in use).

When setting this value, keep in mind the following:

* the timeout settings used on the Cassandra side (\*\_request\_timeout\_in\_ms in cassandra.yaml) should be taken into account when picking a value for this read timeout. You should pick a value a couple of seconds greater than the Cassandra timeout settings.
* the read timeout is only approximate and only control the timeout to one Cassandra host, not the full query.

Setting a value of 0 disables read timeouts. Default: `12000`. | | socketOptions.tcpNoDelay | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | When set to true, it disables the Nagle algorithm. Default: true. | | socketOptions.coalescingThreshold | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Buffer length in bytes use by the write queue before flushing the frames. Default: 8000. | | authProvider | `AuthProvider` | Provider to be used to authenticate to an auth-enabled cluster. | | requestTracker | `RequestTracker` | The instance of RequestTracker used to monitor or log requests executed with this instance. | | sslOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Client-to-node ssl options. When set the driver will use the secure layer. You can specify cert, ca, … options named after the Node.js `tls.connect()` options.

It uses the same default values as Node.js `tls.connect()` except for `rejectUnauthorized` which is set to `false` by default (for historical reasons). This setting is likely to change in upcoming versions to enable validation by default. | | encoding | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Encoding options. | | encoding.map | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Map constructor to use for Cassandra map type encoding and decoding. If not set, it will default to Javascript Object with map keys as property names. | | encoding.set | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Set constructor to use for Cassandra set type encoding and decoding. If not set, it will default to Javascript Array. | | encoding.copyBuffer | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the network buffer should be copied for buffer based data types (blob, uuid, timeuuid and inet).

Setting it to true will cause that the network buffer is copied for each row value of those types, causing additional allocations but freeing the network buffer to be reused. Setting it to true is a good choice for cases where the Row and ResultSet returned by the queries are long-lived objects.

Setting it to false will cause less overhead and the reference of the network buffer to be maintained until the row / result set are de-referenced. Default: true. | | encoding.useUndefinedAsUnset | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Valid for Cassandra 2.2 and above. Determines that, if a parameter is set to `undefined` it should be encoded as `unset`.

By default, ECMAScript `undefined` is encoded as `null` in the driver. Cassandra 2.2 introduced the concept of unset. At driver level, you can set a parameter to unset using the field `types.unset`. Setting this flag to true allows you to use ECMAScript undefined as Cassandra `unset`.

Default: true. | | encoding.useBigIntAsLong | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Use [BigInt ECMAScript type](https://tc39.github.io/proposal-bigint/)
to represent CQL bigint and counter data types. | | encoding.useBigIntAsVarint | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Use [BigInt ECMAScript type](https://tc39.github.io/proposal-bigint/)
to represent CQL varint data type. | | profiles | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) `\> | The array of `[execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) `. | | promiseFactory | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Function to be used to create a `Promise` from a callback-style function.

Promise libraries often provide different methods to create a promise. For example, you can use Bluebird’s `Promise.fromCallback()` method.

By default, the driver will use the `Promise constructor`. | --- # DataStax Node.js Driver - HostMap [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.HostMap/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.HostMap/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.HostMap/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.HostMap/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.HostMap/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.HostMap/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.HostMap/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.HostMap/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.HostMap/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.HostMap/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.HostMap/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.HostMap/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.HostMap/) * class HostMap[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#class-host-map) ====================================================================================================================== Represents an associative-array of `[hosts](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` that can be iterated. It creates an internal copy when adding or removing, making it safe to iterate using the values() method within async operations. Global This class is global Augments[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#augments) ----------------------------------------------------------------------------------------------------------- * `events.EventEmitter` Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#constructor) ----------------------------------------------------------------------------------------------------------------- new ### HostMap[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#host-map) () Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#methods) --------------------------------------------------------------------------------------------------------- ### clear[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#clear) () Removes all items from the map. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) `\> | The previous items | ### forEach[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#for-each) (callback) Executes a provided function once per map element. Parameters: | Name | Type | Description | | --- | --- | --- | | callback | | | ### get[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#get) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` key) Gets a `[host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` by key or undefined if not found. Parameters: | Name | Type | Description | | --- | --- | --- | | key | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | Returns: | Type | Description | | --- | --- | | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` | | ### keys[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#keys) () Returns an array of host addresses. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) `\> | | ### remove[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#remove) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` key) Removes an item from the map. Parameters: | Name | Type | Description | | --- | --- | --- | | key | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The key of the host | ### removeMultiple[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#remove-multiple) (`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) `\> keys) Removes multiple hosts from the map. Parameters: | Name | Type | Description | | --- | --- | --- | | keys | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) `\> | | ### set[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#set) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` key, `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` value) Adds a new item to the map. Parameters: | Name | Type | Description | | --- | --- | --- | | key | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The key of the host | | value | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` | The host to be added | ### values[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/index.html#values) () Returns a shallow copy of the values of the map. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) `\> | | --- # DataStax Node.js Driver - ResultCallback [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ResultCallback/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ResultCallback/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ResultCallback/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.ResultCallback/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/type.ResultCallback/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/type.ResultCallback/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/type.ResultCallback/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/type.ResultCallback/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/type.ResultCallback/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/type.ResultCallback/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/type.ResultCallback/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/type.ResultCallback/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/type.ResultCallback/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/type.ResultCallback/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/type.ResultCallback/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/type.ResultCallback/) * type ResultCallback[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ResultCallback/index.html#type-result-callback) ======================================================================================================================================== Callback used by execution methods. Global This type is global --- # DataStax Node.js Driver - errors [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.errors/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.errors/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.errors/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.errors/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.errors/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.errors/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.errors/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.errors/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.errors/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.errors/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.errors/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.errors/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.errors/) * module errors[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/index.html#module-errors) ===================================================================================================================== Contains the error classes exposed by the driver. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/index.html#classes) --------------------------------------------------------------------------------------------------------- * `[NoHostAvailableError](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/class.NoHostAvailableError/) ` * `[ResponseError](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/class.ResponseError/) ` * `[DriverInternalError](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/class.DriverInternalError/) ` * `[AuthenticationError](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/class.AuthenticationError/) ` * `[ArgumentError](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/class.ArgumentError/) ` * `[OperationTimedOutError](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/class.OperationTimedOutError/) ` * `[NotSupportedError](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/class.NotSupportedError/) ` * `[BusyConnectionError](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/class.BusyConnectionError/) ` --- # DataStax Node.js Driver - QueryOptions [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.QueryOptions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/type.QueryOptions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/type.QueryOptions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/type.QueryOptions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/type.QueryOptions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/type.QueryOptions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/type.QueryOptions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/type.QueryOptions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/type.QueryOptions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/type.QueryOptions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/type.QueryOptions/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/type.QueryOptions/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/type.QueryOptions/) * type QueryOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/index.html#type-query-options) ================================================================================================================================== Query options Global This type is global Properties: | Name | Type | Description | | --- | --- | --- | | autoPage | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the driver must retrieve the following result pages automatically.

This setting is only considered by the `[Client#eachRow()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#function.each-row) ` method. For more information, check the `paging results documentation`. | | captureStackTrace | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the stack trace before the query execution should be maintained.

Useful for debugging purposes, it should be set to `false` under production environment as it adds an unnecessary overhead to each execution.

Default: false. | | consistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | `[Consistency level](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/#constant.consistencies) `.

Defaults to `localOne` for Apache Cassandra and DSE deployments. For DataStax Astra, it defaults to `localQuorum`. | | customPayload | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Key-value payload to be passed to the server. On the Cassandra side, implementations of QueryHandler can use this data. | | executeAs | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The user or role name to act as when executing this statement.

When set, it executes as a different user/role than the one currently authenticated (a.k.a. proxy execution).

This feature is only available in DSE 5.1+. | | executionProfile | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) ` | Name or instance of the `[profile](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) ` to be used for this execution. If not set, it will the use “default” execution profile. | | fetchSize | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Amount of rows to retrieve per page. | | hints | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\> | Type hints for parameters given in the query, ordered as for the parameters.

For batch queries, an array of such arrays, ordered as with the queries in the batch. | | host | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` | The host that should handle the query.

Use of this option is _heavily discouraged_ and should only be used in the following cases:

1. Querying node-local tables, such as tables in the `system` and `system_views` keyspaces.
2. Applying a series of schema changes, where it may be advantageous to execute schema changes in sequence on the same node.

Configuring a specific host causes the configured `[LoadBalancingPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.loadBalancing/class.LoadBalancingPolicy/) ` to be completely bypassed. However, if the load balancing policy dictates that the host is at a `[distance of ignored](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/#constant.distance) ` or there is no active connectivity to the host, the request will fail with a `[NoHostAvailableError](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/class.NoHostAvailableError/) `. | | isIdempotent | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Defines whether the query can be applied multiple times without changing the result beyond the initial application.

The query execution idempotence can be used at `[RetryPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.retry/class.RetryPolicy/) ` level to determine if an statement can be retried in case of request error or write timeout.

Default: `false`. | | keyspace | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Specifies the keyspace for the query. It is used for the following:

1. To indicate what keyspace the statement is applicable to (protocol V5+ only). This is useful when the query does not provide an explicit keyspace and you want to override the current `[keyspace](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#member.keyspace) `.
2. For query routing when the query operates on a different keyspace than the current `[keyspace](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#member.keyspace) `. | | logged | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the batch should be written to the batchlog. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#function.batch) `, it will be ignored by other methods. Default: true. | | counter | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if its a counter batch. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#function.batch) `, it will be ignored by other methods. Default: false. | | pageState | `Buffer` or `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Buffer or string token representing the paging state.

Useful for manual paging, if provided, the query will be executed starting from a given paging state. | | prepare | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the query must be executed as a prepared statement. | | readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | When defined, it overrides the default read timeout (`socketOptions.readTimeout`) in milliseconds for this execution per coordinator.

Suitable for statements for which the coordinator may allow a longer server-side timeout, for example aggregation queries.

A value of `0` disables client side read timeout for the execution. Default: `undefined`. | | retry | `RetryPolicy` | Retry policy for the query.

This property can be used to specify a different `[retry policy](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.retry/) ` to the one specified in the `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) `.policies. | | routingIndexes | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | Index of the parameters that are part of the partition key to determine the routing. | | routingKey | `Buffer` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | Partition key(s) to determine which coordinator should be used for the query. | | routingNames | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | Array of the parameters names that are part of the partition key to determine the routing. Only valid for non-prepared requests, it’s recommended that you use the prepare flag instead. | | serialConsistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Serial consistency is the consistency level for the serial phase of conditional updates. This option will be ignored for anything else that a conditional update/insert. | | timestamp | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` or `Long` | The default timestamp for the query in microseconds from the unix epoch (00:00:00, January 1st, 1970).

If provided, this will replace the server side assigned timestamp as default timestamp.

Use `[generateTimestamp()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/#function.generate-timestamp) ` utility method to generate a valid timestamp based on a Date and microseconds parts. | | traceQuery | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Enable query tracing for the execution. Use query tracing to diagnose performance problems related to query executions. Default: false.

To retrieve trace, you can call `[Metadata.getTrace()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.Metadata/#function.get-trace) ` method. | | graphOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Default options for graph query executions.

These options are meant to provide defaults for all graph query executions. Consider using `[execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) ` if you plan to reuse different set of options across different query executions. | | graphOptions.language | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph language to use in graph queries. Default: `'gremlin-groovy'`. | | graphOptions.name | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph name to be used in all graph queries.

This property is required but there is no default value for it. This value can be overridden at query level. | | graphOptions.readConsistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Overrides the `[consistency level](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/#constant.consistencies) ` defined in the query options for graph read queries. | | graphOptions.readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Overrides the default per-host read timeout (in milliseconds) for all graph queries. Default: `0`.

Use `null` to reset the value and use the default on `socketOptions.readTimeout` . | | graphOptions.source | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph traversal source name to use in graph queries. Default: `'g'`. | | graphOptions.writeConsistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Overrides the \[consistency level\]`[consistencies](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/#constant.consistencies) ` defined in the query options for graph write queries. | --- # DataStax Node.js Driver - Encoder [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.Encoder/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.Encoder/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.Encoder/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.Encoder/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.Encoder/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.Encoder/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.Encoder/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.Encoder/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.Encoder/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.Encoder/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.Encoder/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.Encoder/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.Encoder/) * class Encoder[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/index.html#class-encoder) ===================================================================================================================== Global This class is global Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/index.html#constructor) ----------------------------------------------------------------------------------------------------------------- new ### Encoder[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/index.html#encoder) (`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` protocolVersion, `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) ` options) Serializes and deserializes to and from a CQL type and a Javascript Type. Parameters: | Name | Type | Description | | --- | --- | --- | | protocolVersion | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | | options | `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) ` | | Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/index.html#methods) --------------------------------------------------------------------------------------------------------- ### decode[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/index.html#decode) (`Buffer` buffer, `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` type) Decodes Cassandra bytes into Javascript values. This is part of an **experimental** API, this can be changed future releases. Parameters: | Name | Type | Description | | --- | --- | --- | | buffer | `Buffer` | Raw buffer to be decoded. | | type | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | An object containing the data type `code` and `info`. | | type.code | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Type code. | | type.info optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Additional information on the type for complex / nested types. | ### encode[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/index.html#encode) (`*` value, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) `, `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` typeInfo\]) Encodes Javascript types into Buffer according to the Cassandra protocol. This is part of an **experimental** API, this can be changed future releases. Parameters: | Name | Type | Description | | --- | --- | --- | | value | `*` | The value to be converted. | | typeInfo optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) `, `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The type information.

It can be either a:

* A `String` representing the data type.
* A `Number` with one of the values of `[dataTypes](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/#constant.data-types) `.
* An `Object` containing the `type.code` as one of the values of `[dataTypes](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/#constant.data-types) ` and `type.info`. | Returns: | Type | Description | | --- | --- | | `Buffer` | | --- # DataStax Node.js Driver - Fetching large result sets [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/paging/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/paging/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/paging/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/paging/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/paging/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/paging/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/paging/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/paging/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/paging/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/paging/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/paging/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/paging/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/paging/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/paging/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/paging/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/paging/) * Fetching large result sets[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/paging/index.html#fetching-large-result-sets) ============================================================================================================================================= When dealing with a large number of rows, the driver breaks the result into pages, only requesting a limited number of rows each time (`5000` being the default `fetchSize`). To retrieve the rows beyond this default size, use one of the following paging mechanisms. Automatic paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/paging/index.html#automatic-paging) ------------------------------------------------------------------------------------------------------------------------- The driver supports asynchronous iteration of the `ResultSet` using the built-in [Async Iterator](https://github.com/tc39/proposal-async-iteration) , fetching the following result pages after the previous one has been yielded. Large result sets can be iterated using the [`for await ... of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) statement: const result = await client.execute(query, params, { prepare: true }); for await (const row of result) { console.log(row[columnName]); } Under the hood, the driver will get all the rows of the query result using multiple requests. Initially, when calling `execute()` it will retrieve the first page of results according to the fetch size (defaults to `5000`). If there are additional rows, those will be retrieved once the async iterator yielded the rows from the previous page. If needed, you can use `isPaged()` method of `ResultSet` instance to determine whether there are more pages of results than initially fetched. Note that using the async iterator will not affect the internal state of the `ResultSet` instance. You should avoid using both `rows` property that contains the row instances of the first page of results, and the async iterator, that will yield all the rows in the result regardless on the number of pages. Manual paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/paging/index.html#manual-paging) ------------------------------------------------------------------------------------------------------------------- Sometimes it is convenient to save the paging state in order to restore it later. For example, consider a stateless web service that displays a list of results with a link to the next page. When the user clicks that link, we want to run the exact same query, except that the iteration should start where we stopped on the previous page. To do so, the driver exposes a `pagingState` object that represents where we were in the result set when the last page was fetched: const options = { prepare: true , fetchSize: 1000 }; const result = await client.execute(query, parameters, options); // Property 'rows' will contain only the amount of items of the first page (max 1000 in this case) const rows = result.rows; // Store the page state let pageState = result.pageState; In the next request, use the `pageState` to fetch the following rows. // Use the pageState in the queryOptions to continue where you left it. const options = { pageState, prepare: true, fetchSize: 1000 }; const result = await client.execute(query, parameters, options); // Following rows up to fetch size (1000) const rows = result.rows; // Store the next paging state. pageState = result.pageState; Saving the paging state works well when you only let the user move from one page to the next. But it doesn’t allow arbitrary jumps (like “go directly to page 10”), because you can’t fetch a page unless you have the paging state of the previous one. Such a feature would require offset queries, which are not natively supported by Apache Cassandra. **Note**: The page state token can be manipulated to retrieve other results within the same column family, so it is not safe to expose it to the users in plain text. Row streams[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/paging/index.html#row-streams) --------------------------------------------------------------------------------------------------------------- If you want to handle a large result set as a [`Stream`](https://nodejs.org/api/stream.html) of rows, you can use `stream()` method of the `Client` instance. The `stream()` method automatically fetches the following pages, yielding the rows as they come through the network and retrieving the following page only after the previous rows were read (throttling). client.stream(query, parameters, options) .on('readable', function () { // readable is emitted as soon a row is received and parsed let row; while (row = this.read()) { // process row } }) .on('end', function () { // emitted when all rows have been retrieved and read }); --- # DataStax Node.js Driver - Batch statements [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/batch/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/batch/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/batch/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/batch/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/batch/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/batch/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/batch/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/batch/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/batch/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/batch/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/batch/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/batch/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/batch/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/batch/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/batch/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/batch/) * Batch statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/batch/index.html#batch-statements) ------------------------------------------------------------------------------------------------------------------------ It’s common for applications to require atomic batching of multiple `INSERT`, `UPDATE`, or `DELETE` statements, even in different partitions or column families. Thanks to the Cassandra protocol changes introduced in Cassandra 2.0, the driver allows you to execute multiple statements efficiently without the need to concatenate multiple queries. The method `batch()` accepts the queries as first parameter: const query1 = 'UPDATE user_profiles SET email = ? WHERE key = ?'; const query2 = 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)'; const queries = [\ { query: query1, params: [emailAddress, 'hendrix'] },\ { query: query2, params: ['hendrix', 'Changed email', new Date()] } \ ]; // Promise-based call client.batch(queries, { prepare: true }) .then(function() { // All queries have been executed successfully }) .catch(function(err) { // None of the changes have been applied }); Or using the callback-based invocation client.batch(queries, { prepare: true }, function (err) { // All queries have been executed successfully // Or none of the changes have been applied, check err }); By preparing your queries, you will get the best performance and your JavaScript parameters correctly mapped to Cassandra types. The driver will prepare each query once on each host and execute the batch every time with the different parameters provided. Note that Cassandra batches are not suitable for bulk loading, there are dedicated tools for that. Batches allow you to group related updates in a single request, so keep the batch size small (in the order of tens). Starting from Cassandra version 2.0.8, the server issues a warning if the batch size is greater than 5K. Refer to [CQL documentation](https://docs.datastax.com/en/cql/3.3/cql/cql_using/useBatchTOC.html) for information about correct and incorrect use of batches. --- # DataStax Node.js Driver - CQL data types to JavaScript types [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/datatypes/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/datatypes/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/datatypes/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/datatypes/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/datatypes/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/datatypes/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/datatypes/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/datatypes/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/datatypes/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/datatypes/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/datatypes/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/datatypes/) * CQL data types to JavaScript types[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/index.html#cql-data-types-to-java-script-types) ================================================================================================================================================================= When retrieving the value of a column from a `Row` object, the value is typed according to the following table. | CQL data type | JavaScript type | | --- | --- | | ascii | String | | bigint | [Long / BigInt](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) | | blob | [Buffer](https://nodejs.org/api/buffer.html) | | boolean | Boolean | | counter | [Long / BigInt](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) | | date | [LocalDate](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/datetime) | | decimal | [BigDecimal](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) | | double | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) | | duration | [Duration](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.Duration/) | | float | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) | | inet | [InetAddress](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.InetAddress/) | | int | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) | | list | [Array](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/collections) | | map | [Object / ECMAScript 6 Map](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/collections) | | set | [Array / ECMAScript 6 Set](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/collections) | | smallint | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) | | text | String | | time | [LocalTime](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/datetime) | | timestamp | [Date](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/datetime) | | timeuuid | [TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/uuids) | | tinyint | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) | | tuple | [Tuple](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/tuples) | | uuid | [Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/uuids) | | varchar | String | | varint | [Integer](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) | Encoding data[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/index.html#encoding-data) ---------------------------------------------------------------------------------------------------------------------- When encoding data, on a normal execute with parameters, the driver tries to guess the target type based on the input type. Values of type `Number` will be encoded as `double` (because `Number` is IEEE 754 double). Consider the following example: const key = 1000; client.execute('SELECT * FROM table1 where key = ?', [ key ]); If the key column is of type `int`, the execution fails. There are two possible ways to avoid this type of problem, as detailed below. ### Prepare your queries (recommended)[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/index.html#prepare-your-queries-recommended) Using prepared statements provides multiple benefits. Prepared statements are parsed and prepared on the Cassandra nodes and are ready for future execution. Also, the driver retrieves information about the parameter types which allows an **accurate mapping between a JavaScript type and a Cassandra type**. Using the previous example, setting the `prepare` flag in the queryOptions will fix it: // Prepare the query before execution client.execute('SELECT * FROM table1 where key = ?', [ key ], { prepare : true }); When using prepared statements, the driver prepares the statement once on each host to execute multiple times. ### Hinting the target data type[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/index.html#hinting-the-target-data-type) Providing parameter hints in the query options is another way around it. // Hint that the first parameter is an integer client.execute('SELECT * FROM table1 where key = ?', [ key ], { hints : ['int'] }); --- # DataStax Node.js Driver - Client [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.Client/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.Client/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.Client/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.Client/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.Client/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.Client/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.Client/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.Client/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.Client/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.Client/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.Client/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.Client/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.Client/) * class Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#class-client) ================================================================================================================== Represents a database client that maintains multiple connections to the cluster nodes, providing methods to execute CQL statements. The `Client` uses `[policies](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/) ` to decide which nodes to connect to, which node to use per each query execution, when it should retry failed or timed-out executions and how reconnection to down nodes should be made. Global This class is global Augments[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#augments) ---------------------------------------------------------------------------------------------------------- * `[EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) ` Events[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#events) ------------------------------------------------------------------------------------------------------ ### hostAdd[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#host-add) Emitted when a new host is added to the cluster. * `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` The host being added. ### hostDown[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#host-down) Emitted when a host in the cluster changed status from up to down. * `[host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` The host that changed the status. ### hostRemove[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#host-remove) Emitted when a host is removed from the cluster * `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` The host being removed. ### hostUp[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#host-up) Emitted when a host in the cluster changed status from down to up. * `[host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` The host that changed the status. Members[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#members) -------------------------------------------------------------------------------------------------------- `[HostMap](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/) ` ### hosts[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#hosts) Gets an associative array of cluster hosts. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### keyspace[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#keyspace) Gets the name of the active keyspace. `Metadata` ### metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#metadata) Gets the schema and cluster metadata information. `ClientMetrics` ### metrics[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#metrics) The `[ClientMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/interface.ClientMetrics/) ` instance used to expose measurements of its internal behavior and of the server as seen from the driver side. By default, a `[DefaultMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/class.DefaultMetrics/) ` instance is used. Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#constructor) ---------------------------------------------------------------------------------------------------------------- new ### Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#client) (`[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) ` options) Creates a new instance of `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) `. Examples: Creating a new client instance const client = new Client({ contactPoints: ['10.0.1.101', '10.0.1.102'], localDataCenter: 'datacenter1' }); Executing a query const result = await client.connect(); console.log(`Connected to ${client.hosts.length} nodes in the cluster: ${client.hosts.keys().join(', ')}`); Executing a query const result = await client.execute('SELECT key FROM system.local'); const row = result.first(); console.log(row['key']); Parameters: | Name | Type | Description | | --- | --- | --- | | options | `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) ` | The options for this instance. | Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#methods) -------------------------------------------------------------------------------------------------------- ### batch[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#batch) (`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<{query, params}\> queries, \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` options\], \[`[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ResultCallback/) ` callback\]) Executes batch of queries on an available connection to a host. It returns a `Promise` when a `callback` is not provided. Parameters: | Name | Type | Description | | --- | --- | --- | | queries | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` | The query options. | | callback optional | `[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ResultCallback/) ` | Executes callback(err, result) when the batch was executed | ### connect[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#connect) (\[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Attempts to connect to one of the `[contactPoints](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) ` and discovers the rest the nodes of the cluster. When the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` is already connected, it resolves immediately. It returns a `Promise` when a `callback` is not provided. Examples: Usage example await client.connect(); Parameters: | Name | Type | Description | | --- | --- | --- | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | The optional callback that is invoked when the pool is connected or it failed to connect. | ### eachRow[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#each-row) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params\], \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` options\], `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` rowCallback, \[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Executes the query and calls `rowCallback` for each row as soon as they are received. Calls the final `callback` after all rows have been sent, or when there is an error. The query can be prepared (recommended) or not depending on the `[prepare](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` flag. 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); Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The query to execute | | params optional | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Array of parameter values or an associative array (object) containing parameter names as keys and its value. | | options optional | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` | The query options. | | rowCallback | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Executes `rowCallback(n, row)` per each row received, where n is the row index and row is the current Row. | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Executes `callback(err, result)` after all rows have been received.

When dealing with paged results, `[ResultSet#nextPage()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.ResultSet/#member.next-page) ` 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. | ### execute[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#execute) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params\], \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` options\], \[`[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ResultCallback/) ` callback\]) Executes a query on an available connection. The query can be prepared (recommended) or not depending on the `[prepare](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` flag. Some execution failures can be handled transparently by the driver, according to the `[RetryPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.retry/class.RetryPolicy/) ` or the `[SpeculativeExecutionPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.speculativeExecution/) ` used. It returns a `Promise` when a `callback` is not provided. Examples: 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']); 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']); }); Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The query to execute. | | params optional | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Array of parameter values or an associative array (object) containing parameter names as keys and its value. | | options optional | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` | The query options for the execution. | | callback optional | `[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ResultCallback/) ` | Executes callback(err, result) when execution completed. When not defined, the method will return a promise. | ### executeGraph[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#execute-graph) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` parameters\], \[`GraphQueryOptions` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` options\], \[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Executes a graph query. It returns a `Promise` when a `callback` is not provided. 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 client.executeGraph('g.V()', (err, result) => { const vertex = result.first(); console.log(vertex.label); }); Iterating through the results const result = await client.executeGraph('g.E()'); for (let edge of result) { console.log(edge.label); // created }); 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 }); Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The gremlin query. | | parameters optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` | An associative array containing the key and values of the parameters. | | options optional | `GraphQueryOptions` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` | The graph query options. | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Function to execute when the response is retrieved, taking two arguments: `err` and `result`. When not defined, the method will return a promise. | ### getReplicas[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#get-replicas) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` keyspace, `Buffer` token) Gets the host that are replicas of a given token. Parameters: | Name | Type | Description | | --- | --- | --- | | keyspace | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | | token | `Buffer` | | Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) `\> | | ### getState[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#get-state) () Gets a snapshot containing information on the connections pools held by this Client at the current time. The information provided in the returned object only represents the state at the moment this method was called and it’s not maintained in sync with the driver metadata. Returns: | Type | Description | | --- | --- | | `ClientState` | A `[ClientState](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/class.ClientState/) ` instance. | ### shutdown[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#shutdown) (\[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Closes all connections to all hosts. It returns a `Promise` when a `callback` is not provided. Parameters: | Name | Type | Description | | --- | --- | --- | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Optional callback to be invoked when finished closing all connections. | ### stream[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/index.html#stream) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params\], \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` options\], \[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Executes the query and pushes the rows to the result stream as soon as they received. The stream is a `ReadableStream` object that emits rows. 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](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) `.prepare flag. Retries on multiple hosts if needed. Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The query to prepare and execute. | | params optional | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Array of parameter values or an associative array (object) containing parameter names as keys and its value | | options optional | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` | The query options. | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | executes callback(err) after all rows have been received or if there is an error | Returns: | Type | Description | | --- | --- | | `ResultStream` | | --- # DataStax Node.js Driver - Host [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.Host/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.Host/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.Host/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.Host/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.Host/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.Host/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.Host/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.Host/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.Host/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.Host/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.Host/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.Host/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.Host/) * class Host[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#class-host) ============================================================================================================ Represents a Cassandra node. Global This class is global Augments[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#augments) -------------------------------------------------------------------------------------------------------- * `[EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) ` Members[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#members) ------------------------------------------------------------------------------------------------------ `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### address[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#address) Gets ip address and port number of the node separated by `:`. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### cassandraVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#cassandra-version) Gets string containing the Cassandra version. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### datacenter[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#datacenter) Gets data center name of the node. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### dseVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#dse-version) Gets string containing the DSE version or null if not set. `Uuid` ### hostId[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#host-id) Gets the id of the host. This identifier is used by the server for internal communication / gossip. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### rack[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#rack) Gets rack name of the node. `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` ### tokens[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#tokens) Gets the tokens assigned to the node. `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> ### workloads[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#workloads) Gets the DSE Workloads the host is running. This is based on the “workload” or “workloads” columns in {@code system.local} and {@code system.peers}. Workload labels may vary depending on the DSE version in use;e.g. DSE 5.1 may report two distinct workloads: `Search` and `Analytics`, while DSE 5.0 would report a single `SearchAnalytics` workload instead. The driver simply returns the workload labels as reported by DSE, without any form of pre-processing. When the information is unavailable, this property returns an empty array. Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#constructor) -------------------------------------------------------------------------------------------------------------- new ### Host[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#host) () Creates a new Host instance. Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#methods) ------------------------------------------------------------------------------------------------------ ### canBeConsideredAsUp[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#can-beconsidered-asup) () Determines if the host can be considered as UP. Deprecated: Use `Host#isUp()` instead. Returns: | Type | Description | | --- | --- | | `boolean` | | ### getCassandraVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#get-cassandra-version) () Returns an array containing the Cassandra Version as an Array of Numbers having the major version in the first position. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) `\> | | ### getDseVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#get-dse-version) () Gets the DSE version of the host as an Array, containing the major version in the first position. In case the cluster is not a DSE cluster, it returns an empty Array. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | | ### isUp[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/index.html#is-up) () Determines if the node is UP now (seen as UP by the driver). Returns: | Type | Description | | --- | --- | | `boolean` | | --- # DataStax Node.js Driver - ExecutionProfile [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.ExecutionProfile/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.ExecutionProfile/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.ExecutionProfile/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.ExecutionProfile/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.ExecutionProfile/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.ExecutionProfile/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.ExecutionProfile/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.ExecutionProfile/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.ExecutionProfile/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.ExecutionProfile/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.ExecutionProfile/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.ExecutionProfile/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * class ExecutionProfile[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#class-execution-profile) ================================================================================================================================================= Represents a set configurations to be used in a statement execution to be used for a single `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` instance. An `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) ` instance should not be shared across different `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` instances. Global This class is global Members[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#members) ------------------------------------------------------------------------------------------------------------------ `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` ### consistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#consistency) Consistency level. `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` ### graphOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#graph-options) The graph options for this profile. Properties: | Name | Type | Description | | --- | --- | --- | | language | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph language. | | name | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph name. | | readConsistency | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The consistency to use for graph write queries. | | source | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph traversal source. | | writeConsistency | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The consistency to use for graph write queries. | `LoadBalancingPolicy` ### loadBalancing[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#load-balancing) Load-balancing policy `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### name[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#name) Name of the execution profile. `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` ### readTimeout[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#read-timeout) Client read timeout. `RetryPolicy` ### retry[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#retry) Retry policy. `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` ### serialConsistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#serial-consistency) Serial consistency level. Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#constructor) -------------------------------------------------------------------------------------------------------------------------- new ### ExecutionProfile[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/index.html#execution-profile) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` name, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` options\]) Creates a new instance of `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) `. Examples: const { Client, ExecutionProfile } = require('cassandra-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], profiles: [\ new ExecutionProfile('metrics-oltp', {\ consistency: consistency.localQuorum,\ retry: myRetryPolicy\ })\ ] }); client.execute(query, params, { executionProfile: 'metrics-oltp' }, callback); Parameters: | Name | Type | Description | | --- | --- | --- | | name | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Name of the execution profile.

Use `'default'` to specify that the new instance should be the default `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) ` if no profile is specified in the execution. | | options optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Profile options, when any of the options is not specified the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` will the use the ones defined in the default profile. | | options.consistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The consistency level to use for this profile. | | options.loadBalancing optional | `LoadBalancingPolicy` | The load-balancing policy to use for this profile. | | options.readTimeout optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The client per-host request timeout to use for this profile. | | options.retry optional | `RetryPolicy` | The retry policy to use for this profile. | | options.serialConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The serial consistency level to use for this profile. | | options.graphOptions optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | options.graphOptions.language optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph language to use for graph queries.

Note that this setting should normally be `undefined` or set by a utility method and it’s not expected to be defined manually by the user. | | options.graphOptions.results optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The protocol to use for serializing and deserializing graph results.

Note that this setting should normally be `undefined` or set by a utility method and it’s not expected to be defined manually by the user. | | options.graphOptions.name optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph name to use for graph queries. | | options.graphOptions.readConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The consistency level to use for graph read queries. | | options.graphOptions.source optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph traversal source name to use for graph queries. | | options.graphOptions.writeConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The consistency level to use for graph write queries. | | options.loadBalancing optional | `LoadBalancingPolicy` | The load-balancing policy to use for this profile. | | options.readTimeout optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The client per-host request timeout to use for this profile. | | options.retry optional | `RetryPolicy` | The retry policy to use for this profile. | | options.serialConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The serial consistency level to use for this profile. | --- # DataStax Node.js Driver - Query warnings [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-warnings/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-warnings/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-warnings/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-warnings/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/query-warnings/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/query-warnings/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/query-warnings/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/query-warnings/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/query-warnings/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/query-warnings/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/query-warnings/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/query-warnings/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/query-warnings/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/query-warnings/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/query-warnings/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/query-warnings/) * Query warnings[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-warnings/index.html#query-warnings) ============================================================================================================================= When a query is considered to be harmful for the overall cluster, Cassandra issues a warning that is written to the Cassandra logs. From Cassandra 2.2, [these warnings are also returned to the client drivers](https://issues.apache.org/jira/browse/CASSANDRA-8930) . In the driver, these warnings are [returned in the ResultSet property information](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.ResultSet/) . The warning is still written to the [driver logs](https://docs.datastax.com/en/developer/nodejs-driver/4.6/#logging) . --- # DataStax Node.js Driver - mapping [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.mapping/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.mapping/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.mapping/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.mapping/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.mapping/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.mapping/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module mapping[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/index.html#module-mapping) ======================================================================================================================== Module containing classes and fields related to the Mapper. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/index.html#classes) ---------------------------------------------------------------------------------------------------------- * `[Mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/class.Mapper/) ` * `[ModelBatchItem](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/class.ModelBatchItem/) ` * `[ModelMapper](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/class.ModelMapper/) ` * `[Result](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/class.Result/) ` * `[UnderscoreCqlToCamelCaseMappings](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/class.UnderscoreCqlToCamelCaseMappings/) ` * `[DefaultTableMappings](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/class.DefaultTableMappings/) ` Interfaces[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/index.html#interfaces) ---------------------------------------------------------------------------------------------------------------- * `[TableMappings](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/interface.TableMappings/) ` Types[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/index.html#types) ------------------------------------------------------------------------------------------------------ * `[MappingOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/type.MappingOptions/) ` * `[ModelOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/type.ModelOptions/) ` Constants[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/index.html#constants) -------------------------------------------------------------------------------------------------------------- ### q[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/index.html#q) Contains functions that represents operators in a query. Properties: | Name | Type | Description | | --- | --- | --- | | in\_ | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator “IN”. | | gt | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator greater than “>”. | | gte | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator greater than or equals to “>=” . | | lt | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator less than “<” . | | lte | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator less than or equals to “<=” . | | notEq | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator not equals to “!=” . | | and | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | When applied to a property, it represents two CQL conditions on the same column separated by the logical AND operator, e.g: “col1 >= x col < y” | | incr | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL increment assignment used for counters, e.g: “col = col + x” | | decr | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL decrement assignment used for counters, e.g: “col = col - x” | | append | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL append assignment used for collections, e.g: “col = col + x” | | prepend | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL prepend assignment used for lists, e.g: “col = x + col” | | remove | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL remove assignment used for collections, e.g: “col = col - x” | --- # DataStax Node.js Driver - Query timestamps [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/query-timestamps/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/query-timestamps/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/query-timestamps/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/query-timestamps/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/query-timestamps/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/query-timestamps/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/query-timestamps/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/query-timestamps/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/query-timestamps/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/query-timestamps/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Query timestamps[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/index.html#query-timestamps) =================================================================================================================================== In Cassandra, each mutation has a microsecond-precision timestamp, which is used to order operations relative to each other. The timestamp can be provided by the client or assigned server-side based on the time the server processes the request. Letting the server assign the timestamp can be a problem when the order of the writes matter: with unlucky timing (different coordinators, network latency, etc.), two successive requests from the same client might be processed in a different order server-side, and end up with out-of-order timestamps. Client-side generation[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/index.html#client-side-generation) ----------------------------------------------------------------------------------------------------------------------------------------------- ### Using a timestamp generator[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/index.html#using-a-timestamp-generator) The operation timestamp can be sent as part of the request. The driver uses [`MonotonicTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) by default to generate the request timestamps. You can provide a different generator when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, policies: { timestampGeneration: new MyCustomTimestampGenerator() } }); To implement a custom timestamp generator, you must implement `TimestampGenerator` base class. In addition, you can also set the default timestamp on a per-execution basis in the query options: session.execute(query, params, { timestamp: timestamp }); #### Accuracy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/index.html#accuracy) As defined by ECMAScript, the `Date` object has millisecond resolution. The [`MononoticTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) uses a incremental counter to generate the sub-millisecond part of the timestamp until the next clock tick. #### Monotonicity[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/index.html#monotonicity) The [`MononoticTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) implementation also guarantees that the returned timestamps will always be monotonically increasing, even if multiple updates happen under the same millisecond. Note that to guarantee such monotonicity, if more than one thousand timestamps are generated within the same millisecond, or in the event of a system clock skew, the implementation might return timestamps that drift out into the future. When this happens, the built-in generator logs a periodic warning message. See their non-default constructors for ways to control the warning interval. ### Provide the timestamp in the query[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/index.html#provide-the-timestamp-in-the-query) Alternatively, if you are using an old server version, you can explicitly provide the timestamp in your CQL query (not recommended): client.execute('INSERT INTO my_table(c1, c2) VALUES (1, 1) USING TIMESTAMP 1482156745633040'); --- # DataStax Node.js Driver - API docs [DataStax Node.js Driver 4.8 (Latest version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.8 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/) * API documentation[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#api-documentation) =============================================================================================================== Top level objects Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#modules) ------------------------------------------------------------------------------------------- * `[geometry](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/) ` * `[datastax](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.datastax/) ` * `[types](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/) ` * `[auth](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/) ` * `[policies](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/) ` * `[mapping](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/) ` * `[metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/) ` * `[concurrent](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.concurrent/) ` * `[errors](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/) ` * `[tracker](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.tracker/) ` * `[metrics](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/) ` Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#classes) ------------------------------------------------------------------------------------------- * `[TransitionalModePlainTextAuthenticator](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.TransitionalModePlainTextAuthenticator/) ` * `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) ` * `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) ` * `[ExecutionOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/) ` * `[Encoder](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/) ` * `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) ` * `[HostMap](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/) ` Types[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#types) --------------------------------------------------------------------------------------- * `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) ` * `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) ` * `[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ResultCallback/) ` Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#functions) ----------------------------------------------------------------------------------------------- ### \_parseUdtName[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#parse-udt-name) (`string` typeName, `number` startIndex, `number` length) Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | typeName | `string` | | | startIndex | `number` | | | length | `number` | | Returns: | Type | Description | | --- | --- | | `UdtColumnInfo` | | ### decodeCustom[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#decode-custom) (`Buffer` bytes, `OtherCustomColumnInfo` or `VectorColumnInfo` columnInfo) Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | bytes | `Buffer` | | | columnInfo | `OtherCustomColumnInfo` or `VectorColumnInfo` | | ### decodeVector[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#decode-vector) (`Buffer` buffer, `VectorColumnInfo` params) Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | buffer | `Buffer` | | | params | `VectorColumnInfo` | | Returns: | Type | Description | | --- | --- | | `Vector` | | ### encodeCustom[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#encode-custom) (`any` value, `OtherCustomColumnInfo` or `VectorColumnInfo` columnInfo) Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | value | `any` | | | columnInfo | `OtherCustomColumnInfo` or `VectorColumnInfo` | | ### encodeTuple[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#encode-tuple) (`any` value, `TupleColumnInfo` columnInfo) Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | value | `any` | | | columnInfo | `TupleColumnInfo` | | ### encodeUdt[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#encode-udt) (`any` value, `UdtColumnInfo` columnInfo) Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | value | `any` | | | columnInfo | `UdtColumnInfo` | | ### encodeVector[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#encode-vector) (`Vector` value, `VectorColumnInfo` params) Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | value | `Vector` | | | params | `VectorColumnInfo` | | Returns: | Type | Description | | --- | --- | | `Buffer` | | ### parseVectorTypeArgs[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#parse-vector-type-args) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` typeName, `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` stringToExclude, `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` subtypeResolveFn) Extract the (typed) arguments from a vector type Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | typeName | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | | stringToExclude | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Leading string indicating this is a vector type (to be excluded when eval’ing args) | | subtypeResolveFn | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Function used to resolve subtype type; varies depending on type naming convention | Returns: | Type | Description | | --- | --- | | `VectorColumnInfo` | | ### serializationSizeIfFixed[](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/index.html#serialization-size-iffixed) (`ColumnInfo` cqlType) Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | cqlType | `ColumnInfo` | | Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | --- # DataStax Node.js Driver - Geospatial types [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/geotypes/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/geotypes/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/geotypes/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/geotypes/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/geotypes/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Geospatial types[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/geotypes/index.html#geospatial-types) --------------------------------------------------------------------------------------------------------------------------- [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) comes with a set of additional CQL types to represent geospatial data: * `PointType` * `LineStringType` * `PolygonType`. cqlsh> CREATE TABLE points_of_interest(name text PRIMARY KEY, coords 'PointType'); cqlsh> INSERT INTO points_of_interest (name, coords) VALUES ('Eiffel Tower', 'POINT(48.8582 2.2945)'); The driver includes encoders and representations of these types in the `geometry` module that can be used directly as parameters in queries. All Javascript geospatial types implement `toString()`, that returns the string representation in [Well-known text](https://en.wikipedia.org/wiki/Well-known_text) format, and `toJSON()`, that returns the JSON representation in [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) format. Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/geotypes/index.html#usage) ----------------------------------------------------------------------------------------------------- const cassandra = require('cassandra-driver'); const Point = cassandra.geometry.Point; const insertQuery = 'INSERT INTO points_of_interest (name, coords) VALUES (?, ?)'; const selectQuery = 'SELECT coords FROM points_of_interest WHERE name = ?'; await client.execute(insertQuery, [ 'Eiffel Tower', new Point(48.8582, 2.2945) ]); const result = await client.execute(selectQuery, [ 'Eiffel Tower' ]); const row = result.first(); const point = row['coords']; console.log(point instanceof Point); // true console.log('x: %d, y: %d', point.x, point.y); // x: 48.8582, y: 2.2945 console.log(point.toString()); // 'POINT (48.8582 2.2945)' --- # DataStax Node.js Driver - Speculative query execution [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/speculative-executions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/speculative-executions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/speculative-executions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/speculative-executions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/speculative-executions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/speculative-executions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/speculative-executions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/speculative-executions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/speculative-executions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Speculative query execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/index.html#speculative-query-execution) =============================================================================================================================================================== Sometimes a server node might be experiencing difficulties (for example, long GC pause) and take longer than usual to reply. Queries sent to that node experience higher latencies than expected. One thing we can do to improve that is preemptively start a second execution of the query against another node, before the first node has replied or errored out. If that second node replies faster, we can send the response back to the client (we also cancel the first query): ![Text Diagram]() Or the first node could reply just after the second execution was started. In this case, we cancel the second execution. In other words, whichever node replies faster wins and completes the client query: ![Text Diagram]() Note that “cancelling” in this context simply means marking the operation to discard the response when it later arrives. Speculative executions are disabled by default. The following sections cover the practical details and how to enable them. Query idempotence[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/index.html#query-idempotence) ------------------------------------------------------------------------------------------------------------------------------------------- One important aspect to consider is whether queries are idempotent, (that is, whether they can be applied multiple times without changing the result beyond the initial application). If a query is not idempotent, the driver never schedules speculative executions for it, because there is no way to guarantee that only one node will apply the mutation. Examples of queries that are not idempotent are: * counter operations * prepending or appending to a list column * using non-idempotent CQL functions, like `now()` or `uuid()` In the driver, this is determined by [`isIdempotent` flag in the `QueryOptions`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) . Because the driver does not parse query strings, in most cases it has no information about what the query actually does. Therefore, for all other types of statements, it defaults to `false`. You must set it manually with one of the mechanisms described below. You can override the value for each execution: const query = 'SELECT * FROM users WHERE key = ?'; client.execute(query, [ 'usr1' ], { prepare: true, isIdempotent: true }); Additionally, if you know for a fact that your application does not use any of the non-idempotent CQL queries listed above, you can change the default cluster-wide: // Make all statements idempotent by default: const client = new Client({ contactPoints, localDataCenter, queryOptions: { isIdempotent: true } }); Enabling speculative execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/index.html#enabling-speculative-execution) --------------------------------------------------------------------------------------------------------------------------------------------------------------------- Speculative executions are controlled by an instance of `SpeculativeExecutionPolicy` provided when initializing the `Client`. This policy defines the threshold after which a new speculative execution is triggered. The driver provides a `ConstantSpeculativeExecutionPolicy` that schedules a given number of speculative executions, separated by a fixed delay, the policy is exported under the `.policies.speculativeExecution` module. This simple policy uses a constant threshold: const { Client, policies } = require('cassandra-driver'); const ConstantSpeculativeExecutionPolicy = policies.speculativeExecution.ConstantSpeculativeExecutionPolicy; const client = new Client({ contactPoints, policies: { speculativeExecution: new ConstantSpeculativeExecutionPolicy( 200, // delay before a new execution is launched 2) // maximum amount of additional executions } }); Given the configuration above, an idempotent query would be handled this way: * start the initial execution at t0 * if no response has been received at t0 + 200 milliseconds, start a speculative execution on another node * if no response has been received at t0 + 400 milliseconds, start another speculative execution on a third node As with the rest of policies in the driver, you can provide your own implementation by extending the `SpeculativeExecutionPolicy` prototype. How speculative executions affect retries[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/index.html#how-speculative-executions-affect-retries) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Regardless of speculative executions, the driver has a retry mechanism: * on an internal error, it will try the next host * if the consistency level cannot be reached (for example, unavailable error or read or write timeout), it delegates the decision to the `RetryPolicy`, which might trigger a retry on the same host Turning speculative executions on does not change this behavior. Each parallel execution trigger retries independently: ![Text Diagram]() The only impact is that all executions of the same query always share the same query plan, so each host is used by at most one execution. Tuning and practical details[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/index.html#tuning-and-practical-details) ----------------------------------------------------------------------------------------------------------------------------------------------------------------- The goal of speculative executions is to improve overall latency (the time between `execute(query)` and `complete` in the diagrams above) at high percentiles. On the flipside, they cause the driver to send more individual requests, so throughput does not necessarily improve. One side-effect of speculative executions is that many requests are cancelled, which can lead to a phenomenon called stream id exhaustion: each TCP connection can handle multiple simultaneous requests, identified by a unique number called stream id. When a request gets cancelled, we can’t reuse its stream id immediately because we might still receive a response from the server later. If this happens often, the number of available stream ids diminishes over time, and when it goes below a given threshold we close the connection and create a new one. If requests are often cancelled, so will see connections being recycled at a high rate. This problem is more likely to happen with old server versions (Apache Cassandra version 2.0 or below and DSE 4.6 or below) which only support version 1 and 2 of the native protocol where each TCP connection only has 128 available stream ids. With modern server versions, there are 32K stream ids per connection, so higher cancellation rates can be sustained. Another issue that might arise is that you get unintuitive results because of request ordering. Suppose you run the following query with speculative executions enabled: insert into my_table (k, v) values (1, 1); The first execution is a bit too slow, so a second execution gets triggered. Finally, the first execution completes, so the client code gets back an acknowledgement, and the second execution is cancelled. However, cancelling only means that the driver stops waiting for the server’s response, the request could still be on the wire; let us assume that this is the case. Now you run the following query, which completes successfully: delete from my_table where k = 1; But now the second execution of the first query finally reaches its target node, which applies the mutation. The row that you’ve just deleted is back! **Using [query timestamps](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps) **, which are enabled by default, prevents this issue to appear as each request will have a client-level timestamp which will define the order to apply the mutations. --- # DataStax Node.js Driver - Connection pooling [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/connection-pooling/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/connection-pooling/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/connection-pooling/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/connection-pooling/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/connection-pooling/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/connection-pooling/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/connection-pooling/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/connection-pooling/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/connection-pooling/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/connection-pooling/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/connection-pooling/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/connection-pooling/) * Connection pooling[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling/index.html#connection-pooling) ========================================================================================================================================= The driver maintains one or more connections opened to each Apache Cassandra node selected by the load-balancing policy. The amount of connections per host is defined in the pooling configuration. Default pooling configuration[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling/index.html#default-pooling-configuration) --------------------------------------------------------------------------------------------------------------------------------------------------------------- The default number of connections per host depends on the version of the Apache Cassandra cluster. When using the driver to connect to modern server versions (Apache Cassandra 2.1 and above), the driver uses one connection per host. Setting the number of connections per host[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling/index.html#setting-the-number-of-connections-per-host) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If needed, you can set the number of connections per host depending on the distance, relative to the driver instance, in the `pooling` configuration: const cassandra = require('cassandra-driver'); const distance = cassandra.types.distance; const options = { contactPoints, localDataCenter, pooling: { coreConnectionsPerHost: { [distance.local]: 2, [distance.remote]: 1 } } }; const client = new Client(options); Simultaneous requests per connection[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling/index.html#simultaneous-requests-per-connection) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The driver limits the amount of concurrent requests per connection to `2048` with modern protocol versions and `128` with older versions of the protocol (v1 and v2). You can throttle requests by setting the `maxRequestsPerConnection` value in the `poolingOptions`. When the limit is reached for all connections to a host, the driver will move to the next host according to the query plan. When the query plan is exhausted, the driver will yield a `NoHostAvailableError` containing `BusyConnectionError` instances per each host in the `innerErrors` property. Get status of the connection pool[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling/index.html#get-status-of-the-connection-pool) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can use `getState()` method to get a point-in-time information of the state of the connections pools to each host. const state = client.getState(); for (let host of state.getConnectedHosts()) { console.log('Host %s: open connections = %d; in flight queries = %d', host.address, state.getOpenConnections(host), state.getInFlightQueries(host)); } --- # DataStax Node.js Driver - Native protocol [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/native-protocol/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/native-protocol/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/native-protocol/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/native-protocol/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/native-protocol/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/native-protocol/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/native-protocol/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/native-protocol/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/native-protocol/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/native-protocol/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/native-protocol/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/native-protocol/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/native-protocol/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/native-protocol/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/native-protocol/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/native-protocol/) * Native protocol[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/native-protocol/index.html#native-protocol) ================================================================================================================================ The native protocol defines the format of the binary messages exchanged between the driver and Cassandra over TCP. As a driver user what you need to be aware of is that some Cassandra features are only available with a specific protocol version, but if you are interested in the technical details you can check [the specification in the Cassandra codebase](https://git-wip-us.apache.org/repos/asf?p=cassandra.git;a=tree;f=doc;hb=HEAD) . Controlling the protocol version[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/native-protocol/index.html#controlling-the-protocol-version) ------------------------------------------------------------------------------------------------------------------------------------------------------------------ By default, the driver uses the highest protocol version supported by the driver and the Cassandra cluster. If you want to limit the protocol version to use, you do so in the protocol options. const cassandra = require('cassandra-driver'); const protocolVersion = cassandra.types.protocolVersion; const client = new cassandra.Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.v3 } }); Mixed cluster versions and rolling upgrades[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/native-protocol/index.html#mixed-cluster-versions-and-rolling-upgrades) ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The protocol version used between the client and the Cassandra cluster is negotiated upon establishing the first connection. For clusters with nodes running mixed versions of Cassandra and during rolling upgrades this could represent an issue that could lead to limited availability. To exemplify the above, consider a mixed cluster having nodes running either Cassandra 2.1 or 2.0. * The first contact point is a 2.1 host, so the driver negotiates native protocol version 3 * While connecting to the rest of the cluster, the driver contacts a 2.0 host using native protocol version 3, which fails; an error is logged and this host will be permanently ignored. For these scenarios, mixed version clusters and rolling upgrades, it is strongly recommended to set the maximum protocol version when initializing the client: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.v2 } }); And switching it to the highest protocol version once the upgrade is completed, by leaving the maximum protocol version unspecified or by using `protocolVersion.maxSupported`: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.maxSupported } }); --- # DataStax Node.js Driver - Parameterized queries [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/parameterized-queries/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/parameterized-queries/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/parameterized-queries/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/parameterized-queries/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/parameterized-queries/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/parameterized-queries/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/parameterized-queries/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/parameterized-queries/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/parameterized-queries/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/parameterized-queries/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/parameterized-queries/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/parameterized-queries/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/parameterized-queries/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/parameterized-queries/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/parameterized-queries/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/parameterized-queries/) * Parameterized queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/parameterized-queries/index.html#parameterized-queries) ================================================================================================================================================== You can bind the values of parameters in a prepared statement either by position or by using named markers. Positional parameterized query[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/parameterized-queries/index.html#positional-parameterized-query) -------------------------------------------------------------------------------------------------------------------------------------------------------------------- When using positional parameters, the query parameters must be provided as an Array. const query = 'INSERT INTO artists (id, name) VALUES (?, ?)'; // Parameters by marker position const params = ['krichards', 'Keith Richards']; client.execute(query, params, { prepare: true }); Named parameterized query[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/parameterized-queries/index.html#named-parameterized-query) ---------------------------------------------------------------------------------------------------------------------------------------------------------- You declare the named markers in your queries and use a JavaScript object properties to define the parameters, with the `Object` property names matching the parameters names. const query = 'INSERT INTO artists (id, name) VALUES (:id, :name)'; // Parameters by marker name const params = { id: 'krichards', name: 'Keith Richards' }; client.execute(query, params, { prepare: true }); Defining named markers in your queries is supported in Cassandra 2.0 or greater for prepared statements and Cassandra 2.1 or greater for non-prepared statements. --- # DataStax Node.js Driver - policies [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.policies/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.policies/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.policies/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.policies/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.policies/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.policies/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.policies/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.policies/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.policies/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.policies/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.policies/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.policies/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.policies/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.policies/) * module policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/index.html#module-policies) =========================================================================================================================== Contains driver tuning policies to determine `[load balancing](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.loadBalancing/) `, `[retrying](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.retry/) ` queries, `[reconnecting](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.reconnection/) ` to a node, `[address resolution](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.addressResolution/) `, `[timestamp generation](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.timestampGeneration/) ` and `[speculative execution](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.speculativeExecution/) `. Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/index.html#modules) ----------------------------------------------------------------------------------------------------------- * `[addressResolution](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.addressResolution/) ` * `[loadBalancing](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.loadBalancing/) ` * `[reconnection](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.reconnection/) ` * `[retry](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.retry/) ` * `[speculativeExecution](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.speculativeExecution/) ` * `[timestampGeneration](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.timestampGeneration/) ` Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/index.html#functions) --------------------------------------------------------------------------------------------------------------- ### policies.defaultAddressTranslator[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/index.html#default-address-translator) () Returns a new instance of the default address translator policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `AddressTranslator` | | ### policies.defaultLoadBalancingPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/index.html#default-load-balancing-policy) (\[`string` localDc\]) Returns a new instance of the default load-balancing policy used by the driver. Static This function is static Parameters: | Name | Type | Description | | --- | --- | --- | | localDc optional | `string` | When provided, it sets the data center that is going to be used as local for the load-balancing policy instance.

When localDc is undefined, the load-balancing policy instance will use the `localDataCenter` provided in the `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) `. | Returns: | Type | Description | | --- | --- | | `LoadBalancingPolicy` | | ### policies.defaultReconnectionPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/index.html#default-reconnection-policy) () Returns a new instance of the default reconnection policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `ReconnectionPolicy` | | ### policies.defaultRetryPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/index.html#default-retry-policy) () Returns a new instance of the default retry policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `RetryPolicy` | | ### policies.defaultSpeculativeExecutionPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/index.html#default-speculative-execution-policy) () Returns a new instance of the default speculative execution policy used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `SpeculativeExecutionPolicy` | | ### policies.defaultTimestampGenerator[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/index.html#default-timestamp-generator) () Returns a new instance of the default timestamp generator used by the driver. Static This function is static Returns: | Type | Description | | --- | --- | | `TimestampGenerator` | | --- # DataStax Node.js Driver - Graph support [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/graph-support/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Graph support[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/index.html#graph-support) ========================================================================================================================== `Client` includes the `executeGraph()` method to execute graph queries: const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'dc1', graphOptions: { name: 'demo' } }); // executeGraph() method returns a Promise client.executeGraph('g.V()') .then(function (result) { const vertex = result.first(); console.log(vertex.label); }); Alternatively, you can use the callback-based execution: client.executeGraph('g.V()', function (err, result) { assert.ifError(err); const vertex = result.first(); // ... }); Graph Options[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/index.html#graph-options) -------------------------------------------------------------------------------------------------------------------------- You can set default graph options when initializing `Client` which will be used for all graph statements. For example, to avoid providing a `graphName` option in each `executeGraph()` call: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'dc1', graphOptions: { name: 'demo' } }); These options may be overridden by specifying the [execution profile](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles) when calling `executeGraph()`: // Use a different graph name than the one provided when creating the client instance const result = await client.executeGraph(query, params, { executionProfile: 'graph-oltp' }); const vertex = result.first(); console.log(vertex.label); You can check out more info on [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles) . Handling Results[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/index.html#handling-results) -------------------------------------------------------------------------------------------------------------------------------- Graph queries return a `GraphResultSet`, which is an [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable) of items. The format of the data returned is dependent on the data requested. Retrieving property values: const result = await client.executeGraph('g.V().hasLabel("person").values("name")'); for (const name of result) { console.log(name); } Retrieving vertices: const result = await client.executeGraph('g.V().hasLabel("person")'); for (const vertex of result) { console.log(vertex.label); } Retrieving edges: const result = await client.executeGraph('g.E()'); for (const edge of result) { console.log(edge.label); } ### Parameters[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/index.html#parameters) Graph traversal execution supports named parameters. Parameters must be passed in as an object: const traversal = 'g.addV(vertexLabel).property("name", username)'; await client.executeGraph(traversal, { vertexLabel: 'person', username: 'marko' }); ### Graph types[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/index.html#graph-types) The DataStax Node.js driver supports a wide variety of TinkerPop types and [DSE types](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/) . For graph types that don’t have a native JavaScript representation, the driver provides the [`types` module](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/) . For example: const { types } = require('cassandra-driver'); const { Uuid, InetAddress } = types; const traversal = 'g.addV("sample").property("uid", uid).property("ip_address", address)'; await client.execute(traversal, { uid: Uuid.random(), address: InetAddress.fromString('10.0.0.100') }); The same types are also supported for traversal execution results: const rs = await client.execute('g.V().hasLabel("sample").values("ip_address")'); for (const ip of rs) { console.log(ip instanceof InetAddress); // true } #### User-defined types[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/index.html#user-defined-types) User-defined types (UDTs) are supported in the Node.js driver using JavaScript objects. const rs = await client.execute('g.V().hasLabel("sample").values("user_address")'); for (const address of rs) { console.log(`User address is ${address.street}, ${address.city} ${address.state}`); } In order to use a UDT as a parameter, you must wrap the object instance using `asUdt()` function to provide additional information to properly represent the UDT on the server. const { datastax } = require('cassandra-driver'); const { asUdt } = datastax.graph; // Get the UDT metadata const udtInfo = await client.metadata.getUdt(graphName, 'address'); // Build the UDT const address = asUdt({ street: '123 Priam St.', city: 'My City', state: 'MY' }, udtInfo); const traversal = 'g.addV("sample").property("uid", uid).property("user_address", address)'; // Use the UDT as parameter await client.execute(traversal, { uid: Uuid.random(), address }); --- # DataStax Node.js Driver - Upgrading from the DSE Driver [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/upgrade-from-dse-driver/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/upgrade-from-dse-driver/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/upgrade-from-dse-driver/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/upgrade-from-dse-driver/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/upgrade-guide/upgrade-from-dse-driver/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Upgrading from the DSE Driver[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/upgrade-from-dse-driver/index.html#upgrading-from-the-dse-driver) ========================================================================================================================================================================= This guide is intended for users of the DSE driver that plan to migrate to the `cassandra-driver`. The `cassandra-driver` now supports all DataStax products and features, such as Unified Authentication, Kerberos, geo types and graph traversal executions, allowing you to use a single driver for Apache Cassandra, DSE or other DataStax products. Upgrading from `dse-driver` to `cassandra-driver` can be as simple as changing the import statement to point to the dse package: const { Client } = require('dse-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); Becomes: const { Client } = require('cassandra-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); Submodules[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/upgrade-from-dse-driver/index.html#submodules) ----------------------------------------------------------------------------------------------------------------------------------- Most of the child modules are in the same path. const { auth, types, geometry, policies, mapping } = require('dse-driver'); Becomes: const { auth, types, geometry, policies, mapping } = require('cassandra-driver'); The only notable module path distinctions are Graph and Search types that are under `datastax` module. const { graph, search } = require('dse-driver'); Becomes: const { datastax } = require('cassandra-driver'); const { graph, search } = datastax; Load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/upgrade-from-dse-driver/index.html#load-balancing-policy) --------------------------------------------------------------------------------------------------------------------------------------------------------- The default load balancing policy on the `dse-driver` was `DseLoadBalancingPolicy`. In the `cassandra-driver`, a policy with the same behaviour is called `DefaultLoadBalancingPolicy`, which is the default. --- # DataStax Node.js Driver - Cluster and schema metadata [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/metadata/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/metadata/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/metadata/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/metadata/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/metadata/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/metadata/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/metadata/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/metadata/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/metadata/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/metadata/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/metadata/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/metadata/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/metadata/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/metadata/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/metadata/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/metadata/) * Cluster and schema metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/metadata/index.html#cluster-and-schema-metadata) ================================================================================================================================================= You can retrieve the cluster topology and the schema metadata information using the Node.js driver. After establishing the first connection, the driver retrieves the cluster topology details and exposes these through properties of the client object. This information is kept up to date using Cassandra event notifications. The following example outputs hosts information about your cluster: client.hosts.forEach(function (host) { console.log(host.address, host.datacenter, host.rack); }); Additionally, the keyspaces information is already loaded into the `Metadata` object, once the client is connected: console.log(Object.keys(client.metadata.keyspaces)); To retrieve the definition of a table, use the `Metadata#getTable()` method: client.metadata.getTable('ks1', 'table1') .then(function (tableInfo) { console.log('Table %s', table.name); table.columns.forEach(function (column) { console.log('Column %s with type %j', column.name, column.type); }); }); When retrieving the same table definition concurrently, the driver queries once and invokes all callbacks with the retrieved information. Schema agreement[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/metadata/index.html#schema-agreement) --------------------------------------------------------------------------------------------------------------------------- Schema changes need to be propagated to all nodes in the cluster. Once they have settled on a common version, we say that they are in agreement. the driver waits for schema agreement after executing a schema-altering query. This is to ensure that subsequent requests (which might get routed to different nodes) see an up-to-date version of the schema. ![Text Diagram]() The schema agreement wait is performed serially, so the `execute()` call will only return after it has completed. The check is implemented by repeatedly querying system tables for the schema version reported by each node, until they all converge to the same value. If that doesn’t happen within a given timeout, the driver will give up waiting. The default timeout is `10` seconds, it can be customized when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxSchemaAgreementWaitSeconds: 20 } }); After executing a statement, you can check whether schema agreement was successful or timed out: client.execute('CREATE TABLE table1 (id int PRIMARY KEY)') .then(rs => { console.log(`Is schema in agreement? ${rs.info.isSchemaInAgreement}`); }); Additionally, you can perform an on-demand check at any time: client.metadata.checkSchemaAgreement() .then(agreement => { console.log(`Is schema in agreement? ${agreement}`); }); Note that the on-demand check using `checkSchemaAgreement()` does not retry, it only queries system tables once. --- # DataStax Node.js Driver - Tuning policies [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/tuning-policies/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/tuning-policies/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/tuning-policies/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/tuning-policies/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/tuning-policies/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/tuning-policies/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/tuning-policies/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/tuning-policies/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/tuning-policies/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/tuning-policies/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/tuning-policies/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/tuning-policies/) * Tuning policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/index.html#tuning-policies) ================================================================================================================================ Load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/index.html#load-balancing-policy) -------------------------------------------------------------------------------------------------------------------------------------------- The load balancing policy interface consists of three methods: * `#distance(Host host)`: determines the distance to the specified host. The values are `distance.ignored`, `distance.local`, and `distance.remote`. * `#init(client, hosts, callback)`: initializes the policy. The driver calls this method only once and before any other method calls are made. * `#newQueryPlan(keyspace, queryOptions, callback)`: executes a callback with the iterator of hosts to use for a query. Each new query calls this method. The policies are responsible for yielding a group of nodes in an specific order for the driver to use (if the first node fails, it uses the next one). There are four load-balancing policies implemented in the driver: * `DCAwareRoundRobinPolicy`: a datacenter-aware, round-robin, load-balancing policy. This policy provides round-robin queries over the node of the local datacenter. It also includes in the query plans returned a configurable number of hosts in the remote data centers, but those are always tried after the local nodes. * `RoundRobinPolicy`: a policy that yields nodes in a round-robin fashion. * `TokenAwarePolicy`: a policy that yields replica nodes for a given partition key and keyspace. The token-aware policy uses a child policy to retrieve the next nodes in case the replicas for a partition key are not available. * `AllowListPolicy`: a policy that wraps the provided child policy but only “allow” hosts from the provided list. Keep in mind however that this policy defeats somewhat the host auto-detection of the driver. As such, this policy is only useful in a few special cases or for testing, but is not optimal in general. ### Default load-balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/index.html#default-load-balancing-policy) The default load-balancing policy is `DefaultLoadBalancingPolicy`. The policy yields local replicas for a given key and, if not available, it yields nodes of the local datacenter in a round-robin manner. Reconnection policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/index.html#reconnection-policy) ---------------------------------------------------------------------------------------------------------------------------------------- The reconnection policy consists of one method: * `#newSchedule()`: creates a new schedule to use in reconnection attempts. By default, the driver uses an exponential reconnection policy. The driver includes these two policy classes: * `ConstantReconnectionPolicy` * `ExponentialReconnectionPolicy` Retry policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/index.html#retry-policy) -------------------------------------------------------------------------------------------------------------------------- A client may send requests to any node in a cluster whether or not it is a replica of the data being queried. This node is placed into the coordinator role temporarily. Which node is the coordinator is determined by the load balancing policy for the cluster. The coordinator is responsible for routing the request to the appropriate replicas. If a coordinator fails during a request, the driver connects to a different node and retries the request. If the coordinator knows before a request that a replica is down, it can throw an `UnavailableException`, but if the replica fails after the request is made, it throws a `TimeoutException`. Of course, this all depends on the consistency level set for the query before executing it. A retry policy centralizes the handling of query retries, minimizing the need for catching and handling of exceptions in your business code. The retry policy interface consists of four methods: * `#onReadTimeout(info, consistency, received, blockFor, isDataPresent)`: determines what to do when the driver gets a `ReadTimeoutException` response from a Cassandra node. * `#onUnavailable(info, consistency, required, alive)`: determines what to do when the driver gets an `UnavailableException` response from a Cassandra node. * `#onWriteTimeout(info, consistency, received, blockFor, writeType)`: determines what to do when the driver gets a `WriteTimeoutException` response from a Cassandra node * `#onRequestError(info, consistency, err)`: defines whether to retry and at which consistency level on an unexpected error, invoked in the following situations: * On a client timeout, while waiting for the server response , being the error an instance of `OperationTimedOutError`. * On a connection error (socket closed, etc.). * When the contacted host replies with an error, such as `overloaded`, `isBootstrapping`, `serverError`, etc. In this case, the error is instance of `ResponseError` The [operation info](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.retry/type.OperationInfo/) , passed as a parameter to the retry policy methods, exposes the `query` and query `options` as properties. A default and base retry policy are included. ### Query idempotence[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/index.html#query-idempotence) Note that as of version 2.0, the configured `RetryPolicy` is not engaged when a query errors with a `WriteTimeoutException` or request error and the query was not [idempotent](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/#query-idempotence) . --- # DataStax Node.js Driver - auth [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.auth/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.auth/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.auth/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.auth/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.auth/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.auth/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.auth/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.auth/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.auth/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.auth/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.auth/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.auth/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.auth/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.auth/) * module auth[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/index.html#module-auth) =============================================================================================================== DSE Authentication module. Contains the classes used for connecting to a DSE cluster secured with DseAuthenticator. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/index.html#classes) ------------------------------------------------------------------------------------------------------- * `[DseGssapiAuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/class.DseGssapiAuthProvider/) ` * `[DsePlainTextAuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/class.DsePlainTextAuthProvider/) ` * `[PlainTextAuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/class.PlainTextAuthProvider/) ` * `[AuthProvider](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/class.AuthProvider/) ` * `[Authenticator](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/class.Authenticator/) ` --- # DataStax Node.js Driver - ResultCallback [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ResultCallback/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ResultCallback/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ResultCallback/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.ResultCallback/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/type.ResultCallback/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/type.ResultCallback/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/type.ResultCallback/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/type.ResultCallback/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/type.ResultCallback/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/type.ResultCallback/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/type.ResultCallback/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/type.ResultCallback/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/type.ResultCallback/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/type.ResultCallback/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/type.ResultCallback/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/type.ResultCallback/) * type ResultCallback[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ResultCallback/index.html#type-result-callback) ======================================================================================================================================== Callback used by execution methods. Global This type is global --- # DataStax Node.js Driver - User-defined functions and aggregates [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/udfs/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/udfs/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/udfs/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/udfs/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/udfs/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/udfs/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/udfs/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/udfs/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/udfs/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/udfs/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/udfs/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/udfs/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/udfs/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/udfs/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/udfs/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/udfs/) * User-defined functions and aggregates[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/udfs/index.html#user-defined-functions-and-aggregates) ================================================================================================================================================================= Cassandra 2.2 introduced [user-defined functions](https://issues.apache.org/jira/browse/CASSANDRA-7395) (UDF) and aggregates support. You access UDF and aggregate values in your queries like regular columns: const query = 'SELECT avg(salary) as salary FROM employees'; client.execute(query) .then(function (result) { const row = result.first(); console.log('Average salary %d', row.salary); }); The driver also exposes [UDFs and aggregates metadata information](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/) , for example let’s see how to retrieve the metadata information of a UDF named iif, that takes a boolean and int parameter. client.metadata.getFunction('ks1', 'iif', ['boolean', 'int']) .then(function (err, udf) { console.log('Function metadata %j', udf); }); --- # DataStax Node.js Driver - datastax [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.datastax/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.datastax/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.datastax/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.datastax/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.datastax/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module datastax[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.datastax/index.html#module-datastax) =========================================================================================================================== DataStax module. Contains modules and classes to represent functionality that is specific to DataStax products. Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.datastax/index.html#modules) ----------------------------------------------------------------------------------------------------------- * `[graph](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.datastax/module.graph/) ` * `[search](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.datastax/module.search/) ` --- # DataStax Node.js Driver - geometry [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.geometry/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.geometry/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module geometry[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/index.html#module-geometry) =========================================================================================================================== Geometry module. Contains the classes to represent the set of additional CQL types for geospatial data that come with DSE 5.0. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/index.html#classes) ----------------------------------------------------------------------------------------------------------- * `[LineString](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/class.LineString/) ` * `[Point](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/class.Point/) ` * `[Polygon](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/class.Polygon/) ` --- # DataStax Node.js Driver - Promise and callback-based API [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/promise-callback/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/promise-callback/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/promise-callback/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/promise-callback/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/promise-callback/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/promise-callback/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/promise-callback/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/promise-callback/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/promise-callback/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/promise-callback/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/promise-callback/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/promise-callback/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/promise-callback/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/promise-callback/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Promise and callback-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/promise-callback/index.html#promise-and-callback-based-api) =============================================================================================================================================================== The driver supports both [promises](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) and callbacks for the asynchronous methods exposed in the `Client` and `Metadata` prototypes, you can choose the approach that suits your needs. Promise-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/promise-callback/index.html#promise-based-api) ------------------------------------------------------------------------------------------------------------------------------------- client.execute('SELECT name, email FROM users') .then(result => console.log('User with email %s', result.rows[0].email)); When a `callback` is not provided as the last argument, the driver will return a `Promise`, without the need to promisify the driver module. Returned promises are instances of [`Promise` global object](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) and are created using the default constructor: `new Promise(executor)`. In case you want the driver to use a third party `Promise` module (ie: [bluebird](http://bluebirdjs.com/) ) to create the `Promise` instances, you can optionally provide your own factory method when creating the `Client` instance, for example: const BbPromise = require('bluebird'); const client = new Client({ contactPoints, localDataCenter, promiseFactory: BbPromise.fromCallback }); Callback-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/promise-callback/index.html#callback-based-api) --------------------------------------------------------------------------------------------------------------------------------------- All asynchronous methods of the driver supports an optional `callback` as the last argument. client.execute('SELECT name, email FROM users', function(err, result) { assert.ifError(err); console.log('User with email %s', result.rows[0].email); }); --- # DataStax Node.js Driver - metrics [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.metrics/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.metrics/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.metrics/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.metrics/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.metrics/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.metrics/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module metrics[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/index.html#module-metrics) ======================================================================================================================== The `metrics` module contains interfaces and implementations used by the driver to expose measurements of its internal behavior and of the server as seen from the driver side. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/index.html#classes) ---------------------------------------------------------------------------------------------------------- * `[DefaultMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/class.DefaultMetrics/) ` Interfaces[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/index.html#interfaces) ---------------------------------------------------------------------------------------------------------------- * `[ClientMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/interface.ClientMetrics/) ` --- # DataStax Node.js Driver - tracker [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.tracker/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.tracker/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.tracker/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.tracker/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.tracker/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.tracker/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.tracker/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.tracker/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.tracker/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module tracker[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.tracker/index.html#module-tracker) ======================================================================================================================== Tracker module. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.tracker/index.html#classes) ---------------------------------------------------------------------------------------------------------- * `[RequestLogger](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.tracker/class.RequestLogger/) ` Interfaces[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.tracker/index.html#interfaces) ---------------------------------------------------------------------------------------------------------------- * `[RequestTracker](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.tracker/interface.RequestTracker/) ` --- # DataStax Node.js Driver - ExecutionOptions [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.ExecutionOptions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.ExecutionOptions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.ExecutionOptions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.ExecutionOptions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.ExecutionOptions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.ExecutionOptions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * class ExecutionOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#class-execution-options) ================================================================================================================================================= A base class that represents a wrapper around the user provided query options with getter methods and proper default values. Note that getter methods might return `undefined` when not set on the query options or default `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` options. Global This class is global Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#constructor) -------------------------------------------------------------------------------------------------------------------------- new ### ExecutionOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#execution-options) () Creates a new instance of `[ExecutionOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/) `. Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#methods) ------------------------------------------------------------------------------------------------------------------ ### getCaptureStackTrace[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-capture-stack-trace) () Determines if the stack trace before the query execution should be maintained. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | ### getConsistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-consistency) () Gets the `[Consistency level](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/#constant.consistencies) ` to be used for the execution. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getCustomPayload[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-custom-payload) () Key-value payload to be passed to the server. On the server side, implementations of QueryHandler can use this data. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | ### getFetchSize[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-fetch-size) () Gets the amount of rows to retrieve per page. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getFixedHost[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-fixed-host) () When a fixed host is set on the query options and the query plan for the load-balancing policy is not used, it gets the host that should handle the query. Returns: | Type | Description | | --- | --- | | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` | | ### getHints[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-hints) () Gets the type hints for parameters given in the query, ordered as for the parameters. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\> | | ### getKeyspace[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-keyspace) () Gets the keyspace for the query when set at query options level. Note that this method will return `undefined` when the keyspace is not set at query options level. It will only return the keyspace name when the user provided a different keyspace than the current `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` keyspace. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | ### getLoadBalancingPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-load-balancing-policy) () Gets the load balancing policy used for this execution. Returns: | Type | Description | | --- | --- | | `LoadBalancingPolicy` | A `LoadBalancingPolicy` instance, it can’t be `undefined`. | ### getPageState[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-page-state) () Gets the Buffer representing the paging state. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `Buffer` | | ### getRawQueryOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-raw-query-options) () Gets the query options as provided to the execution method without setting the default values. Returns: | Type | Description | | --- | --- | | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` | | ### getReadTimeout[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-read-timeout) () Gets the timeout in milliseconds to be used for the execution per coordinator. A value of `0` disables client side read timeout for the execution. Default: `undefined`. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getRetryPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-retry-policy) () Gets the `[retry policy](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/module.retry/) ` to be used. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `RetryPolicy` | A `RetryPolicy` instance, it can’t be `undefined`. | ### getRoutingKey[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-routing-key) () Gets the partition key(s) to determine which coordinator should be used for the query. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `Buffer` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`Buffer`\> | | ### getSerialConsistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-serial-consistency) () Gets the the consistency level to be used for the serial phase of conditional updates. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getTimestamp[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#get-timestamp) () Gets the provided timestamp for the execution in microseconds from the unix epoch (00:00:00, January 1st, 1970). When a timestamp generator is used, this method returns `undefined`. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) `, `Long`, `[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined) ` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` | | ### isAutoPage[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#is-auto-page) () Determines whether the driver must retrieve the following result pages automatically. This setting is only considered by the `[Client#eachRow()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#function.each-row) ` method. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | ### isBatchCounter[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#is-batch-counter) () Determines whether its a counter batch. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#function.batch) `, it will be ignored by other methods. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | A `Boolean` value, it can’t be `undefined`. | ### isBatchLogged[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#is-batch-logged) () Determines whether the batch should be written to the batchlog. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/#function.batch) `, it will be ignored by other methods. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | A `Boolean` value, it can’t be `undefined`. | ### isIdempotent[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#is-idempotent) () Determines whether the query can be applied multiple times without changing the result beyond the initial application. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | ### isPrepared[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#is-prepared) () Determines whether the query must be prepared beforehand. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | A `Boolean` value, it can’t be `undefined`. | ### isQueryTracing[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/index.html#is-query-tracing) () Determines whether query tracing is enabled for the execution. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | --- # DataStax Node.js Driver - metadata [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metadata/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.metadata/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.metadata/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.metadata/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.metadata/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.metadata/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.metadata/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.metadata/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.metadata/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.metadata/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.metadata/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.metadata/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.metadata/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.metadata/) * module metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/index.html#module-metadata) =========================================================================================================================== Module containing classes and fields related to metadata. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/index.html#classes) ----------------------------------------------------------------------------------------------------------- * `[Aggregate](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.Aggregate/) ` * `[ClientState](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.ClientState/) ` * `[DataCollection](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.DataCollection/) ` * `[Metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.Metadata/) ` * `[MaterializedView](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.MaterializedView/) ` * `[SchemaFunction](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.SchemaFunction/) ` * `[Index](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.Index/) ` * `[TableMetadata](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.TableMetadata/) ` --- # DataStax Node.js Driver - concurrent [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.concurrent/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.concurrent/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.concurrent/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.concurrent/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.concurrent/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.concurrent/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.concurrent/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.concurrent/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module concurrent[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.concurrent/index.html#module-concurrent) ================================================================================================================================= Utilities for concurrent query execution with the DataStax Node.js Driver. Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.concurrent/index.html#functions) ----------------------------------------------------------------------------------------------------------------- ### concurrent.executeConcurrent[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.concurrent/index.html#execute-concurrent) (`[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` client, `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<{query, params}\> query, `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\>, `Stream` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` parameters, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` options\]) Executes multiple queries concurrently at the defined concurrency level. Static This function is static Examples: Using a fixed query and an Array of Arrays as parameters const query = 'INSERT INTO table1 (id, value) VALUES (?, ?)'; const parameters = [[1, 'a'], [2, 'b'], [3, 'c'], ]; // ... const result = await executeConcurrent(client, query, parameters); Using a fixed query and a readable stream const stream = csvStream.pipe(transformLineToArrayStream); const result = await executeConcurrent(client, query, stream); Using a different queries const queryAndParameters = [\ { query: 'INSERT INTO videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ { query: 'INSERT INTO user_videos (user_id, id, name) VALUES (?, ?, ?)',\ params: [ userId, id, name ] },\ { query: 'INSERT INTO latest_videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ ]; const result = await executeConcurrent(client, queryAndParameters); Parameters: | Name | Type | Description | | --- | --- | --- | | client | `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` | The `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` instance. | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<{query, params}\> | The query to execute per each parameter item. | | parameters | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\>, `Stream` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | An `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or a readable `Stream` composed of `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` items representing each individual set of parameters. Per each item in the `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `Stream`, an execution is going to be made. | | options optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | The execution options. | | options.executionProfile optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The execution profile to be used. | | options.concurrencyLevel optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The concurrency level to determine the maximum amount of in-flight operations at any given time

(default: `100`) | | options.raiseOnFirstError optional | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether execution should stop after the first failed execution and the corresponding exception will be raised.

(default: `true`) | | options.collectResults optional | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether each individual `[ResultSet](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/class.ResultSet/) ` instance should be collected in the grouped result.

(default: `false`) | | options.maxErrors optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The maximum amount of errors to be collected before ignoring the rest of the error results.

(default: `100`) | Returns: | Type | Description | | --- | --- | | `Promise`<`ResultSetGroup`\> | A `Promise` of `ResultSetGroup` that is resolved when all the executions completed and it’s rejected when `raiseOnFirstError` is `true` and there is one or more failures. | --- # DataStax Node.js Driver - Frequently Asked Questions [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/faq/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/faq/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/faq/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/faq/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/faq/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/faq/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/faq/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/faq/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/faq/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/faq/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/faq/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/faq/) * Frequently Asked Questions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/index.html#frequently-asked-questions) ================================================================================================================================= ### Which versions of Apache Cassandra and DSE does the driver support?[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/index.html#which-versions-of-apache-cassandra-and-dse-does-the-driver-support) The driver supports all Apache Cassandra versions starting from 2.1 and [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) versions from 4.8 to the latest version. ### How do I generate a random uuid or a time-based uuid?[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/index.html#how-do-i-generate-a-random-uuid-or-a-time-based-uuid) Use the [Uuid and TimeUuid classes](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/uuids) inside the types module. ### Should I create one `Client` instance per module in my application?[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/index.html#should-i-create-one-client-instance-per-module-in-my-application) Normally you should use one `Client` instance per application. You should share that instance between modules within your application. ### Should I shut down the pool after executing a query?[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/index.html#should-i-shut-down-the-pool-after-executing-a-query) No, only call `client.shutdown()` once in your application’s lifetime, normally when you shutdown your application. ### How can I use a list of values with the IN operator in a WHERE clause?[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/index.html#how-can-i-use-a-list-of-values-with-the-in-operator-in-a-where-clause) To provide a dynamic list of values in a single parameter, use the `IN` operator followed by the question mark placeholder without parenthesis in the query. The parameter containing the list of values should be of an instance of Array. For example: const query = 'SELECT * FROM table1 WHERE key1 = ? AND key2 IN ?'; const key1 = 'param1'; const allKeys2 = [ 'val1', 'val2', 'val3' ]; client.execute(query, [ key1, allKeys2 ], { prepare: true }); ### Can I use a single `Client` instance for graph and CQL?[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/index.html#can-i-use-a-single-client-instance-for-graph-and-cql) Yes, you can. You should use [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/) to define your settings for CQL and graph workloads, for example: define which datacenter should be used for graph or for CQL. --- # DataStax Node.js Driver - TransitionalModePlainTextAuthenticator [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.TransitionalModePlainTextAuthenticator/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.TransitionalModePlainTextAuthenticator/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.TransitionalModePlainTextAuthenticator/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * class TransitionalModePlainTextAuthenticator[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.TransitionalModePlainTextAuthenticator/index.html#class-transitional-mode-plain-text-authenticator) ====================================================================================================================================================================================================================== Authenticator that accounts for DSE authentication configured with transitional mode: normal. In this situation, the client is allowed to connect without authentication, but DSE would still send an AUTHENTICATE response. This Authenticator handles this situation by sending back a dummy credential. Global This class is global Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.TransitionalModePlainTextAuthenticator/index.html#constructor) ------------------------------------------------------------------------------------------------------------------------------------------------ new ### TransitionalModePlainTextAuthenticator[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.TransitionalModePlainTextAuthenticator/index.html#transitional-mode-plain-text-authenticator) () --- # DataStax Node.js Driver - ClientOptions [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.ClientOptions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.ClientOptions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/type.ClientOptions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/type.ClientOptions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/type.ClientOptions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/type.ClientOptions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/type.ClientOptions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/type.ClientOptions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/type.ClientOptions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/type.ClientOptions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/type.ClientOptions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/type.ClientOptions/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/type.ClientOptions/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/type.ClientOptions/) * type ClientOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/index.html#type-client-options) ===================================================================================================================================== Client options. While the driver provides lots of extensibility points and configurability, few client options are required. Default values for all settings are designed to be suitable for the majority of use cases, you should avoid fine tuning it when not needed. See `[Client constructor](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` documentation for recommended options. Global This type is global Properties: | Name | Type | Description | | --- | --- | --- | | contactPoints | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> | Array of addresses or host names of the nodes to add as contact points.

Contact points are addresses of Cassandra nodes that the driver uses to discover the cluster topology.

Only one contact point is required (the driver will retrieve the address of the other nodes automatically), but it is usually a good idea to provide more than one contact point, because if that single contact point is unavailable, the driver will not be able to initialize correctly. | | localDataCenter | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The local data center to use.

If using DCAwareRoundRobinPolicy (default), this option is required and only hosts from this data center are connected to and used in query plans. | | keyspace | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The logged keyspace for all the connections created within the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` instance. | | credentials | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | An object containing the username and password for plain-text authentication. It configures the authentication provider to be used against Apache Cassandra’s PasswordAuthenticator or DSE’s DseAuthenticator, when default auth scheme is plain-text.

Note that you should configure either `credentials` or `authProvider` to connect to an auth-enabled cluster, but not both. | | credentials.username | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The username to use for plain-text authentication. | | credentials.password | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The password to use for plain-text authentication. | | id | `Uuid` | A unique identifier assigned to a `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` object, that will be communicated to the server (DSE 6.0+) to identify the client instance created with this options. When not defined, the driver will generate a random identifier. | | applicationName | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | An optional setting identifying the name of the application using the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` instance.

This value is passed to DSE and is useful as metadata for describing a client connection on the server side. | | applicationVersion | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | An optional setting identifying the version of the application using the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` instance.

This value is passed to DSE and is useful as metadata for describing a client connection on the server side. | | monitorReporting | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Options for reporting mechanism from the client to the DSE server, for versions that support it. | | monitorReporting.enabled | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether the reporting mechanism is enabled. Defaults to `true`. | | cloud | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | The options to connect to a cloud instance. | | cloud.secureConnectBundle | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `URL` | Determines the file path for the credentials file bundle. | | refreshSchemaDelay | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The default window size in milliseconds used to debounce node list and schema refresh metadata requests. Default: 1000. | | isMetadataSyncEnabled | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether client-side schema metadata retrieval and update is enabled.

Setting this value to `false` will cause keyspace information not to be automatically loaded, affecting replica calculation per token in the different keyspaces. When disabling metadata synchronization, use `[Metadata.refreshKeyspaces()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.Metadata/#function.refresh-keyspaces) ` to keep keyspace information up to date or token-awareness will not work correctly.

Default: `true`. | | prepareOnAllHosts | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the driver should prepare queries on all hosts in the cluster. Default: `true`. | | rePrepareOnUp | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the driver should re-prepare all cached prepared queries on a host when it marks it back up. Default: `true`. | | maxPrepared | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Determines the maximum amount of different prepared queries before evicting items from the internal cache. Reaching a high threshold hints that the queries are not being reused, like when hard-coding parameter values inside the queries. Default: `500`. | | policies | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | policies.loadBalancing | `LoadBalancingPolicy` | The load balancing policy instance to be used to determine the coordinator per query. | | policies.retry | `RetryPolicy` | The retry policy. | | policies.reconnection | `ReconnectionPolicy` | The reconnection policy to be used. | | policies.addressResolution | `AddressTranslator` | The address resolution policy. | | policies.speculativeExecution | `SpeculativeExecutionPolicy` | The `SpeculativeExecutionPolicy` instance to be used to determine if the client should send speculative queries when the selected host takes more time than expected.

Default: `` `[NoSpeculativeExecutionPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.speculativeExecution/class.NoSpeculativeExecutionPolicy/) ` `` | | policies.timestampGeneration | `TimestampGenerator` | The client-side `[query timestamp generator](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.timestampGeneration/class.TimestampGenerator/) `.

Default: `` `[MonotonicTimestampGenerator](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) ` ``

Use `null` to disable client-side timestamp generation. | | queryOptions | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` | Default options for all queries. | | pooling | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Pooling options. | | pooling.heartBeatInterval | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The amount of idle time in milliseconds that has to pass before the driver issues a request on an active connection to avoid idle time disconnections. Default: 30000. | | pooling.coreConnectionsPerHost | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Associative array containing amount of connections per host distance. | | pooling.maxRequestsPerConnection | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The maximum number of requests per connection. The default value is:

* For modern protocol versions (v3 and above): 2048
* For older protocol versions (v1 and v2): 128 | | pooling.warmup | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if all connections to hosts in the local datacenter must be opened on connect. Default: true. | | protocolOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | protocolOptions.port | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The port to use to connect to the Cassandra host. If not set through this method, the default port (9042) will be used instead. | | protocolOptions.maxSchemaAgreementWaitSeconds | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The maximum time in seconds to wait for schema agreement between nodes before returning from a DDL query. Default: 10. | | protocolOptions.maxVersion | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | When set, it limits the maximum protocol version used to connect to the nodes. Useful for using the driver against a cluster that contains nodes with different major/minor versions of Cassandra. | | protocolOptions.noCompact | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | When set to true, enables the NO\_COMPACT startup option.

When this option is supplied `SELECT`, `UPDATE`, `DELETE`, and `BATCH` statements on `COMPACT STORAGE` tables function in “compatibility” mode which allows seeing these tables as if they were “regular” CQL tables.

This option only effects interactions with interactions with tables using `COMPACT STORAGE` and is only supported by C\* 3.0.16+, 3.11.2+, 4.0+ and DSE 6.0+. | | socketOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | socketOptions.connectTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Connection timeout in milliseconds. Default: 5000. | | socketOptions.defunctReadTimeoutThreshold | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Determines the amount of requests that simultaneously have to timeout before closing the connection. Default: 64. | | socketOptions.keepAlive | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Whether to enable TCP keep-alive on the socket. Default: true. | | socketOptions.keepAliveDelay | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | TCP keep-alive delay in milliseconds. Default: 0. | | socketOptions.readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Per-host read timeout in milliseconds.

Please note that this is not the maximum time a call to `[execute](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#function.execute) ` may have to wait; this is the maximum time that call will wait for one particular Cassandra host, but other hosts will be tried if one of them timeout. In other words, a `[execute](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#function.execute) ` call may theoretically wait up to `readTimeout * number_of_cassandra_hosts` (though the total number of hosts tried for a given query also depends on the LoadBalancingPolicy in use).

When setting this value, keep in mind the following:

* the timeout settings used on the Cassandra side (\*\_request\_timeout\_in\_ms in cassandra.yaml) should be taken into account when picking a value for this read timeout. You should pick a value a couple of seconds greater than the Cassandra timeout settings.
* the read timeout is only approximate and only control the timeout to one Cassandra host, not the full query.

Setting a value of 0 disables read timeouts. Default: `12000`. | | socketOptions.tcpNoDelay | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | When set to true, it disables the Nagle algorithm. Default: true. | | socketOptions.coalescingThreshold | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Buffer length in bytes use by the write queue before flushing the frames. Default: 8000. | | authProvider | `AuthProvider` | Provider to be used to authenticate to an auth-enabled cluster. | | requestTracker | `RequestTracker` | The instance of RequestTracker used to monitor or log requests executed with this instance. | | sslOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Client-to-node ssl options. When set the driver will use the secure layer. You can specify cert, ca, … options named after the Node.js `tls.connect()` options.

It uses the same default values as Node.js `tls.connect()` except for `rejectUnauthorized` which is set to `false` by default (for historical reasons). This setting is likely to change in upcoming versions to enable validation by default. | | encoding | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Encoding options. | | encoding.map | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Map constructor to use for Cassandra map type encoding and decoding. If not set, it will default to Javascript Object with map keys as property names. | | encoding.set | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Set constructor to use for Cassandra set type encoding and decoding. If not set, it will default to Javascript Array. | | encoding.copyBuffer | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the network buffer should be copied for buffer based data types (blob, uuid, timeuuid and inet).

Setting it to true will cause that the network buffer is copied for each row value of those types, causing additional allocations but freeing the network buffer to be reused. Setting it to true is a good choice for cases where the Row and ResultSet returned by the queries are long-lived objects.

Setting it to false will cause less overhead and the reference of the network buffer to be maintained until the row / result set are de-referenced. Default: true. | | encoding.useUndefinedAsUnset | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Valid for Cassandra 2.2 and above. Determines that, if a parameter is set to `undefined` it should be encoded as `unset`.

By default, ECMAScript `undefined` is encoded as `null` in the driver. Cassandra 2.2 introduced the concept of unset. At driver level, you can set a parameter to unset using the field `types.unset`. Setting this flag to true allows you to use ECMAScript undefined as Cassandra `unset`.

Default: true. | | encoding.useBigIntAsLong | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Use [BigInt ECMAScript type](https://tc39.github.io/proposal-bigint/)
to represent CQL bigint and counter data types. | | encoding.useBigIntAsVarint | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Use [BigInt ECMAScript type](https://tc39.github.io/proposal-bigint/)
to represent CQL varint data type. | | profiles | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) `\> | The array of `[execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) `. | | promiseFactory | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Function to be used to create a `Promise` from a callback-style function.

Promise libraries often provide different methods to create a promise. For example, you can use Bluebird’s `Promise.fromCallback()` method.

By default, the driver will use the `Promise constructor`. | --- # DataStax Node.js Driver - Address resolution [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/address-resolution/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/address-resolution/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/address-resolution/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/address-resolution/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/address-resolution/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/address-resolution/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/address-resolution/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/address-resolution/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/address-resolution/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/address-resolution/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/address-resolution/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/address-resolution/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/address-resolution/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/address-resolution/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/address-resolution/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/address-resolution/) * Address resolution[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/address-resolution/index.html#address-resolution) ========================================================================================================================================= The driver auto-detects new Cassandra nodes when they are added to the cluster by means of server-side push notifications and checking the system tables. For each node, the address the driver receives the address set as [`rpc_address` in the node’s cassandra.yaml file](https://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configCassandra_yaml_r.html?scroll=reference_ds_qfg_n1r_1k__rpc_address) (or [`broadcast_rpc_address` when defined](https://docs.datastax.com/en/cassandra/2.1/cassandra/configuration/configCassandra_yaml_r.html?scroll=reference_ds_qfg_n1r_1k__rpc_address) ). In most cases, this is the correct value, however, sometimes the addresses received in this manner are either not reachable directly by the driver or are not the preferred address to use. A common such scenario is a multi-datacenter deployment with a client connecting using the private IP address to the local datacenter (to reduce network costs) and the public IP address for the remote datacenter nodes. The AddressTranslator interface[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/address-resolution/index.html#the-address-translator-interface) -------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `AddressTranslator` interface allows you to deal with such cases, by transforming the address sent by a Cassandra node to another address to be used by the driver for connection. class MyAddressTranslator extends AddressTranslator { translate(address, port, callback) { // Your custom translation logic } } You then configure the driver to use your AddressTranslator implementation in the client options. const client = new Client({ contactPoints, localDataCenter, policies: { addressResolution: new MyAddressTranslator() } }); Note: The contact points provided while creating the Client are not translated, only addresses retrieved from or sent by Cassandra nodes are. EC2 multi-region[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/address-resolution/index.html#ec2-multi-region) ------------------------------------------------------------------------------------------------------------------------------------- The `EC2MultiRegionTranslator` class is provided out of the box. It helps optimize network costs when your infrastructure (both Cassandra nodes and clients) is distributed across multiple Amazon EC2 regions: * a client communicating with a Cassandra node in the same EC2 region should use the node’s private IP address (which is less expensive); * a client communicating with a node in a different region should use the public IP address. To use this implementation, provide an instance when initializing the `Client` object. const cassandra = require('cassandra-driver'); const { EC2MultiRegionTranslator } = cassandra.policies.addressResolution; const client = new cassandra.Client({ contactPoints, localDataCenter, policies: { addressResolution: new EC2MultiRegionTranslator() } }); The `Client` class performs a reverse DNS lookup of the origin address to find the domain name of the target instance. Then it performs a forward DNS lookup of the domain name; the EC2 DNS does the private to public switch automatically based on location. --- # DataStax Node.js Driver - types [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.types/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.types/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.types/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.types/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.types/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.types/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.types/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.types/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.types/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.types/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.types/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.types/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.types/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.types/) * module types[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#module-types) ================================================================================================================== Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#classes) -------------------------------------------------------------------------------------------------------- * `[BigDecimal](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.BigDecimal/) ` * `[Duration](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.Duration/) ` * `[Long](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.Long/) ` * `[InetAddress](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.InetAddress/) ` * `[Integer](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.Integer/) ` * `[LocalDate](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.LocalDate/) ` * `[LocalTime](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.LocalTime/) ` * `[ResultSet](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.ResultSet/) ` * `[ResultStream](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.ResultStream/) ` * `[Row](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.Row/) ` * `[TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.TimeUuid/) ` * `[Tuple](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.Tuple/) ` * `[Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.Uuid/) ` Constants[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#constants) ------------------------------------------------------------------------------------------------------------ ### consistencies[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#consistencies) Consistency levels Properties: | Name | Type | Description | | --- | --- | --- | | any | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Writing: A write must be written to at least one node. If all replica nodes for the given row key are down, the write can still succeed after a hinted handoff has been written. If all replica nodes are down at write time, an ANY write is not readable until the replica nodes for that row have recovered. | | one | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns a response from the closest replica, as determined by the snitch. | | two | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the most recent data from two of the closest replicas. | | three | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the most recent data from three of the closest replicas. | | quorum | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record with the most recent timestamp after a quorum of replicas has responded regardless of data center. Writing: A write must be written to the commit log and memory table on a quorum of replica nodes. | | all | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record with the most recent timestamp after all replicas have responded. The read operation will fail if a replica does not respond. Writing: A write must be written to the commit log and memory table on all replica nodes in the cluster for that row. | | localQuorum | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record with the most recent timestamp once a quorum of replicas in the current data center as the coordinator node has reported. Writing: A write must be written to the commit log and memory table on a quorum of replica nodes in the same data center as the coordinator node. Avoids latency of inter-data center communication. | | eachQuorum | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Reading: Returns the record once a quorum of replicas in each data center of the cluster has responded. Writing: Strong consistency. A write must be written to the commit log and memtable on a quorum of replica nodes in all data centers. | | serial | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Achieves linearizable consistency for lightweight transactions by preventing unconditional updates. | | localSerial | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Same as serial but confined to the data center. A write must be written conditionally to the commit log and memtable on a quorum of replica nodes in the same data center. | | localOne | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Similar to One but only within the DC the coordinator is in. | ### consistencyToString[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#consistency-tostring) Mapping of consistency level codes to their string representation. ### dataTypes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#data-types) CQL data types Properties: | Name | Type | Description | | --- | --- | --- | | custom | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A custom type. | | ascii | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | ASCII character string. | | bigint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 64-bit signed long. | | blob | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Arbitrary bytes (no validation). | | boolean | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | true or false. | | counter | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Counter column (64-bit signed value). | | decimal | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Variable-precision decimal. | | double | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 64-bit IEEE-754 floating point. | | float | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 32-bit IEEE-754 floating point. | | int | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 32-bit signed integer. | | text | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | UTF8 encoded string. | | timestamp | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A timestamp. | | uuid | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Type 1 or type 4 UUID. | | varchar | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | UTF8 encoded string. | | varint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Arbitrary-precision integer. | | timeuuid | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Type 1 UUID. | | inet | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | An IP address. It can be either 4 bytes long (IPv4) or 16 bytes long (IPv6). | | date | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A date without a time-zone in the ISO-8601 calendar system. | | time | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A value representing the time portion of the day. | | smallint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 16-bit two’s complement integer. | | tinyint | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | 8-bit two’s complement integer. | | list | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A collection of elements. | | map | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Key/value pairs. | | set | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A collection that contains no duplicate elements. | | udt | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | User-defined type. | | tuple | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A sequence of values. | ### distance[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#distance) Represents the distance of Cassandra node as assigned by a LoadBalancingPolicy relatively to the driver instance. Properties: | Name | Type | Description | | --- | --- | --- | | local | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A local node. | | remote | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A remote node. | | ignored | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A node that is meant to be ignored. | ### protocolVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#protocol-version) Contains information for the different protocol versions supported by the driver. Properties: | Name | Type | Description | | --- | --- | --- | | v1 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v1, supported in Apache Cassandra 1.2–>2.2. | | v2 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v2, supported in Apache Cassandra 2.0–>2.2. | | v3 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v3, supported in Apache Cassandra 2.1–>3.x. | | v4 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v4, supported in Apache Cassandra 2.2–>3.x. | | v5 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Cassandra protocol v5, in beta from Apache Cassandra 3.x+. Currently not supported by the driver. | | dseV1 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | DataStax Enterprise protocol v1, DSE 5.1+ | | dseV2 | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | DataStax Enterprise protocol v2, DSE 6.0+ | | maxSupported | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the higher protocol version that is supported by this driver. | | minSupported | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Returns the lower protocol version that is supported by this driver. | | isSupported | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | A function that returns a boolean determining whether a given protocol version is supported. | ### responseErrorCodes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#response-error-codes) Server error codes returned by Cassandra Properties: | Name | Type | Description | | --- | --- | --- | | serverError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Something unexpected happened. | | protocolError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Some client message triggered a protocol violation. | | badCredentials | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Authentication was required and failed. | | unavailableException | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Raised when coordinator knows there is not enough replicas alive to perform a query with the requested consistency level. | | overloaded | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The request cannot be processed because the coordinator is overloaded. | | isBootstrapping | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The request was a read request but the coordinator node is bootstrapping. | | truncateError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Error encountered during a truncate request. | | writeTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Timeout encountered on write query on coordinator waiting for response(s) from replicas. | | readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Timeout encountered on read query on coordinator waitign for response(s) from replicas. | | readFailure | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A non-timeout error encountered during a read request. | | functionFailure | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A (user defined) function encountered during execution. | | writeFailure | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A non-timeout error encountered during a write request. | | syntaxError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The submitted query has a syntax error. | | unauthorized | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The logged user doesn’t have the right to perform the query. | | invalid | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The query is syntactically correct but invalid. | | configError | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The query is invalid because of some configuration issue. | | alreadyExists | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The query attempted to create a schema element (i.e. keyspace, table) that already exists. | | unprepared | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Can be thrown while a prepared statement tries to be executed if the provided statement is not known by the coordinator. | ### unset[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#unset) Unset representation. Use this field if you want to set a parameter to `unset`. Valid for Cassandra 2.2 and above. Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#functions) ------------------------------------------------------------------------------------------------------------ ### generateTimestamp[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#generate-timestamp) (\[`[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) ` date\], \[`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` microseconds\]) Generates a value representing the timestamp for the query in microseconds based on the date and the microseconds provided Parameters: | Name | Type | Description | | --- | --- | --- | | date optional | `[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) ` | The date to generate the value, if not provided it will use the current date. | | microseconds optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | A number from 0 to 999 used to build the microseconds part of the date. | Returns: | Type | Description | | --- | --- | | `Long` | | ### timeuuid[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#timeuuid) (\[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` options\], \[`Buffer` buffer\], \[`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` offset\]) **Backward compatibility only, use `[TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.TimeUuid/) ` instead**. Generates and returns a RFC4122 v1 (timestamp based) UUID in a string representation. Parameters: | Name | Type | Description | | --- | --- | --- | | options optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | buffer optional | `Buffer` | | | offset optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### uuid[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/index.html#uuid) () **Backward compatibility only, use `[Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.Uuid/) ` class instead**. Generate and return a RFC4122 v4 UUID in a string representation. --- # DataStax Node.js Driver - Batch statements [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/batch/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/batch/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/batch/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/batch/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/batch/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/batch/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/batch/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/batch/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/batch/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/batch/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/batch/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/batch/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/batch/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/batch/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/batch/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/batch/) * Batch statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/batch/index.html#batch-statements) ------------------------------------------------------------------------------------------------------------------------ It’s common for applications to require atomic batching of multiple `INSERT`, `UPDATE`, or `DELETE` statements, even in different partitions or column families. Thanks to the Cassandra protocol changes introduced in Cassandra 2.0, the driver allows you to execute multiple statements efficiently without the need to concatenate multiple queries. The method `batch()` accepts the queries as first parameter: const query1 = 'UPDATE user_profiles SET email = ? WHERE key = ?'; const query2 = 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)'; const queries = [\ { query: query1, params: [emailAddress, 'hendrix'] },\ { query: query2, params: ['hendrix', 'Changed email', new Date()] } \ ]; // Promise-based call client.batch(queries, { prepare: true }) .then(function() { // All queries have been executed successfully }) .catch(function(err) { // None of the changes have been applied }); Or using the callback-based invocation client.batch(queries, { prepare: true }, function (err) { // All queries have been executed successfully // Or none of the changes have been applied, check err }); By preparing your queries, you will get the best performance and your JavaScript parameters correctly mapped to Cassandra types. The driver will prepare each query once on each host and execute the batch every time with the different parameters provided. Note that Cassandra batches are not suitable for bulk loading, there are dedicated tools for that. Batches allow you to group related updates in a single request, so keep the batch size small (in the order of tens). Starting from Cassandra version 2.0.8, the server issues a warning if the batch size is greater than 5K. Refer to [CQL documentation](https://docs.datastax.com/en/cql/3.3/cql/cql_using/useBatchTOC.html) for information about correct and incorrect use of batches. --- # DataStax Node.js Driver - Client [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Client/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.Client/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.Client/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.Client/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.Client/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.Client/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.Client/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.Client/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.Client/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.Client/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.Client/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.Client/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.Client/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.Client/) * class Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#class-client) ================================================================================================================== Represents a database client that maintains multiple connections to the cluster nodes, providing methods to execute CQL statements. The `Client` uses `[policies](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/) ` to decide which nodes to connect to, which node to use per each query execution, when it should retry failed or timed-out executions and how reconnection to down nodes should be made. Global This class is global Augments[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#augments) ---------------------------------------------------------------------------------------------------------- * `[EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) ` Events[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#events) ------------------------------------------------------------------------------------------------------ ### hostAdd[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#host-add) Emitted when a new host is added to the cluster. * `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` The host being added. ### hostDown[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#host-down) Emitted when a host in the cluster changed status from up to down. * `[host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` The host that changed the status. ### hostRemove[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#host-remove) Emitted when a host is removed from the cluster * `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` The host being removed. ### hostUp[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#host-up) Emitted when a host in the cluster changed status from down to up. * `[host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` The host that changed the status. Members[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#members) -------------------------------------------------------------------------------------------------------- `[HostMap](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/) ` ### hosts[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#hosts) Gets an associative array of cluster hosts. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### keyspace[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#keyspace) Gets the name of the active keyspace. `Metadata` ### metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#metadata) Gets the schema and cluster metadata information. `ClientMetrics` ### metrics[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#metrics) The `[ClientMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/interface.ClientMetrics/) ` instance used to expose measurements of its internal behavior and of the server as seen from the driver side. By default, a `[DefaultMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/class.DefaultMetrics/) ` instance is used. Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#constructor) ---------------------------------------------------------------------------------------------------------------- new ### Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#client) (`[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) ` options) Creates a new instance of `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) `. Examples: Creating a new client instance const client = new Client({ contactPoints: ['10.0.1.101', '10.0.1.102'], localDataCenter: 'datacenter1' }); Executing a query const result = await client.connect(); console.log(`Connected to ${client.hosts.length} nodes in the cluster: ${client.hosts.keys().join(', ')}`); Executing a query const result = await client.execute('SELECT key FROM system.local'); const row = result.first(); console.log(row['key']); Parameters: | Name | Type | Description | | --- | --- | --- | | options | `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) ` | The options for this instance. | Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#methods) -------------------------------------------------------------------------------------------------------- ### batch[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#batch) (`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<{query, params}\> queries, \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` options\], \[`[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ResultCallback/) ` callback\]) Executes batch of queries on an available connection to a host. It returns a `Promise` when a `callback` is not provided. Parameters: | Name | Type | Description | | --- | --- | --- | | queries | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` | The query options. | | callback optional | `[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ResultCallback/) ` | Executes callback(err, result) when the batch was executed | ### connect[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#connect) (\[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Attempts to connect to one of the `[contactPoints](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) ` and discovers the rest the nodes of the cluster. When the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` is already connected, it resolves immediately. It returns a `Promise` when a `callback` is not provided. Examples: Usage example await client.connect(); Parameters: | Name | Type | Description | | --- | --- | --- | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | The optional callback that is invoked when the pool is connected or it failed to connect. | ### eachRow[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#each-row) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params\], \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` options\], `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` rowCallback, \[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Executes the query and calls `rowCallback` for each row as soon as they are received. Calls the final `callback` after all rows have been sent, or when there is an error. The query can be prepared (recommended) or not depending on the `[prepare](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` flag. 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); Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The query to execute | | params optional | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Array of parameter values or an associative array (object) containing parameter names as keys and its value. | | options optional | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` | The query options. | | rowCallback | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Executes `rowCallback(n, row)` per each row received, where n is the row index and row is the current Row. | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Executes `callback(err, result)` after all rows have been received.

When dealing with paged results, `[ResultSet#nextPage()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.ResultSet/#member.next-page) ` 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. | ### execute[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#execute) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params\], \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` options\], \[`[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ResultCallback/) ` callback\]) Executes a query on an available connection. The query can be prepared (recommended) or not depending on the `[prepare](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` flag. Some execution failures can be handled transparently by the driver, according to the `[RetryPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.retry/class.RetryPolicy/) ` or the `[SpeculativeExecutionPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.speculativeExecution/) ` used. It returns a `Promise` when a `callback` is not provided. Examples: 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']); 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']); }); Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The query to execute. | | params optional | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Array of parameter values or an associative array (object) containing parameter names as keys and its value. | | options optional | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` | The query options for the execution. | | callback optional | `[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ResultCallback/) ` | Executes callback(err, result) when execution completed. When not defined, the method will return a promise. | ### executeGraph[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#execute-graph) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` parameters\], \[`GraphQueryOptions` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` options\], \[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Executes a graph query. It returns a `Promise` when a `callback` is not provided. 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 client.executeGraph('g.V()', (err, result) => { const vertex = result.first(); console.log(vertex.label); }); Iterating through the results const result = await client.executeGraph('g.E()'); for (let edge of result) { console.log(edge.label); // created }); 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 }); Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The gremlin query. | | parameters optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` | An associative array containing the key and values of the parameters. | | options optional | `GraphQueryOptions` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` | The graph query options. | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Function to execute when the response is retrieved, taking two arguments: `err` and `result`. When not defined, the method will return a promise. | ### getReplicas[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#get-replicas) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` keyspace, `Buffer` token) Gets the host that are replicas of a given token. Parameters: | Name | Type | Description | | --- | --- | --- | | keyspace | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | | token | `Buffer` | | Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) `\> | | ### getState[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#get-state) () Gets a snapshot containing information on the connections pools held by this Client at the current time. The information provided in the returned object only represents the state at the moment this method was called and it’s not maintained in sync with the driver metadata. Returns: | Type | Description | | --- | --- | | `ClientState` | A `[ClientState](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.ClientState/) ` instance. | ### shutdown[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#shutdown) (\[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Closes all connections to all hosts. It returns a `Promise` when a `callback` is not provided. Parameters: | Name | Type | Description | | --- | --- | --- | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Optional callback to be invoked when finished closing all connections. | ### stream[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/index.html#stream) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` query, \[`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params\], \[`[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` options\], \[`[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` callback\]) Executes the query and pushes the rows to the result stream as soon as they received. The stream is a `ReadableStream` object that emits rows. 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](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) `.prepare flag. Retries on multiple hosts if needed. Parameters: | Name | Type | Description | | --- | --- | --- | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The query to prepare and execute. | | params optional | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Array of parameter values or an associative array (object) containing parameter names as keys and its value | | options optional | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` | The query options. | | callback optional | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | executes callback(err) after all rows have been received or if there is an error | Returns: | Type | Description | | --- | --- | | `ResultStream` | | --- # DataStax Node.js Driver - Connection pooling [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/connection-pooling/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/connection-pooling/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/connection-pooling/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/connection-pooling/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/connection-pooling/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/connection-pooling/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/connection-pooling/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/connection-pooling/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/connection-pooling/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/connection-pooling/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/connection-pooling/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/connection-pooling/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/connection-pooling/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/connection-pooling/) * Connection pooling[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling/index.html#connection-pooling) ========================================================================================================================================= The driver maintains one or more connections opened to each Apache Cassandra node selected by the load-balancing policy. The amount of connections per host is defined in the pooling configuration. Default pooling configuration[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling/index.html#default-pooling-configuration) --------------------------------------------------------------------------------------------------------------------------------------------------------------- The default number of connections per host depends on the version of the Apache Cassandra cluster. When using the driver to connect to modern server versions (Apache Cassandra 2.1 and above), the driver uses one connection per host. Setting the number of connections per host[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling/index.html#setting-the-number-of-connections-per-host) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If needed, you can set the number of connections per host depending on the distance, relative to the driver instance, in the `pooling` configuration: const cassandra = require('cassandra-driver'); const distance = cassandra.types.distance; const options = { contactPoints, localDataCenter, pooling: { coreConnectionsPerHost: { [distance.local]: 2, [distance.remote]: 1 } } }; const client = new Client(options); Simultaneous requests per connection[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling/index.html#simultaneous-requests-per-connection) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The driver limits the amount of concurrent requests per connection to `2048` with modern protocol versions and `128` with older versions of the protocol (v1 and v2). You can throttle requests by setting the `maxRequestsPerConnection` value in the `poolingOptions`. When the limit is reached for all connections to a host, the driver will move to the next host according to the query plan. When the query plan is exhausted, the driver will yield a `NoHostAvailableError` containing `BusyConnectionError` instances per each host in the `innerErrors` property. Get status of the connection pool[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling/index.html#get-status-of-the-connection-pool) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can use `getState()` method to get a point-in-time information of the state of the connections pools to each host. const state = client.getState(); for (let host of state.getConnectedHosts()) { console.log('Host %s: open connections = %d; in flight queries = %d', host.address, state.getOpenConnections(host), state.getInFlightQueries(host)); } --- # DataStax Node.js Driver - Three simple rules for coding with the driver [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/coding-rules/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/coding-rules/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/coding-rules/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/coding-rules/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/coding-rules/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/coding-rules/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/coding-rules/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/coding-rules/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/coding-rules/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/coding-rules/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/coding-rules/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/coding-rules/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/coding-rules/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/coding-rules/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/coding-rules/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/coding-rules/) * Three simple rules for coding with the driver[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/coding-rules/index.html#three-simple-rules-for-coding-with-the-driver) ================================================================================================================================================================================ When writing code that uses the driver, there are three simple rules that you should follow that make your code efficient: * Only use one `Client` instance per keyspace or use a single Client and explicitly specify the keyspace in your queries and reuse it in across your modules in the application lifetime. * If you execute a statement more than once, use a prepared statement. * In some situations you can reduce the number of network roundtrips and also have atomic operations by using batches. Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/coding-rules/index.html#client) -------------------------------------------------------------------------------------------------- The `Client` instance allows you to configure different important aspects of the way connections and queries are handled. At this level, you can configure everything from contact points (address of the nodes to be contacted initially before the driver performs node discovery), the request routing policy, retry and reconnection policies, and so on. Generally such settings are set once at the application level. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['10.1.1.3', '10.1.1.4', '10.1.1.5'], localDataCenter: 'us-east-1' }); A `Client` instance is a long-lived object, your code should share the same `Client` instance across your application. Prepared statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/coding-rules/index.html#prepared-statements) ---------------------------------------------------------------------------------------------------------------------------- Using prepared statements provides multiple benefits. A prepared statement is parsed and prepared on the Cassandra nodes and is ready for future execution. When binding parameters are provided, only they (and the query id) are sent over the wire. These performance gains add up when using the same queries (with different parameters) repeatedly. Additionally, when preparing, the driver retrieves information about the parameter types which allows an accurate mapping between a JavaScript type and a CQL type. Preparing and executing statements in the driver does not require two chained asynchronous calls. You can set the `prepare` flag in the query options and the driver handles the rest. const query = 'SELECT id, name FROM users WHERE id = ?'; client.execute(query, [ id ], { prepare: true }); Batch statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/coding-rules/index.html#batch-statements) ---------------------------------------------------------------------------------------------------------------------- The batch statement combines multiple data modification statements (`INSERT`, `UPDATE`, or `DELETE`) into a single logical operation that is sent to the server in a single request. Batching together multiple operations also ensures that they are executed in an atomic way, (that is, either all succeed or none). To make the best use of `batch()`, read about [atomic batches in Cassandra 1.2](http://www.datastax.com/dev/blog/atomic-batches-in-cassandra-1-2) , [static columns and batching of conditional updates](http://www.datastax.com/dev/dev/blog/cql-in-2-0-6) , and [CQL documentation](https://docs.datastax.com/en/cql/3.3/cql/cql_using/useBatchTOC.html) . But take into account that incorrect use of batch statements may increase load to servers. Batch queries should be prepared, by setting the `prepare` flag, when possible. const queries = [\ { query: 'UPDATE user_profiles SET email=? WHERE key=?',\ params: [emailAddress, 'hendrix']},\ { query: 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)',\ params: ['hendrix', 'Changed email', new Date()]}\ ]; const queryOptions = { prepare: true, consistency: cassandra.types.consistencies.localQuorum }; client.batch(queries, queryOptions) .then(() => console.log('Data updated on cluster')); --- # DataStax Node.js Driver - Upgrade Guide [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/upgrade-guide/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/upgrade-guide/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/upgrade-guide/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/upgrade-guide/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/upgrade-guide/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Upgrade guide[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#upgrade-guide) ================================================================================================================= The purpose of this guide is to detail the changes made by the successive versions of the DataStax Node.js Driver that are relevant to for an upgrade from prior versions. If you have any questions or comments, you can [post them on the mailing list](https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user) . 4.4[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#4-4) --------------------------------------------------------------------------------------------- ### New default load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#new-default-load-balancing-policy) The driver uses the new `DefaultLoadBalancingPolicy` implementation as default load balancing policy. The new policy attempts to fairly distribute the load based on the amount of in-flight request per hosts. The local replicas are initially shuffled and [between the first two nodes in the shuffled list, the one with fewer in-flight requests is selected as coordinator](https://www.eecs.harvard.edu/%7Emichaelm/postscripts/mythesis.pdf) . ### Upgrade guide for DSE driver users[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#upgrade-guide-for-dse-driver-users) The DSE driver and the Apache Cassandra driver have been merged into a single package. There’s a dedicated [guide for DSE driver users that plan to migrate to the `cassandra-driver`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/upgrade-from-dse-driver) . * * * 4.2[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#4-2) --------------------------------------------------------------------------------------------- ### Tuple constructor with one parameter[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#tuple-constructor-with-one-parameter) The `Tuple` constructor had an undocumented behaviour when invoked with a single parameter which was an `Array`, the driver used the `Array` instance as `Tuple` elements. We removed this behaviour that was used internally. `Tuple.fromArray()` method should be used to build a `Tuple` from an `Array` of elements. 4.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#4-0) --------------------------------------------------------------------------------------------- The following is a list of changes made in version 4.0 of the driver that are relevant when upgrading from version 3.x. ### localDataCenter is now a required Client option[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#local-data-center-is-now-a-required-client-option) When using `DCAwareRoundRobinPolicy`, which is used by default, a local data center must now be provided to the `Client` options parameter as `localDataCenter`. This is necessary to prevent routing requests to nodes in remote data centers. ### Selection of contact points is now evaluated in random order[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#selection-of-contact-points-is-now-evaluated-in-random-order) The list of contact points provided as a Client option is now shuffled before selecting a node to connect to as part of initialization. This change was made for instances where configuration is shared between many clients. In this case, it is better to distribute initial connections to different nodes in the cluster instead of choosing the same node each time as the initial connection makes a number of queries to discover cluster topology and schema. ### Changes to the retry and load-balancing policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#changes-to-the-retry-and-load-balancing-policies) `ExecutionOptions` is introduced as a wrapper around the `QueryOptions`. The `ExecutionOptions` contains getter methods to obtain the values of each option, defaulting to the execution profile options or the ones defined in the `ClientOptions`. Previously, a shallow copy of the provided `QueryOptions` was used, resulting in unnecessary allocations and evaluations. The `LoadBalancingPolicy` and `RetryPolicy` base classes changed method signatures to take `ExecutionOptions` instances as argument instead of `QueryOptions`. Note that no breaking change was introduced for execution methods such as `Client#execute()`, `Client#batch()`, `Client#eachRow()` and `Client#stream()`. This change only affects custom implementations of the policies. ### Query idempotency and retries[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#query-idempotency-and-retries) The configured `RetryPolicy` is not engaged when a query errors with a `WriteTimeoutException` or request error and the query was not idempotent. In order to control the possibility of retrying when an timeout/error is encountered, you must mark the query as idempotent. You can define it at `QueryOptions` level when calling the execution methods. client.execute(query, params, { prepare: true, isIdempotent: true }) Additionally, you can define the default idempotence for all executions when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, queryOptions: { isIdempotent: true } }); Previously, a similar behaviour was available using `IdempotenceAwareRetryPolicy`, that is now marked as deprecated. ### Removed `retryOnTimeout` property of `QueryOptions`[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#removed-retry-ontimeout-property-of-query-options) `retryOnTimeout`, the property that controlled whether a request should be tried when a response wasn’t obtained after a period of time is no longer available. The behaviour should be now controlled using `onRequestError()` method on the `RetryPolicy` for idempotent queries. ### Changes on `OperationInfo` of the retry module[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#changes-on-operation-info-of-the-retry-module) The retry policy methods takes [`OperationInfo`](https://docs.datastax.com/en/developer/nodejs-driver/latest/api/module.policies/module.retry/type.OperationInfo/) as a parameter. Some `OperationInfo` properties changes or were removed. * Deprecated properties `handler`, `request` and `retryOnTimeout` were removed. * `options` property was replaced by `executionOptions` which is an instance of `ExecutionOptions`. ### Removed `meta` property from `ResultSet`[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#removed-meta-property-from-result-set) On earlier versions of the driver, the `ResultSet` exposed the property `meta` which contained the raw result metadata. This property was removed in the latest version. ### Removed `DCAwareRoundRobinPolicy` `usedHostsPerRemoteDC` constructor parameter[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#removed-dc-aware-round-robin-policy-used-hosts-per-remotedc-constructor-parameter) `DCAwareRoundRobinPolicy` no longer supports routing queries to hosts in remote data centers. Because of this `usedHostsPerRemoteDC` has been removed as a constructor parameter. This change was made because handling data center outages is better suited at a service level rather than within an application client. * * * 3.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#3-0) --------------------------------------------------------------------------------------------- ### Changes in CQL aggregates metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#changes-in-cql-aggregates-metadata) The `initCondition` property of `Aggregate`, the class that represents the metadata information of a CQL aggregate, changes from `Object` to `String`. * * * 2.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#2-0) --------------------------------------------------------------------------------------------- The following is a list of changes made in version 2.0 of the driver that are relevant when upgrading from version 1.x. ### API Changes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/index.html#api-changes) 1. `uuid` and `timeuuid` values are decoded as [`Uuid`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/uuids) and [`TimeUuid`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/uuids) instances. 2. `decimal` values are decoded as [`BigDecimal`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) instances. 3. `varint` values are decoded as [`Integer`](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/numerical) instances. 4. `inet` values are decoded as `InetAddress` instances. --- # DataStax Node.js Driver - Concurrent Execution API [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/concurrent-api/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/concurrent-api/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/concurrent-api/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/concurrent-api/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Concurrent Execution API[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/index.html#concurrent-execution-api) ================================================================================================================================================= The DataStax Node.js driver provides a set of [utilities for concurrent query execution](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.concurrent/) , to facilitate executing multiple queries in parallel while controlling the concurrency level. The concurrent execution API can useful when, for example, you want to insert a large group of rows from an `Array` or a `Stream` and evaluate failures, if any, at the end. Usage samples[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/index.html#usage-samples) --------------------------------------------------------------------------------------------------------------------------- ### Using a fixed query and an Array of arrays as parameters[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/index.html#using-a-fixed-query-and-an-array-of-arrays-as-parameters) When an `Array` of arrays is provided, one query per each item in the `Array` will be executed, using each item as parameters. const query = 'INSERT INTO table1 (id, value) VALUES (?, ?)'; const parameters = [[1, 'a'], [2, 'b'], [3, 'c'], ]; // ... const result = await executeConcurrent(client, query, parameters); You can visit the [code examples in the driver repository](https://github.com/datastax/nodejs-driver/tree/master/examples) to check out a working example. ### Using a fixed query and a readable stream[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/index.html#using-a-fixed-query-and-a-readable-stream) When a `Stream` instance is provided the driver will read from the input stream and execute one query per item emitted. The driver will throttle reads of the input stream based on the concurrency level configured and the amount of current in-flight requests. The `Stream` instance should be a readable, in object mode, and emit `Array` instances. Per each item emitted, one query will be executed. const stream = csvStream.pipe(transformLineToArrayStream); const result = await executeConcurrent(client, query, stream); ### Using a different queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/index.html#using-a-different-queries) const queryAndParameters = [\ { query: 'INSERT INTO videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ { query: 'INSERT INTO user_videos (user_id, id, name) VALUES (?, ?, ?)',\ params: [ userId, id, name ] },\ { query: 'INSERT INTO latest_videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ ]; const result = await executeConcurrent(client, queryAndParameters); ### Execute all queries and deal with execution errors at the end[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/index.html#execute-all-queries-and-deal-with-execution-errors-at-the-end) When setting `raiseOnFirstError` to `false`, the driver will continue to execute the queries even when one or more errors are encountered. The returned `Promise` will be resolved and you can inspect the property `errors` to obtain each individual error information. const result = await executeConcurrent(client, query, parameters, { raiseOnFirstError: false }); for (let err of result.errors) { // ... } ### Defining concurrency level[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/index.html#defining-concurrency-level) Use the `concurrencyLevel` option property to set the maximum amount of requests that can be executed simultaneously. It defaults to `100`. const result = await executeConcurrent(client, query, parameters, { concurrencyLevel: 200 }); Note that increasing the amount of simultaneous requests will result in further queueing at the driver level and the server nodes level. You should find the optimal to get high throughput and low latency, based on your cluster size and hardware specifications. Using a higher concurrency level setting than optimal might result in query timeouts. ### Collecting all the ResultSet instances of each individual execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/index.html#collecting-all-the-result-set-instances-of-each-individual-execution) In the case you want the driver to collect each individual `ResultSet` instance, you can use the `collectResults` flag. const result = await executeConcurrent(client, query, parameters, { collectResults: true }); for (let rs of result.resultItems) { // ... } --- # DataStax Node.js Driver - Authentication [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/auth/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/auth/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/auth/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/index.html#authentication) =================================================================================================================== The driver includes three authentication providers: * `PlainTextAuthProvider`: Plain-text authentication for Apache Cassandra and DSE. * `DsePlainTextAuthProvider`: Plain-text authentication for DSE unified auth. * `DseGssapiAuthProvider`: GSSAPI authentication for DSE. In case you are using plain-text authentication on the server, you can set the `credentials` when creating the `Client` instance. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints, localDataCenter, credentials: { username: 'my_username', password: 'my_p@ssword1!' } }); Setting the authentication provider[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/index.html#setting-the-authentication-provider) ------------------------------------------------------------------------------------------------------------------------------------------------------------- For other authentication methods, you can configure the provider in the `Client` options: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints, localDataCenter, authProvider: new cassandra.auth.DseGssapiAuthProvider() }); Note that to use the `DseGssapiAuthProvider` you need to add the dependency to `kerberos` version `~1.0.0` in your application. DSE Unified Authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/index.html#dse-unified-authentication) ------------------------------------------------------------------------------------------------------------------------------------------- DSE Unified Authentication allows you to: * Proxy Login: Authenticate using a fixed set of authentication credentials but allow authorization of resources based on another user id. * Proxy Execute: Authenticate using a fixed set of authentication credentials but execute requests based on another user id. ### Proxy Login[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/index.html#proxy-login) Proxy login allows you to authenticate with a user but act as another one. You need to ensure the authenticated user has the permission to use the authorization of resources of the other user. In the following example, we allow user “ben” to authenticate but use the authorization of “alice”. We grant login permission to “ben” by using a `GRANT` CQL query: GRANT PROXY.LOGIN ON ROLE 'alice' TO 'ben' Once “ben” is granted proxy login as “alice”: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: [ 'host1', 'host2' ], localDataCenter, authProvider: new cassandra.auth.DsePlainTextAuthProvider('ben', 'ben', 'alice') }); // All requests will be executed using the authorizationId 'alice' client.execute(query, params, { prepare: true }); ### Proxy Execute[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/index.html#proxy-execute) Proxy execute allows you to execute requests as another user than the authenticated one. You need to ensure the authenticated user has the permission to use the authorization of resources of the specified user. In the following example will allow the user “ben” to execute requests as “alice”: We grant execute permission to “ben” by using a `GRANT` CQL query: GRANT PROXY.EXECUTE on role user1 to server Once “ben” is granted permission to execute queries as “alice”: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: [ 'host1', 'host2' ], localDataCenter, authProvider: new cassandra.auth.DsePlainTextAuthProvider('ben', 'ben') }); // The following requests will be executed as 'alice' client.execute(query, params, { prepare: true, executeAs: 'alice' }); Please see the [official documentation](https://docs.datastax.com/en/latest-dse/datastax_enterprise/unifiedAuth/unifiedAuthTOC.html) for more details. --- # DataStax Node.js Driver - Native protocol [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/native-protocol/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/native-protocol/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/native-protocol/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/native-protocol/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/native-protocol/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/native-protocol/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/native-protocol/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/native-protocol/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/native-protocol/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/native-protocol/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/native-protocol/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/native-protocol/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/native-protocol/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/native-protocol/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/native-protocol/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/native-protocol/) * Native protocol[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/native-protocol/index.html#native-protocol) ================================================================================================================================ The native protocol defines the format of the binary messages exchanged between the driver and Cassandra over TCP. As a driver user what you need to be aware of is that some Cassandra features are only available with a specific protocol version, but if you are interested in the technical details you can check [the specification in the Cassandra codebase](https://git-wip-us.apache.org/repos/asf?p=cassandra.git;a=tree;f=doc;hb=HEAD) . Controlling the protocol version[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/native-protocol/index.html#controlling-the-protocol-version) ------------------------------------------------------------------------------------------------------------------------------------------------------------------ By default, the driver uses the highest protocol version supported by the driver and the Cassandra cluster. If you want to limit the protocol version to use, you do so in the protocol options. const cassandra = require('cassandra-driver'); const protocolVersion = cassandra.types.protocolVersion; const client = new cassandra.Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.v3 } }); Mixed cluster versions and rolling upgrades[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/native-protocol/index.html#mixed-cluster-versions-and-rolling-upgrades) ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The protocol version used between the client and the Cassandra cluster is negotiated upon establishing the first connection. For clusters with nodes running mixed versions of Cassandra and during rolling upgrades this could represent an issue that could lead to limited availability. To exemplify the above, consider a mixed cluster having nodes running either Cassandra 2.1 or 2.0. * The first contact point is a 2.1 host, so the driver negotiates native protocol version 3 * While connecting to the rest of the cluster, the driver contacts a 2.0 host using native protocol version 3, which fails; an error is logged and this host will be permanently ignored. For these scenarios, mixed version clusters and rolling upgrades, it is strongly recommended to set the maximum protocol version when initializing the client: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.v2 } }); And switching it to the highest protocol version once the upgrade is completed, by leaving the maximum protocol version unspecified or by using `protocolVersion.maxSupported`: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxVersion: protocolVersion.maxSupported } }); --- # DataStax Node.js Driver - Encoder [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Encoder/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.Encoder/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.Encoder/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.Encoder/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.Encoder/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.Encoder/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.Encoder/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.Encoder/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.Encoder/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.Encoder/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.Encoder/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.Encoder/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.Encoder/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.Encoder/) * class Encoder[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/index.html#class-encoder) ===================================================================================================================== Global This class is global Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/index.html#constructor) ----------------------------------------------------------------------------------------------------------------- new ### Encoder[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/index.html#encoder) (`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` protocolVersion, `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) ` options) Serializes and deserializes to and from a CQL type and a Javascript Type. Parameters: | Name | Type | Description | | --- | --- | --- | | protocolVersion | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | | options | `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) ` | | Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/index.html#methods) --------------------------------------------------------------------------------------------------------- ### decode[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/index.html#decode) (`Buffer` buffer, `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` type) Decodes Cassandra bytes into Javascript values. This is part of an **experimental** API, this can be changed future releases. Parameters: | Name | Type | Description | | --- | --- | --- | | buffer | `Buffer` | Raw buffer to be decoded. | | type | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | An object containing the data type `code` and `info`. | | type.code | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Type code. | | type.info optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Additional information on the type for complex / nested types. | ### encode[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/index.html#encode) (`*` value, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) `, `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` typeInfo\]) Encodes Javascript types into Buffer according to the Cassandra protocol. This is part of an **experimental** API, this can be changed future releases. Parameters: | Name | Type | Description | | --- | --- | --- | | value | `*` | The value to be converted. | | typeInfo optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) `, `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The type information.

It can be either a:

* A `String` representing the data type.
* A `Number` with one of the values of `[dataTypes](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/#constant.data-types) `.
* An `Object` containing the `type.code` as one of the values of `[dataTypes](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/#constant.data-types) ` and `type.info`. | Returns: | Type | Description | | --- | --- | | `Buffer` | | --- # DataStax Node.js Driver - QueryOptions [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/type.QueryOptions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.QueryOptions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/type.QueryOptions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/type.QueryOptions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/type.QueryOptions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/type.QueryOptions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/type.QueryOptions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/type.QueryOptions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/type.QueryOptions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/type.QueryOptions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/type.QueryOptions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/type.QueryOptions/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/type.QueryOptions/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/type.QueryOptions/) * type QueryOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/index.html#type-query-options) ================================================================================================================================== Query options Global This type is global Properties: | Name | Type | Description | | --- | --- | --- | | autoPage | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the driver must retrieve the following result pages automatically.

This setting is only considered by the `[Client#eachRow()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#function.each-row) ` method. For more information, check the `paging results documentation`. | | captureStackTrace | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the stack trace before the query execution should be maintained.

Useful for debugging purposes, it should be set to `false` under production environment as it adds an unnecessary overhead to each execution.

Default: false. | | consistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | `[Consistency level](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/#constant.consistencies) `.

Defaults to `localOne` for Apache Cassandra and DSE deployments. For DataStax Astra, it defaults to `localQuorum`. | | customPayload | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Key-value payload to be passed to the server. On the Cassandra side, implementations of QueryHandler can use this data. | | executeAs | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The user or role name to act as when executing this statement.

When set, it executes as a different user/role than the one currently authenticated (a.k.a. proxy execution).

This feature is only available in DSE 5.1+. | | executionProfile | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) ` | Name or instance of the `[profile](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) ` to be used for this execution. If not set, it will the use “default” execution profile. | | fetchSize | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Amount of rows to retrieve per page. | | hints | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\> | Type hints for parameters given in the query, ordered as for the parameters.

For batch queries, an array of such arrays, ordered as with the queries in the batch. | | host | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` | The host that should handle the query.

Use of this option is _heavily discouraged_ and should only be used in the following cases:

1. Querying node-local tables, such as tables in the `system` and `system_views` keyspaces.
2. Applying a series of schema changes, where it may be advantageous to execute schema changes in sequence on the same node.

Configuring a specific host causes the configured `[LoadBalancingPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.loadBalancing/class.LoadBalancingPolicy/) ` to be completely bypassed. However, if the load balancing policy dictates that the host is at a `[distance of ignored](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/#constant.distance) ` or there is no active connectivity to the host, the request will fail with a `[NoHostAvailableError](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/class.NoHostAvailableError/) `. | | isIdempotent | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Defines whether the query can be applied multiple times without changing the result beyond the initial application.

The query execution idempotence can be used at `[RetryPolicy](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.retry/class.RetryPolicy/) ` level to determine if an statement can be retried in case of request error or write timeout.

Default: `false`. | | keyspace | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Specifies the keyspace for the query. It is used for the following:

1. To indicate what keyspace the statement is applicable to (protocol V5+ only). This is useful when the query does not provide an explicit keyspace and you want to override the current `[keyspace](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#member.keyspace) `.
2. For query routing when the query operates on a different keyspace than the current `[keyspace](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#member.keyspace) `. | | logged | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the batch should be written to the batchlog. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#function.batch) `, it will be ignored by other methods. Default: true. | | counter | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if its a counter batch. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#function.batch) `, it will be ignored by other methods. Default: false. | | pageState | `Buffer` or `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Buffer or string token representing the paging state.

Useful for manual paging, if provided, the query will be executed starting from a given paging state. | | prepare | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines if the query must be executed as a prepared statement. | | readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | When defined, it overrides the default read timeout (`socketOptions.readTimeout`) in milliseconds for this execution per coordinator.

Suitable for statements for which the coordinator may allow a longer server-side timeout, for example aggregation queries.

A value of `0` disables client side read timeout for the execution. Default: `undefined`. | | retry | `RetryPolicy` | Retry policy for the query.

This property can be used to specify a different `[retry policy](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.retry/) ` to the one specified in the `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) `.policies. | | routingIndexes | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | Index of the parameters that are part of the partition key to determine the routing. | | routingKey | `Buffer` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | Partition key(s) to determine which coordinator should be used for the query. | | routingNames | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | Array of the parameters names that are part of the partition key to determine the routing. Only valid for non-prepared requests, it’s recommended that you use the prepare flag instead. | | serialConsistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Serial consistency is the consistency level for the serial phase of conditional updates. This option will be ignored for anything else that a conditional update/insert. | | timestamp | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` or `Long` | The default timestamp for the query in microseconds from the unix epoch (00:00:00, January 1st, 1970).

If provided, this will replace the server side assigned timestamp as default timestamp.

Use `[generateTimestamp()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/#function.generate-timestamp) ` utility method to generate a valid timestamp based on a Date and microseconds parts. | | traceQuery | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Enable query tracing for the execution. Use query tracing to diagnose performance problems related to query executions. Default: false.

To retrieve trace, you can call `[Metadata.getTrace()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/class.Metadata/#function.get-trace) ` method. | | graphOptions | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Default options for graph query executions.

These options are meant to provide defaults for all graph query executions. Consider using `[execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) ` if you plan to reuse different set of options across different query executions. | | graphOptions.language | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph language to use in graph queries. Default: `'gremlin-groovy'`. | | graphOptions.name | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph name to be used in all graph queries.

This property is required but there is no default value for it. This value can be overridden at query level. | | graphOptions.readConsistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Overrides the `[consistency level](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/#constant.consistencies) ` defined in the query options for graph read queries. | | graphOptions.readTimeout | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Overrides the default per-host read timeout (in milliseconds) for all graph queries. Default: `0`.

Use `null` to reset the value and use the default on `socketOptions.readTimeout` . | | graphOptions.source | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph traversal source name to use in graph queries. Default: `'g'`. | | graphOptions.writeConsistency | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | Overrides the \[consistency level\]`[consistencies](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/#constant.consistencies) ` defined in the query options for graph write queries. | --- # DataStax Node.js Driver - Host [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.Host/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.Host/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.Host/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.Host/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.Host/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.Host/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.Host/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.Host/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.Host/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.Host/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.Host/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.Host/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.Host/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.Host/) * class Host[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#class-host) ============================================================================================================ Represents a Cassandra node. Global This class is global Augments[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#augments) -------------------------------------------------------------------------------------------------------- * `[EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) ` Members[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#members) ------------------------------------------------------------------------------------------------------ `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### address[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#address) Gets ip address and port number of the node separated by `:`. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### cassandraVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#cassandra-version) Gets string containing the Cassandra version. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### datacenter[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#datacenter) Gets data center name of the node. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### dseVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#dse-version) Gets string containing the DSE version or null if not set. `Uuid` ### hostId[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#host-id) Gets the id of the host. This identifier is used by the server for internal communication / gossip. `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### rack[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#rack) Gets rack name of the node. `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` ### tokens[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#tokens) Gets the tokens assigned to the node. `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`string`\> ### workloads[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#workloads) Gets the DSE Workloads the host is running. This is based on the “workload” or “workloads” columns in {@code system.local} and {@code system.peers}. Workload labels may vary depending on the DSE version in use;e.g. DSE 5.1 may report two distinct workloads: `Search` and `Analytics`, while DSE 5.0 would report a single `SearchAnalytics` workload instead. The driver simply returns the workload labels as reported by DSE, without any form of pre-processing. When the information is unavailable, this property returns an empty array. Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#constructor) -------------------------------------------------------------------------------------------------------------- new ### Host[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#host) () Creates a new Host instance. Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#methods) ------------------------------------------------------------------------------------------------------ ### canBeConsideredAsUp[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#can-beconsidered-asup) () Determines if the host can be considered as UP. Deprecated: Use `Host#isUp()` instead. Returns: | Type | Description | | --- | --- | | `boolean` | | ### getCassandraVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#get-cassandra-version) () Returns an array containing the Cassandra Version as an Array of Numbers having the major version in the first position. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) `\> | | ### getDseVersion[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#get-dse-version) () Gets the DSE version of the host as an Array, containing the major version in the first position. In case the cluster is not a DSE cluster, it returns an empty Array. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` | | ### isUp[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/index.html#is-up) () Determines if the node is UP now (seen as UP by the driver). Returns: | Type | Description | | --- | --- | | `boolean` | | --- # DataStax Node.js Driver - Query warnings [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-warnings/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-warnings/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-warnings/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-warnings/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/query-warnings/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/query-warnings/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/query-warnings/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/query-warnings/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/query-warnings/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/query-warnings/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/query-warnings/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/query-warnings/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/query-warnings/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/query-warnings/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/query-warnings/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/query-warnings/) * Query warnings[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-warnings/index.html#query-warnings) ============================================================================================================================= When a query is considered to be harmful for the overall cluster, Cassandra issues a warning that is written to the Cassandra logs. From Cassandra 2.2, [these warnings are also returned to the client drivers](https://issues.apache.org/jira/browse/CASSANDRA-8930) . In the driver, these warnings are [returned in the ResultSet property information](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.types/class.ResultSet/) . The warning is still written to the [driver logs](https://docs.datastax.com/en/developer/nodejs-driver/4.5/#logging) . --- # DataStax Node.js Driver - errors [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.errors/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.errors/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.errors/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.errors/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.errors/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.errors/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.errors/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/module.errors/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/module.errors/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/module.errors/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/module.errors/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/module.errors/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/module.errors/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/module.errors/) * module errors[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/index.html#module-errors) ===================================================================================================================== Contains the error classes exposed by the driver. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/index.html#classes) --------------------------------------------------------------------------------------------------------- * `[NoHostAvailableError](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/class.NoHostAvailableError/) ` * `[ResponseError](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/class.ResponseError/) ` * `[DriverInternalError](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/class.DriverInternalError/) ` * `[AuthenticationError](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/class.AuthenticationError/) ` * `[ArgumentError](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/class.ArgumentError/) ` * `[OperationTimedOutError](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/class.OperationTimedOutError/) ` * `[NotSupportedError](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/class.NotSupportedError/) ` * `[BusyConnectionError](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/class.BusyConnectionError/) ` --- # DataStax Node.js Driver - Getting Started [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/getting-started/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/getting-started/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/getting-started/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/getting-started/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/getting-started/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/getting-started/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/getting-started/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/getting-started/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/getting-started/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/getting-started/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/getting-started/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/getting-started/) * Getting started[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/index.html#getting-started) ======================================================================================================================= Getting started with the DataStax Node.js driver for Apache Cassandra. Connecting to a cluster[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/index.html#connecting-to-a-cluster) --------------------------------------------------------------------------------------------------------------------------------------- To connect to an Apache Cassandra cluster, you need to provide the address or host name of at least one node in the cluster and the local data center (DC) name. The driver will discover all the nodes in the cluster and connect to all the nodes in the local data center. Typically, you should create only a single `Client` instance for a given Cassandra cluster and use it across your application. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); client.connect(); At this point, the driver will be connected to all the nodes in the local data center and discovered the rest of the nodes in your cluster. Even though calling `connect()` is not required (the `execute()` method internally calls to connect), it is recommended you call to `#connect()` on application startup, this way you can ensure that you start your app once your are connected to your cluster. When using [DataStax Astra](https://www.datastax.com/products/datastax-astra) you can configure your client by setting the secure bundle and the user credentials: const client = new cassandra.Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); Retrieving data[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/index.html#retrieving-data) ----------------------------------------------------------------------------------------------------------------------- The `execute()` method can be used to send a CQL query to a Cassandra node. const query = "SELECT name, email, birthdate FROM users WHERE key = 'mick-jagger'"; client.execute(query) .then(result => { const row = result.first(); // The row is an Object with column names as property keys. console.log('My name is %s and my email is %s', row['name'], row['email']); }); Execution methods in the driver return a `Promise`, you can await on the promise to be fulfilled using [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) . Note that for the rest of the documentation, Promise method `then()` and `await` will be used interchangeably. ### Using query parameters and prepared statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/index.html#using-query-parameters-and-prepared-statements) Instead of hard-coding your parameters in your query, you can use parameter markers in your queries and provide the parameters as an Array. const query = 'SELECT name, email, birthdate FROM users WHERE key = ?'; const result = await client.execute(query, ['mick-jagger']); This way you can reuse the query and forget about escaping / stringifying the parameters in your query. Additionally, if you plan to reuse a query within your application (it is generally the case, your parameter value changes but there is only a small number of different queries for a given schema), **you can benefit from using prepared statements**. Using prepared statements increases performance compared to plain executes, especially for repeated queries, as the query only needs to be parsed once by the Cassandra node. It has the **additional benefit of providing metadata of the parameters to the driver, allowing better type mapping between JavaScript and Cassandra** without the need of additional info (hints) from the user. // Recommended: use query markers for parameters const query = 'SELECT name, email, birthdate FROM users WHERE key = ?'; // Recommended: set the prepare flag in your queryOptions const result = await client.execute(query, ['mick-jagger'], { prepare: true }); See the [data types documentation to see how CQL types are mapped to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/) . Inserting data[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/index.html#inserting-data) --------------------------------------------------------------------------------------------------------------------- You can use the `#execute()` method to execute any CQL query. const query = 'INSERT INTO users (key, name, email, birthdate) VALUES (?, ?, ?)'; const params = ['mick-jagger', 'Sir Mick Jagger', 'mick@rollingstones.com', new Date(1943, 6, 26)]; await client.execute(query, params, { prepare: true }); The promise is fulfilled when the data is inserted. ### Setting the consistency level[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/index.html#setting-the-consistency-level) To specify how consistent the data must be for a given read or write operation, you can set the [consistency level](https://docs.datastax.com/en/dse/6.7/dse-arch/datastax_enterprise/dbInternals/dbIntConfigConsistency.html) per query. const { types } = cassandra; await client.execute(query, params, { consistency: types.consistencies.quorum }); The promise is fulfilled when the data has been written in the number of replicas satisfying the consistency level specified. You can also provide a default consistency level for all your queries when creating the `Client` instance (defaults to `localOne`). const client = new Client({ queryOptions: { consistency: types.consistencies.localQuorum }, // ... rest of the options }); Mapper (optional)[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/index.html#mapper-optional) ------------------------------------------------------------------------------------------------------------------------- The driver provides [a built-in object mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/) that lets you interact with your data like you would interact with a set of documents. const userVideos = await videoMapper.find({ userId }); for (let video of userVideos) { console.log(video.name); } Visit the [Getting Started with the Mapper Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/getting-started/) for more information. Authentication (optional)[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/index.html#authentication-optional) ----------------------------------------------------------------------------------------------------------------------------------------- Using an authentication provider on an auth-enabled Cassandra cluster: const authProvider = new cassandra.auth.PlainTextAuthProvider('my_user', 'p@ssword1!'); //Set the auth provider in the clientOptions when creating the Client instance const client = new Client({ contactPoints, localDataCenter, authProvider }); Working with mixed workloads[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/index.html#working-with-mixed-workloads) ------------------------------------------------------------------------------------------------------------------------------------------------- The driver features [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles) that provide a mechanism to group together a set of configuration options and reuse them across different query executions. [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles) are specially useful when dealing with different workloads like Graph and CQL workloads, allowing you to use a single `Client` instance for all workloads, for example: const client = new cassandra.Client({ contactPoints: ['host1'], localDataCenter: 'oltp-us-west', profiles: [\ new ExecutionProfile('time-series', {\ consistency: consistency.localOne,\ readTimeout: 30000,\ serialConsistency: consistency.localSerial\ }),\ new ExecutionProfile('graph', {\ loadBalancing: new DefaultLoadBalancingPolicy('graph-us-west'),\ consistency: consistency.localQuorum,\ readTimeout: 10000,\ graphOptions: { name: 'myGraph' }\ })\ ] }); // Use an execution profile for a CQL query client.execute('SELECT * FROM system.local', null, { executionProfile: 'time-series' }); // Use an execution profile for a gremlin query client.executeGraph('g.V().count()', null, { executionProfile: 'graph' }); --- # DataStax Node.js Driver - API docs [DataStax Node.js Driver 4.7 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.7 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/) * API documentation[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/index.html#api-documentation) =============================================================================================================== Top level objects Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/index.html#modules) ------------------------------------------------------------------------------------------- * `[geometry](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/) ` * `[datastax](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.datastax/) ` * `[types](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.types/) ` * `[auth](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.auth/) ` * `[policies](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.policies/) ` * `[mapping](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/) ` * `[metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metadata/) ` * `[concurrent](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.concurrent/) ` * `[errors](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.errors/) ` * `[tracker](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.tracker/) ` * `[metrics](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/) ` Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/index.html#classes) ------------------------------------------------------------------------------------------- * `[TransitionalModePlainTextAuthenticator](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.TransitionalModePlainTextAuthenticator/) ` * `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Client/) ` * `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) ` * `[ExecutionOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/) ` * `[Encoder](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Encoder/) ` * `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.Host/) ` * `[HostMap](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/) ` Types[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/index.html#types) --------------------------------------------------------------------------------------- * `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ClientOptions/) ` * `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.QueryOptions/) ` * `[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/type.ResultCallback/) ` Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/index.html#functions) ----------------------------------------------------------------------------------------------- ### encodeVector[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/index.html#encode-vector) (`CqlVector` value, `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` params) Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | value | `CqlVector` | | | params | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | ### parseVectorTypeArgs[](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/index.html#parse-vector-type-args) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` typeName, `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` stringToExclude, `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` subtypeResolveFn) Extract the (typed) arguments from a vector type Global This function is global Parameters: | Name | Type | Description | | --- | --- | --- | | typeName | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | | stringToExclude | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Leading string indicating this is a vector type (to be excluded when eval’ing args) | | subtypeResolveFn | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Function used to resolve subtype type; varies depending on type naming convention | Returns: | Type | Description | | --- | --- | | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | --- # DataStax Node.js Driver - Features [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/) * Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/index.html#features) ================================================================================================== The DataStax Node.js Driver is feature-rich and highly tunable Node.js client library for Apache Cassandra, DSE and DataStax products. Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/index.html#usage) -------------------------------------------------------------------------------------------- * [Address resolution](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/address-resolution) * [Authentication](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth) * [Batch statements](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/batch) * [Cluster and schema metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/metadata) * [Concurrent execution API](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api) * [Connecting to DataStax Astra](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/cloud) * [Connection pooling](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/connection-pooling) * [CQL data types to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes) * [Execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles) * [Fetching large result sets](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/paging) * [Geospatial types support](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/geotypes) * [Graph support](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support) * [Logging](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/logging) * [Mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper) * [Native protocol](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/native-protocol) * [Parameterized queries](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/parameterized-queries) * [Promise and callback support](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/promise-callback) * [Query timestamps](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps) * [Query warnings](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-warnings) * [Speculative query executions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions) * [TLS/SSL](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tls) * [Tuning policies](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies) * [User-defined functions and aggregates](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/udfs) --- # DataStax Node.js Driver - Connecting to your DataStax Astra database using a secure connection bundle [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/cloud/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/cloud/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/cloud/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/cloud/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/cloud/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/cloud/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Connecting to your DataStax Astra database using a secure connection bundle[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/cloud/index.html#connecting-to-your-data-stax-astra-database-using-a-secure-connection-bundle) =============================================================================================================================================================================================================================================== Quickstart[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/cloud/index.html#quickstart) ------------------------------------------------------------------------------------------------------------ Use the `ClientOptions` property `cloud` to connect to your [DataStax Astra database](https://www.datastax.com/products/datastax-astra) using your secure connection bundle (`secure-connect-DATABASE_NAME.zip`) and `credentials` property to provide your [CQL credentials](https://cassandra.apache.org/doc/latest/cql/security.html#cql-roles) . Here is an example of the minimum configuration needed to connect to your DataStax Astra database using the secure connection bundle: const client = new Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); Configurable settings when using a secure connection bundle[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/cloud/index.html#configurable-settings-when-using-a-secure-connection-bundle) -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can configure your `Client` instance using other `ClientOptions` properties, for example: const client = new Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' }, keyspace: 'my_ks' }); Note that `contactPoints` and `sslOptions` should not be set when using `secureConnectBundle`. --- # DataStax Node.js Driver - Logging [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/logging/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/logging/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/logging/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/logging/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/logging/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/logging/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/logging/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/logging/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/logging/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Logging[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/logging/index.html#logging) ======================================================================================================== The DataStax Node.js driver uses [events](https://nodejs.org/api/events.html) to expose logging information decoupled from any specific logging framework. The driver’s `Client` inherits from [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) and it triggers `'log'` events. client.on('log', (level, loggerName, message, furtherInfo) => { console.log(`${level} - ${loggerName}: ${message}`); }); The level being passed to the listener can be `'verbose'`, `'info'`, `'warning'` or `'error'`. `verbose` level is only suitable for debugging and it’s usually too noisy. We recommend that you gather logging events from `info` and above on production environments. Tracking query latency and size[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/logging/index.html#tracking-query-latency-and-size) -------------------------------------------------------------------------------------------------------------------------------------------------------- The `RequestLogger` logs queries executed by the driver and it allows tracking requests considered slow and/or large. A request is considered “slow” when it takes longer to complete than a configured threshold in milliseconds. A request is considered to be large when the request size is greater than a configured threshold in bytes. To turn on this feature, you first need to create an instance of `RequestLogger` and use it when creating the `Client` instance: const cassandra = require('cassandra-driver'); const requestTracker = new cassandra.tracker.RequestLogger({ slowThreshold: 1000 }); const client = new Client({ contactPoints, localDataCenter, requestTracker }); You can subscribe to `'slow'`, `'large'`, `'normal'` and `'failure'` events using the emitter object instance: requestTracker.emitter.on('slow', message => console.log(message)); An example message would be: [10.1.1.1:9042] Slow request, took 305 ms (request size 35 bytes / response size 1 KB): SELECT col1, col2 FROM table1 WHERE id = ? [1] Note that events will be emitted only when certain options are defined: * `'slow'` events will only be emitted if `slowThreshold` is set. * `'large'` events will only be emitted if `requestSizeThreshold` is set. * `'normal'` events will only be emitted if `logNormalRequests` is set to `true`. This setting can be changed at runtime using the `RequestLogger` property of the same name. * `'failure'` events will only be emitted if `logErroredRequests` is set to `true`. This setting can be changed at runtime using the property of the same name. You can provide your own tracker implementing `RequestTracker` interface. --- # DataStax Node.js Driver - Mapper [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/mapper/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/mapper/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/mapper/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/mapper/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/mapper/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Mapper[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/index.html#mapper) ===================================================================================================== The driver provides an object mapper that lets you interact with your data like you would interact with a set of documents. Mapper Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/index.html#mapper-features) ----------------------------------------------------------------------------------------------------------------------- * No / minimal configuration required: no need to specify the schema manually, it uses the driver schema metadata * Support denormalized schemas and materialized views: one model can be mapped to multiple tables * Convention-based mapping * Support bypassing query generation / bring your own queries and map results * Minimal performance impact compared to the core driver Basic Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/index.html#basic-usage) --------------------------------------------------------------------------------------------------------------- Retrieving objects from the database: const videos = await videoMapper.find({ userId }); for (let video of videos) { console.log(video.name); } Updating an object from the database: await videoMapper.update({ id, userId, name, addedDate, description }); Note that execution methods return a `Promise`, to simplify the code examples in the documentation [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) are used. You can continue by reading the [Getting Started Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/getting-started/) or other topics in the Mapper documentation: * [Getting Started Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/getting-started/) * [Queries](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/queries/) * [Defining Mappings](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/defining-mappings/) * [Limitations and FAQ](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/limitations-and-faq/) --- # DataStax Node.js Driver - TLS/SSL [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tls/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tls/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tls/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tls/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/tls/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/tls/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/tls/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/tls/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/tls/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * TLS/SSL[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tls/index.html#tls-ssl) ==================================================================================================== You can secure traffic between the driver and Apache Cassandra with TLS/SSL. There are two aspects to that: * Client-to-node encryption, where the traffic is encrypted and the client verifies the identity of the Apache Cassandra nodes it connects to. * Optional client certificate authentication, where Apache Cassandra nodes also verify the identity of the client. This section describes the driver-side configuration, it assumes that you’ve already configured SSL encryption in Apache Cassandra, you can checkout the [server documentation that covers the basic procedures](https://docs.datastax.com/en/cassandra/3.0/cassandra/configuration/secureSSLClientToNode.html) . Driver configuration[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tls/index.html#driver-configuration) ------------------------------------------------------------------------------------------------------------------------------ Use `sslOptions` property in the [`ClientOptions`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) to enable client TLS/SSL encryption: const client = new Client({ contactPoints, localDataCenter, sslOptions: { rejectUnauthorized: true }}); await client.connect(); You can define the same object properties as the options in the [standard Node.js `tls.connect()` method](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) . The main difference is that server certificate validation against the list of supplied CAs is disabled by default. You should specify `rejectUnauthorized: true` in your settings to enable it. ### Enabling client certificate authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tls/index.html#enabling-client-certificate-authentication) Much like in [Node.js standard tls module](https://nodejs.org/api/tls.html) , you can use `cert` and `key` properties to provide the certificate chain and private key. Additionally, you can override the trusted CA certificates using `ca` property: const sslOptions = { // Necessary only if the server requires client certificate authentication. key: fs.readFileSync('client-key.pem'), cert: fs.readFileSync('client-cert.pem'), // Necessary only if the server uses a self-signed certificate. ca: [ fs.readFileSync('server-cert.pem') ], rejectUnauthorized: true }; const client = new Client({ contactPoints, localDataCenter, sslOptions }); --- # DataStax Node.js Driver - HostMap [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.HostMap/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.HostMap/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.HostMap/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.HostMap/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.HostMap/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.HostMap/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.HostMap/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.HostMap/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.HostMap/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.HostMap/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.HostMap/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.HostMap/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.HostMap/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.HostMap/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/class.HostMap/) * class HostMap[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#class-host-map) ====================================================================================================================== Represents an associative-array of `[hosts](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` that can be iterated. It creates an internal copy when adding or removing, making it safe to iterate using the values() method within async operations. Global This class is global Augments[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#augments) ----------------------------------------------------------------------------------------------------------- * `events.EventEmitter` Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#constructor) ----------------------------------------------------------------------------------------------------------------- new ### HostMap[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#host-map) () Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#methods) --------------------------------------------------------------------------------------------------------- ### clear[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#clear) () Removes all items from the map. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) `\> | The previous items | ### forEach[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#for-each) (callback) Executes a provided function once per map element. Parameters: | Name | Type | Description | | --- | --- | --- | | callback | | | ### get[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#get) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` key) Gets a `[host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` by key or undefined if not found. Parameters: | Name | Type | Description | | --- | --- | --- | | key | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | Returns: | Type | Description | | --- | --- | | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` | | ### keys[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#keys) () Returns an array of host addresses. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) `\> | | ### remove[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#remove) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` key) Removes an item from the map. Parameters: | Name | Type | Description | | --- | --- | --- | | key | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The key of the host | ### removeMultiple[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#remove-multiple) (`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) `\> keys) Removes multiple hosts from the map. Parameters: | Name | Type | Description | | --- | --- | --- | | keys | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) `\> | | ### set[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#set) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` key, `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` value) Adds a new item to the map. Parameters: | Name | Type | Description | | --- | --- | --- | | key | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The key of the host | | value | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` | The host to be added | ### values[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/index.html#values) () Returns a shallow copy of the values of the map. Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) `\> | | --- # DataStax Node.js Driver - Fetching large result sets [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/paging/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/paging/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/paging/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/paging/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/paging/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/paging/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/paging/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/paging/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/paging/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/paging/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/paging/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/paging/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/paging/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/paging/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/paging/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/paging/) * Fetching large result sets[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/paging/index.html#fetching-large-result-sets) ============================================================================================================================================= When dealing with a large number of rows, the driver breaks the result into pages, only requesting a limited number of rows each time (`5000` being the default `fetchSize`). To retrieve the rows beyond this default size, use one of the following paging mechanisms. Automatic paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/paging/index.html#automatic-paging) ------------------------------------------------------------------------------------------------------------------------- The driver supports asynchronous iteration of the `ResultSet` using the built-in [Async Iterator](https://github.com/tc39/proposal-async-iteration) , fetching the following result pages after the previous one has been yielded. Large result sets can be iterated using the [`for await ... of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) statement: const result = await client.execute(query, params, { prepare: true }); for await (const row of result) { console.log(row[columnName]); } Under the hood, the driver will get all the rows of the query result using multiple requests. Initially, when calling `execute()` it will retrieve the first page of results according to the fetch size (defaults to `5000`). If there are additional rows, those will be retrieved once the async iterator yielded the rows from the previous page. If needed, you can use `isPaged()` method of `ResultSet` instance to determine whether there are more pages of results than initially fetched. Note that using the async iterator will not affect the internal state of the `ResultSet` instance. You should avoid using both `rows` property that contains the row instances of the first page of results, and the async iterator, that will yield all the rows in the result regardless on the number of pages. Manual paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/paging/index.html#manual-paging) ------------------------------------------------------------------------------------------------------------------- Sometimes it is convenient to save the paging state in order to restore it later. For example, consider a stateless web service that displays a list of results with a link to the next page. When the user clicks that link, we want to run the exact same query, except that the iteration should start where we stopped on the previous page. To do so, the driver exposes a `pagingState` object that represents where we were in the result set when the last page was fetched: const options = { prepare: true , fetchSize: 1000 }; const result = await client.execute(query, parameters, options); // Property 'rows' will contain only the amount of items of the first page (max 1000 in this case) const rows = result.rows; // Store the page state let pageState = result.pageState; In the next request, use the `pageState` to fetch the following rows. // Use the pageState in the queryOptions to continue where you left it. const options = { pageState, prepare: true, fetchSize: 1000 }; const result = await client.execute(query, parameters, options); // Following rows up to fetch size (1000) const rows = result.rows; // Store the next paging state. pageState = result.pageState; Saving the paging state works well when you only let the user move from one page to the next. But it doesn’t allow arbitrary jumps (like “go directly to page 10”), because you can’t fetch a page unless you have the paging state of the previous one. Such a feature would require offset queries, which are not natively supported by Apache Cassandra. **Note**: The page state token can be manipulated to retrieve other results within the same column family, so it is not safe to expose it to the users in plain text. Row streams[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/paging/index.html#row-streams) --------------------------------------------------------------------------------------------------------------- If you want to handle a large result set as a [`Stream`](https://nodejs.org/api/stream.html) of rows, you can use `stream()` method of the `Client` instance. The `stream()` method automatically fetches the following pages, yielding the rows as they come through the network and retrieving the following page only after the previous rows were read (throttling). client.stream(query, parameters, options) .on('readable', function () { // readable is emitted as soon a row is received and parsed let row; while (row = this.read()) { // process row } }) .on('end', function () { // emitted when all rows have been retrieved and read }); --- # DataStax Node.js Driver - CQL data types to JavaScript types [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/datatypes/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/datatypes/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/datatypes/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/datatypes/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/datatypes/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/datatypes/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/datatypes/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/datatypes/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/datatypes/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/datatypes/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/datatypes/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/datatypes/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/datatypes/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/datatypes/) * CQL data types to JavaScript types[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/index.html#cql-data-types-to-java-script-types) ================================================================================================================================================================= When retrieving the value of a column from a `Row` object, the value is typed according to the following table. | CQL data type | JavaScript type | | --- | --- | | ascii | String | | bigint | [Long / BigInt](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) | | blob | [Buffer](https://nodejs.org/api/buffer.html) | | boolean | Boolean | | counter | [Long / BigInt](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) | | date | [LocalDate](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/datetime) | | decimal | [BigDecimal](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) | | double | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) | | duration | [Duration](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.types/class.Duration/) | | float | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) | | inet | [InetAddress](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.types/class.InetAddress/) | | int | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) | | list | [Array](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/collections) | | map | [Object / ECMAScript 6 Map](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/collections) | | set | [Array / ECMAScript 6 Set](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/collections) | | smallint | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) | | text | String | | time | [LocalTime](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/datetime) | | timestamp | [Date](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/datetime) | | timeuuid | [TimeUuid](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/uuids) | | tinyint | [Number](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) | | tuple | [Tuple](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/tuples) | | uuid | [Uuid](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/uuids) | | varchar | String | | varint | [Integer](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) | Encoding data[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/index.html#encoding-data) ---------------------------------------------------------------------------------------------------------------------- When encoding data, on a normal execute with parameters, the driver tries to guess the target type based on the input type. Values of type `Number` will be encoded as `double` (because `Number` is IEEE 754 double). Consider the following example: const key = 1000; client.execute('SELECT * FROM table1 where key = ?', [ key ]); If the key column is of type `int`, the execution fails. There are two possible ways to avoid this type of problem, as detailed below. ### Prepare your queries (recommended)[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/index.html#prepare-your-queries-recommended) Using prepared statements provides multiple benefits. Prepared statements are parsed and prepared on the Cassandra nodes and are ready for future execution. Also, the driver retrieves information about the parameter types which allows an **accurate mapping between a JavaScript type and a Cassandra type**. Using the previous example, setting the `prepare` flag in the queryOptions will fix it: // Prepare the query before execution client.execute('SELECT * FROM table1 where key = ?', [ key ], { prepare : true }); When using prepared statements, the driver prepares the statement once on each host to execute multiple times. ### Hinting the target data type[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/index.html#hinting-the-target-data-type) Providing parameter hints in the query options is another way around it. // Hint that the first parameter is an integer client.execute('SELECT * FROM table1 where key = ?', [ key ], { hints : ['int'] }); --- # DataStax Node.js Driver - Tuning policies [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tuning-policies/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tuning-policies/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tuning-policies/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/tuning-policies/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/tuning-policies/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/tuning-policies/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/tuning-policies/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/tuning-policies/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/tuning-policies/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/tuning-policies/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/tuning-policies/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/tuning-policies/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/tuning-policies/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/tuning-policies/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/tuning-policies/) * Tuning policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/index.html#tuning-policies) ================================================================================================================================ Load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/index.html#load-balancing-policy) -------------------------------------------------------------------------------------------------------------------------------------------- The load balancing policy interface consists of three methods: * `#distance(Host host)`: determines the distance to the specified host. The values are `distance.ignored`, `distance.local`, and `distance.remote`. * `#init(client, hosts, callback)`: initializes the policy. The driver calls this method only once and before any other method calls are made. * `#newQueryPlan(keyspace, queryOptions, callback)`: executes a callback with the iterator of hosts to use for a query. Each new query calls this method. The policies are responsible for yielding a group of nodes in an specific order for the driver to use (if the first node fails, it uses the next one). There are four load-balancing policies implemented in the driver: * `DCAwareRoundRobinPolicy`: a datacenter-aware, round-robin, load-balancing policy. This policy provides round-robin queries over the node of the local datacenter. It also includes in the query plans returned a configurable number of hosts in the remote data centers, but those are always tried after the local nodes. * `RoundRobinPolicy`: a policy that yields nodes in a round-robin fashion. * `TokenAwarePolicy`: a policy that yields replica nodes for a given partition key and keyspace. The token-aware policy uses a child policy to retrieve the next nodes in case the replicas for a partition key are not available. * `WhiteListPolicy`: a policy that wraps the provided child policy but only “allow” hosts from the provided whilelist. Keep in mind however that this policy defeats somewhat the host auto-detection of the driver. As such, this policy is only useful in a few special cases or for testing, but is not optimal in general. ### Default load-balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/index.html#default-load-balancing-policy) The default load-balancing policy is `DefaultLoadBalancingPolicy`. The policy yields local replicas for a given key and, if not available, it yields nodes of the local datacenter in a round-robin manner. Reconnection policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/index.html#reconnection-policy) ---------------------------------------------------------------------------------------------------------------------------------------- The reconnection policy consists of one method: * `#newSchedule()`: creates a new schedule to use in reconnection attempts. By default, the driver uses an exponential reconnection policy. The driver includes these two policy classes: * `ConstantReconnectionPolicy` * `ExponentialReconnectionPolicy` Retry policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/index.html#retry-policy) -------------------------------------------------------------------------------------------------------------------------- A client may send requests to any node in a cluster whether or not it is a replica of the data being queried. This node is placed into the coordinator role temporarily. Which node is the coordinator is determined by the load balancing policy for the cluster. The coordinator is responsible for routing the request to the appropriate replicas. If a coordinator fails during a request, the driver connects to a different node and retries the request. If the coordinator knows before a request that a replica is down, it can throw an `UnavailableException`, but if the replica fails after the request is made, it throws a `TimeoutException`. Of course, this all depends on the consistency level set for the query before executing it. A retry policy centralizes the handling of query retries, minimizing the need for catching and handling of exceptions in your business code. The retry policy interface consists of four methods: * `#onReadTimeout(info, consistency, received, blockFor, isDataPresent)`: determines what to do when the driver gets a `ReadTimeoutException` response from a Cassandra node. * `#onUnavailable(info, consistency, required, alive)`: determines what to do when the driver gets an `UnavailableException` response from a Cassandra node. * `#onWriteTimeout(info, consistency, received, blockFor, writeType)`: determines what to do when the driver gets a `WriteTimeoutException` response from a Cassandra node * `#onRequestError(info, consistency, err)`: defines whether to retry and at which consistency level on an unexpected error, invoked in the following situations: * On a client timeout, while waiting for the server response , being the error an instance of `OperationTimedOutError`. * On a connection error (socket closed, etc.). * When the contacted host replies with an error, such as `overloaded`, `isBootstrapping`, `serverError`, etc. In this case, the error is instance of `ResponseError` The [operation info](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.policies/module.retry/type.OperationInfo/) , passed as a parameter to the retry policy methods, exposes the `query` and query `options` as properties. A default and base retry policy are included. ### Query idempotence[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies/index.html#query-idempotence) Note that as of version 2.0, the configured `RetryPolicy` is not engaged when a query errors with a `WriteTimeoutException` or request error and the query was not [idempotent](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/#query-idempotence) . --- # DataStax Node.js Driver - mapping [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.mapping/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.mapping/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.mapping/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.mapping/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.mapping/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.mapping/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.mapping/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.mapping/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module mapping[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/index.html#module-mapping) ======================================================================================================================== Module containing classes and fields related to the Mapper. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/index.html#classes) ---------------------------------------------------------------------------------------------------------- * `[Mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/class.Mapper/) ` * `[ModelBatchItem](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/class.ModelBatchItem/) ` * `[ModelMapper](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/class.ModelMapper/) ` * `[Result](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/class.Result/) ` * `[UnderscoreCqlToCamelCaseMappings](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/class.UnderscoreCqlToCamelCaseMappings/) ` * `[DefaultTableMappings](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/class.DefaultTableMappings/) ` Interfaces[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/index.html#interfaces) ---------------------------------------------------------------------------------------------------------------- * `[TableMappings](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/interface.TableMappings/) ` Types[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/index.html#types) ------------------------------------------------------------------------------------------------------ * `[MappingOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/type.MappingOptions/) ` * `[ModelOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/type.ModelOptions/) ` Constants[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/index.html#constants) -------------------------------------------------------------------------------------------------------------- ### q[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/index.html#q) Contains functions that represents operators in a query. Properties: | Name | Type | Description | | --- | --- | --- | | in\_ | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator “IN”. | | gt | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator greater than “>”. | | gte | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator greater than or equals to “>=” . | | lt | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator less than “<” . | | lte | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator less than or equals to “<=” . | | notEq | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL operator not equals to “!=” . | | and | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | When applied to a property, it represents two CQL conditions on the same column separated by the logical AND operator, e.g: “col1 >= x col < y” | | incr | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL increment assignment used for counters, e.g: “col = col + x” | | decr | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL decrement assignment used for counters, e.g: “col = col - x” | | append | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL append assignment used for collections, e.g: “col = col + x” | | prepend | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL prepend assignment used for lists, e.g: “col = x + col” | | remove | `[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions) ` | Represents the CQL remove assignment used for collections, e.g: “col = col - x” | --- # DataStax Node.js Driver - ExecutionProfile [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionProfile/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionProfile/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.ExecutionProfile/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.ExecutionProfile/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.ExecutionProfile/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.ExecutionProfile/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.ExecutionProfile/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.ExecutionProfile/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/class.ExecutionProfile/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/class.ExecutionProfile/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/class.ExecutionProfile/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/class.ExecutionProfile/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/class.ExecutionProfile/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/class.ExecutionProfile/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * class ExecutionProfile[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#class-execution-profile) ================================================================================================================================================= Represents a set configurations to be used in a statement execution to be used for a single `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` instance. An `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) ` instance should not be shared across different `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` instances. Global This class is global Members[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#members) ------------------------------------------------------------------------------------------------------------------ `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` ### consistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#consistency) Consistency level. `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` ### graphOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#graph-options) The graph options for this profile. Properties: | Name | Type | Description | | --- | --- | --- | | language | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph language. | | name | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph name. | | readConsistency | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The consistency to use for graph write queries. | | source | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph traversal source. | | writeConsistency | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The consistency to use for graph write queries. | `LoadBalancingPolicy` ### loadBalancing[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#load-balancing) Load-balancing policy `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` ### name[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#name) Name of the execution profile. `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` ### readTimeout[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#read-timeout) Client read timeout. `RetryPolicy` ### retry[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#retry) Retry policy. `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` ### serialConsistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#serial-consistency) Serial consistency level. Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#constructor) -------------------------------------------------------------------------------------------------------------------------- new ### ExecutionProfile[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/index.html#execution-profile) (`[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` name, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` options\]) Creates a new instance of `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) `. Examples: const { Client, ExecutionProfile } = require('cassandra-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], profiles: [\ new ExecutionProfile('metrics-oltp', {\ consistency: consistency.localQuorum,\ retry: myRetryPolicy\ })\ ] }); client.execute(query, params, { executionProfile: 'metrics-oltp' }, callback); Parameters: | Name | Type | Description | | --- | --- | --- | | name | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | Name of the execution profile.

Use `'default'` to specify that the new instance should be the default `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) ` if no profile is specified in the execution. | | options optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | Profile options, when any of the options is not specified the `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` will the use the ones defined in the default profile. | | options.consistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The consistency level to use for this profile. | | options.loadBalancing optional | `LoadBalancingPolicy` | The load-balancing policy to use for this profile. | | options.readTimeout optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The client per-host request timeout to use for this profile. | | options.retry optional | `RetryPolicy` | The retry policy to use for this profile. | | options.serialConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The serial consistency level to use for this profile. | | options.graphOptions optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | | options.graphOptions.language optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph language to use for graph queries.

Note that this setting should normally be `undefined` or set by a utility method and it’s not expected to be defined manually by the user. | | options.graphOptions.results optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The protocol to use for serializing and deserializing graph results.

Note that this setting should normally be `undefined` or set by a utility method and it’s not expected to be defined manually by the user. | | options.graphOptions.name optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph name to use for graph queries. | | options.graphOptions.readConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The consistency level to use for graph read queries. | | options.graphOptions.source optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The graph traversal source name to use for graph queries. | | options.graphOptions.writeConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The consistency level to use for graph write queries. | | options.loadBalancing optional | `LoadBalancingPolicy` | The load-balancing policy to use for this profile. | | options.readTimeout optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The client per-host request timeout to use for this profile. | | options.retry optional | `RetryPolicy` | The retry policy to use for this profile. | | options.serialConsistency optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The serial consistency level to use for this profile. | --- # DataStax Node.js Driver - Execution Profiles [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/execution-profiles/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/execution-profiles/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/execution-profiles/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/execution-profiles/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/execution-profiles/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/execution-profiles/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/execution-profiles/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/execution-profiles/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/execution-profiles/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/execution-profiles/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/execution-profiles/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/execution-profiles/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/execution-profiles/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Execution Profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/index.html#execution-profiles) ========================================================================================================================================= Execution profiles provide a mechanism to group together a set of configuration options and reuse them across different query executions. This feature is specially useful when dealing with different workloads like DSE Graph, Cql OLTP workloads, DSE search, … These options include: * Load balancing policy * Retry policy * Consistency levels * Per-host request timeout * Graph Options * Graph name * Graph traversal source * Graph read consistency * Graph write consistency Using Execution Profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/index.html#using-execution-profiles) ----------------------------------------------------------------------------------------------------------------------------------------------------- ### Initializing cluster with profiles[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/index.html#initializing-cluster-with-profiles) Execution profiles should be created when creating the `Client` instance with a name that identifies it and the settings that apply to the profile. const aggregationProfile = new ExecutionProfile('aggregation', { consistency: consistency.localQuorum, loadBalancing: new DCAwareRoundRobinPolicy('us-west'), retry: myRetryPolicy, readTimeout: 30000, serialConsistency: consistency.localSerial }); const client = new Client({ contactPoints: ['host1'], localDataCenter, profiles: [ aggregationProfile ] }); Note that while the above options are all the supported settings on the execution profiles, you can specify only the ones that are required for the executions, using the `'default'` profile to fill the rest of the options. #### Default execution profile[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/index.html#default-execution-profile) You can define a default profile, using the name `'default'`: const client = new Client({ contactPoints: ['host1'], localDataCenter, profiles: [ \ new ExecutionProfile('default', {\ consistency: consistency.one,\ readTimeout: 10000\ }),\ new ExecutionProfile('graph-oltp', {\ consistency: consistency.localQuorum,\ graphOptions: { name: 'myGraph' }\ })\ ] }); The default profile will be used to fill the unspecified options in the rest of the profiles. In the above example, the read timeout for the profile named `'graph-oltp'` will be the one defined in the default profile (10,000 ms). For the settings that are not specified in the default profile, the driver will use the default `Client` options. ### Using an execution profile by name[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/index.html#using-an-execution-profile-by-name) Use the name to specify which profile you want to use for the execution. client.execute(query, params, { executionProfile: 'aggregation' }); ### Using an execution profile by instance[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/index.html#using-an-execution-profile-by-instance) You can also use the `ExecutionProfile` instance. client.execute(query, params, { executionProfile: aggregationProfile }); ### Using default execution profile[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/index.html#using-default-execution-profile) When the execution profile is not provided in the options, the default execution profile is used. client.execute(query, params, null); --- # DataStax Node.js Driver - Speculative query execution [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/speculative-executions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/speculative-executions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/speculative-executions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/speculative-executions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/speculative-executions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/speculative-executions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/speculative-executions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/speculative-executions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/speculative-executions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Speculative query execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/index.html#speculative-query-execution) =============================================================================================================================================================== Sometimes a server node might be experiencing difficulties (for example, long GC pause) and take longer than usual to reply. Queries sent to that node experience higher latencies than expected. One thing we can do to improve that is preemptively start a second execution of the query against another node, before the first node has replied or errored out. If that second node replies faster, we can send the response back to the client (we also cancel the first query): ![Text Diagram]() Or the first node could reply just after the second execution was started. In this case, we cancel the second execution. In other words, whichever node replies faster wins and completes the client query: ![Text Diagram]() Note that “cancelling” in this context simply means marking the operation to discard the response when it later arrives. Speculative executions are disabled by default. The following sections cover the practical details and how to enable them. Query idempotence[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/index.html#query-idempotence) ------------------------------------------------------------------------------------------------------------------------------------------- One important aspect to consider is whether queries are idempotent, (that is, whether they can be applied multiple times without changing the result beyond the initial application). If a query is not idempotent, the driver never schedules speculative executions for it, because there is no way to guarantee that only one node will apply the mutation. Examples of queries that are not idempotent are: * counter operations * prepending or appending to a list column * using non-idempotent CQL functions, like `now()` or `uuid()` In the driver, this is determined by [`isIdempotent` flag in the `QueryOptions`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) . Because the driver does not parse query strings, in most cases it has no information about what the query actually does. Therefore, for all other types of statements, it defaults to `false`. You must set it manually with one of the mechanisms described below. You can override the value for each execution: const query = 'SELECT * FROM users WHERE key = ?'; client.execute(query, [ 'usr1' ], { prepare: true, isIdempotent: true }); Additionally, if you know for a fact that your application does not use any of the non-idempotent CQL queries listed above, you can change the default cluster-wide: // Make all statements idempotent by default: const client = new Client({ contactPoints, localDataCenter, queryOptions: { isIdempotent: true } }); Enabling speculative execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/index.html#enabling-speculative-execution) --------------------------------------------------------------------------------------------------------------------------------------------------------------------- Speculative executions are controlled by an instance of `SpeculativeExecutionPolicy` provided when initializing the `Client`. This policy defines the threshold after which a new speculative execution is triggered. The driver provides a `ConstantSpeculativeExecutionPolicy` that schedules a given number of speculative executions, separated by a fixed delay, the policy is exported under the `.policies.speculativeExecution` module. This simple policy uses a constant threshold: const { Client, policies } = require('cassandra-driver'); const ConstantSpeculativeExecutionPolicy = policies.speculativeExecution.ConstantSpeculativeExecutionPolicy; const client = new Client({ contactPoints, policies: { speculativeExecution: new ConstantSpeculativeExecutionPolicy( 200, // delay before a new execution is launched 2) // maximum amount of additional executions } }); Given the configuration above, an idempotent query would be handled this way: * start the initial execution at t0 * if no response has been received at t0 + 200 milliseconds, start a speculative execution on another node * if no response has been received at t0 + 400 milliseconds, start another speculative execution on a third node As with the rest of policies in the driver, you can provide your own implementation by extending the `SpeculativeExecutionPolicy` prototype. How speculative executions affect retries[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/index.html#how-speculative-executions-affect-retries) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Regardless of speculative executions, the driver has a retry mechanism: * on an internal error, it will try the next host * if the consistency level cannot be reached (for example, unavailable error or read or write timeout), it delegates the decision to the `RetryPolicy`, which might trigger a retry on the same host Turning speculative executions on does not change this behavior. Each parallel execution trigger retries independently: ![Text Diagram]() The only impact is that all executions of the same query always share the same query plan, so each host is used by at most one execution. Tuning and practical details[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/index.html#tuning-and-practical-details) ----------------------------------------------------------------------------------------------------------------------------------------------------------------- The goal of speculative executions is to improve overall latency (the time between `execute(query)` and `complete` in the diagrams above) at high percentiles. On the flipside, they cause the driver to send more individual requests, so throughput does not necessarily improve. One side-effect of speculative executions is that many requests are cancelled, which can lead to a phenomenon called stream id exhaustion: each TCP connection can handle multiple simultaneous requests, identified by a unique number called stream id. When a request gets cancelled, we can’t reuse its stream id immediately because we might still receive a response from the server later. If this happens often, the number of available stream ids diminishes over time, and when it goes below a given threshold we close the connection and create a new one. If requests are often cancelled, so will see connections being recycled at a high rate. This problem is more likely to happen with old server versions (Apache Cassandra version 2.0 or below and DSE 4.6 or below) which only support version 1 and 2 of the native protocol where each TCP connection only has 128 available stream ids. With modern server versions, there are 32K stream ids per connection, so higher cancellation rates can be sustained. Another issue that might arise is that you get unintuitive results because of request ordering. Suppose you run the following query with speculative executions enabled: insert into my_table (k, v) values (1, 1); The first execution is a bit too slow, so a second execution gets triggered. Finally, the first execution completes, so the client code gets back an acknowledgement, and the second execution is cancelled. However, cancelling only means that the driver stops waiting for the server’s response, the request could still be on the wire; let us assume that this is the case. Now you run the following query, which completes successfully: delete from my_table where k = 1; But now the second execution of the first query finally reaches its target node, which applies the mutation. The row that you’ve just deleted is back! **Using [query timestamps](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps) **, which are enabled by default, prevents this issue to appear as each request will have a client-level timestamp which will define the order to apply the mutations. --- # DataStax Node.js Driver - Geospatial types [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/geotypes/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/geotypes/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/geotypes/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/geotypes/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/geotypes/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Geospatial types[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/geotypes/index.html#geospatial-types) --------------------------------------------------------------------------------------------------------------------------- [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) comes with a set of additional CQL types to represent geospatial data: * `PointType` * `LineStringType` * `PolygonType`. cqlsh> CREATE TABLE points_of_interest(name text PRIMARY KEY, coords 'PointType'); cqlsh> INSERT INTO points_of_interest (name, coords) VALUES ('Eiffel Tower', 'POINT(48.8582 2.2945)'); The driver includes encoders and representations of these types in the `geometry` module that can be used directly as parameters in queries. All Javascript geospatial types implement `toString()`, that returns the string representation in [Well-known text](https://en.wikipedia.org/wiki/Well-known_text) format, and `toJSON()`, that returns the JSON representation in [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) format. Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/geotypes/index.html#usage) ----------------------------------------------------------------------------------------------------- const cassandra = require('cassandra-driver'); const Point = cassandra.geometry.Point; const insertQuery = 'INSERT INTO points_of_interest (name, coords) VALUES (?, ?)'; const selectQuery = 'SELECT coords FROM points_of_interest WHERE name = ?'; await client.execute(insertQuery, [ 'Eiffel Tower', new Point(48.8582, 2.2945) ]); const result = await client.execute(selectQuery, [ 'Eiffel Tower' ]); const row = result.first(); const point = row['coords']; console.log(point instanceof Point); // true console.log('x: %d, y: %d', point.x, point.y); // x: 48.8582, y: 2.2945 console.log(point.toString()); // 'POINT (48.8582 2.2945)' --- # DataStax Node.js Driver - datastax [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.datastax/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.datastax/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.datastax/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.datastax/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.datastax/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module datastax[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.datastax/index.html#module-datastax) =========================================================================================================================== DataStax module. Contains modules and classes to represent functionality that is specific to DataStax products. Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.datastax/index.html#modules) ----------------------------------------------------------------------------------------------------------- * `[graph](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.datastax/module.graph/) ` * `[search](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.datastax/module.search/) ` --- # DataStax Node.js Driver - Graph support [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/graph-support/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Graph support[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/index.html#graph-support) ========================================================================================================================== `Client` includes the `executeGraph()` method to execute graph queries: const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'dc1', graphOptions: { name: 'demo' } }); // executeGraph() method returns a Promise client.executeGraph('g.V()') .then(function (result) { const vertex = result.first(); console.log(vertex.label); }); Alternatively, you can use the callback-based execution: client.executeGraph('g.V()', function (err, result) { assert.ifError(err); const vertex = result.first(); // ... }); Graph Options[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/index.html#graph-options) -------------------------------------------------------------------------------------------------------------------------- You can set default graph options when initializing `Client` which will be used for all graph statements. For example, to avoid providing a `graphName` option in each `executeGraph()` call: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'dc1', graphOptions: { name: 'demo' } }); These options may be overridden by specifying the [execution profile](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles) when calling `executeGraph()`: // Use a different graph name than the one provided when creating the client instance const result = await client.executeGraph(query, params, { executionProfile: 'graph-oltp' }); const vertex = result.first(); console.log(vertex.label); You can check out more info on [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles) . Handling Results[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/index.html#handling-results) -------------------------------------------------------------------------------------------------------------------------------- Graph queries return a `GraphResultSet`, which is an [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable) of items. The format of the data returned is dependent on the data requested. Retrieving property values: const result = await client.executeGraph('g.V().hasLabel("person").values("name")'); for (const name of result) { console.log(name); } Retrieving vertices: const result = await client.executeGraph('g.V().hasLabel("person")'); for (const vertex of result) { console.log(vertex.label); } Retrieving edges: const result = await client.executeGraph('g.E()'); for (const edge of result) { console.log(edge.label); } ### Parameters[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/index.html#parameters) Graph traversal execution supports named parameters. Parameters must be passed in as an object: const traversal = 'g.addV(vertexLabel).property("name", username)'; await client.executeGraph(traversal, { vertexLabel: 'person', username: 'marko' }); ### Graph types[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/index.html#graph-types) The DataStax Node.js driver supports a wide variety of TinkerPop types and [DSE types](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/) . For graph types that don’t have a native JavaScript representation, the driver provides the [`types` module](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/) . For example: const { types } = require('cassandra-driver'); const { Uuid, InetAddress } = types; const traversal = 'g.addV("sample").property("uid", uid).property("ip_address", address)'; await client.execute(traversal, { uid: Uuid.random(), address: InetAddress.fromString('10.0.0.100') }); The same types are also supported for traversal execution results: const rs = await client.execute('g.V().hasLabel("sample").values("ip_address")'); for (const ip of rs) { console.log(ip instanceof InetAddress); // true } #### User-defined types[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/index.html#user-defined-types) User-defined types (UDTs) are supported in the Node.js driver using JavaScript objects. const rs = await client.execute('g.V().hasLabel("sample").values("user_address")'); for (const address of rs) { console.log(`User address is ${address.street}, ${address.city} ${address.state}`); } In order to use a UDT as a parameter, you must wrap the object instance using `asUdt()` function to provide additional information to properly represent the UDT on the server. const { datastax } = require('cassandra-driver'); const { asUdt } = datastax.graph; // Get the UDT metadata const udtInfo = await client.metadata.getUdt(graphName, 'address'); // Build the UDT const address = asUdt({ street: '123 Priam St.', city: 'My City', state: 'MY' }, udtInfo); const traversal = 'g.addV("sample").property("uid", uid).property("user_address", address)'; // Use the UDT as parameter await client.execute(traversal, { uid: Uuid.random(), address }); --- # DataStax Node.js Driver - Parameterized queries [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/parameterized-queries/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/parameterized-queries/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/parameterized-queries/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/parameterized-queries/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/parameterized-queries/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/parameterized-queries/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/parameterized-queries/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/parameterized-queries/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/parameterized-queries/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/parameterized-queries/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/parameterized-queries/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/parameterized-queries/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/parameterized-queries/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/parameterized-queries/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/parameterized-queries/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/parameterized-queries/) * Parameterized queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/parameterized-queries/index.html#parameterized-queries) ================================================================================================================================================== You can bind the values of parameters in a prepared statement either by position or by using named markers. Positional parameterized query[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/parameterized-queries/index.html#positional-parameterized-query) -------------------------------------------------------------------------------------------------------------------------------------------------------------------- When using positional parameters, the query parameters must be provided as an Array. const query = 'INSERT INTO artists (id, name) VALUES (?, ?)'; // Parameters by marker position const params = ['krichards', 'Keith Richards']; client.execute(query, params, { prepare: true }); Named parameterized query[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/parameterized-queries/index.html#named-parameterized-query) ---------------------------------------------------------------------------------------------------------------------------------------------------------- You declare the named markers in your queries and use a JavaScript object properties to define the parameters, with the `Object` property names matching the parameters names. const query = 'INSERT INTO artists (id, name) VALUES (:id, :name)'; // Parameters by marker name const params = { id: 'krichards', name: 'Keith Richards' }; client.execute(query, params, { prepare: true }); Defining named markers in your queries is supported in Cassandra 2.0 or greater for prepared statements and Cassandra 2.1 or greater for non-prepared statements. --- # DataStax Node.js Driver - Cluster and schema metadata [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/metadata/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/metadata/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/metadata/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/metadata/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/metadata/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/metadata/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/metadata/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/metadata/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/metadata/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/metadata/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/metadata/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/metadata/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/metadata/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/metadata/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/metadata/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/metadata/) * Cluster and schema metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/metadata/index.html#cluster-and-schema-metadata) ================================================================================================================================================= You can retrieve the cluster topology and the schema metadata information using the Node.js driver. After establishing the first connection, the driver retrieves the cluster topology details and exposes these through properties of the client object. This information is kept up to date using Cassandra event notifications. The following example outputs hosts information about your cluster: client.hosts.forEach(function (host) { console.log(host.address, host.datacenter, host.rack); }); Additionally, the keyspaces information is already loaded into the `Metadata` object, once the client is connected: console.log(Object.keys(client.metadata.keyspaces)); To retrieve the definition of a table, use the `Metadata#getTable()` method: client.metadata.getTable('ks1', 'table1') .then(function (tableInfo) { console.log('Table %s', table.name); table.columns.forEach(function (column) { console.log('Column %s with type %j', column.name, column.type); }); }); When retrieving the same table definition concurrently, the driver queries once and invokes all callbacks with the retrieved information. Schema agreement[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/metadata/index.html#schema-agreement) --------------------------------------------------------------------------------------------------------------------------- Schema changes need to be propagated to all nodes in the cluster. Once they have settled on a common version, we say that they are in agreement. the driver waits for schema agreement after executing a schema-altering query. This is to ensure that subsequent requests (which might get routed to different nodes) see an up-to-date version of the schema. ![Text Diagram]() The schema agreement wait is performed serially, so the `execute()` call will only return after it has completed. The check is implemented by repeatedly querying system tables for the schema version reported by each node, until they all converge to the same value. If that doesn’t happen within a given timeout, the driver will give up waiting. The default timeout is `10` seconds, it can be customized when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, protocolOptions: { maxSchemaAgreementWaitSeconds: 20 } }); After executing a statement, you can check whether schema agreement was successful or timed out: client.execute('CREATE TABLE table1 (id int PRIMARY KEY)') .then(rs => { console.log(`Is schema in agreement? ${rs.info.isSchemaInAgreement}`); }); Additionally, you can perform an on-demand check at any time: client.metadata.checkSchemaAgreement() .then(agreement => { console.log(`Is schema in agreement? ${agreement}`); }); Note that the on-demand check using `checkSchemaAgreement()` does not retry, it only queries system tables once. --- # DataStax Node.js Driver - User-defined functions and aggregates [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/udfs/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/udfs/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/udfs/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/udfs/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/udfs/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/udfs/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/udfs/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/udfs/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/udfs/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/udfs/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/udfs/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/udfs/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/udfs/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/udfs/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/udfs/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/udfs/) * User-defined functions and aggregates[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/udfs/index.html#user-defined-functions-and-aggregates) ================================================================================================================================================================= Cassandra 2.2 introduced [user-defined functions](https://issues.apache.org/jira/browse/CASSANDRA-7395) (UDF) and aggregates support. You access UDF and aggregate values in your queries like regular columns: const query = 'SELECT avg(salary) as salary FROM employees'; client.execute(query) .then(function (result) { const row = result.first(); console.log('Average salary %d', row.salary); }); The driver also exposes [UDFs and aggregates metadata information](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.metadata/) , for example let’s see how to retrieve the metadata information of a UDF named iif, that takes a boolean and int parameter. client.metadata.getFunction('ks1', 'iif', ['boolean', 'int']) .then(function (err, udf) { console.log('Function metadata %j', udf); }); --- # DataStax Node.js Driver - Upgrading from the DSE Driver [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/upgrade-from-dse-driver/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/upgrade-from-dse-driver/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/upgrade-from-dse-driver/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/upgrade-from-dse-driver/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/upgrade-guide/upgrade-from-dse-driver/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Upgrading from the DSE Driver[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/upgrade-from-dse-driver/index.html#upgrading-from-the-dse-driver) ========================================================================================================================================================================= This guide is intended for users of the DSE driver that plan to migrate to the `cassandra-driver`. The `cassandra-driver` now supports all DataStax products and features, such as Unified Authentication, Kerberos, geo types and graph traversal executions, allowing you to use a single driver for Apache Cassandra, DSE or other DataStax products. Upgrading from `dse-driver` to `cassandra-driver` can be as simple as changing the import statement to point to the dse package: const { Client } = require('dse-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); Becomes: const { Client } = require('cassandra-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); Submodules[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/upgrade-from-dse-driver/index.html#submodules) ----------------------------------------------------------------------------------------------------------------------------------- Most of the child modules are in the same path. const { auth, types, geometry, policies, mapping } = require('dse-driver'); Becomes: const { auth, types, geometry, policies, mapping } = require('cassandra-driver'); The only notable module path distinctions are Graph and Search types that are under `datastax` module. const { graph, search } = require('dse-driver'); Becomes: const { datastax } = require('cassandra-driver'); const { graph, search } = datastax; Load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/upgrade-from-dse-driver/index.html#load-balancing-policy) --------------------------------------------------------------------------------------------------------------------------------------------------------- The default load balancing policy on the `dse-driver` was `DseLoadBalancingPolicy`. In the `cassandra-driver`, a policy with the same behaviour is called `DefaultLoadBalancingPolicy`, which is the default. --- # DataStax Node.js Driver - geometry [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.geometry/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.geometry/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module geometry[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/index.html#module-geometry) =========================================================================================================================== Geometry module. Contains the classes to represent the set of additional CQL types for geospatial data that come with DSE 5.0. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/index.html#classes) ----------------------------------------------------------------------------------------------------------- * `[LineString](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/class.LineString/) ` * `[Point](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/class.Point/) ` * `[Polygon](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/class.Polygon/) ` --- # DataStax Node.js Driver - concurrent [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.concurrent/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.concurrent/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.concurrent/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.concurrent/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.concurrent/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.concurrent/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.concurrent/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.concurrent/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module concurrent[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.concurrent/index.html#module-concurrent) ================================================================================================================================= Utilities for concurrent query execution with the DataStax Node.js Driver. Functions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.concurrent/index.html#functions) ----------------------------------------------------------------------------------------------------------------- ### concurrent.executeConcurrent[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.concurrent/index.html#execute-concurrent) (`[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` client, `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<{query, params}\> query, `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\>, `Stream` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` parameters, \[`[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` options\]) Executes multiple queries concurrently at the defined concurrency level. Static This function is static Examples: Using a fixed query and an Array of Arrays as parameters const query = 'INSERT INTO table1 (id, value) VALUES (?, ?)'; const parameters = [[1, 'a'], [2, 'b'], [3, 'c'], ]; // ... const result = await executeConcurrent(client, query, parameters); Using a fixed query and a readable stream const stream = csvStream.pipe(transformLineToArrayStream); const result = await executeConcurrent(client, query, stream); Using a different queries const queryAndParameters = [\ { query: 'INSERT INTO videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ { query: 'INSERT INTO user_videos (user_id, id, name) VALUES (?, ?, ?)',\ params: [ userId, id, name ] },\ { query: 'INSERT INTO latest_videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ ]; const result = await executeConcurrent(client, queryAndParameters); Parameters: | Name | Type | Description | | --- | --- | --- | | client | `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` | The `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` instance. | | query | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<{query, params}\> | The query to execute per each parameter item. | | parameters | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\>, `Stream` or `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | An `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or a readable `Stream` composed of `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` items representing each individual set of parameters. Per each item in the `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `Stream`, an execution is going to be made. | | options optional | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | The execution options. | | options.executionProfile optional | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | The execution profile to be used. | | options.concurrencyLevel optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The concurrency level to determine the maximum amount of in-flight operations at any given time

(default: `100`) | | options.raiseOnFirstError optional | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether execution should stop after the first failed execution and the corresponding exception will be raised.

(default: `true`) | | options.collectResults optional | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | Determines whether each individual `[ResultSet](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/class.ResultSet/) ` instance should be collected in the grouped result.

(default: `false`) | | options.maxErrors optional | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | The maximum amount of errors to be collected before ignoring the rest of the error results.

(default: `100`) | Returns: | Type | Description | | --- | --- | | `Promise`<`ResultSetGroup`\> | A `Promise` of `ResultSetGroup` that is resolved when all the executions completed and it’s rejected when `raiseOnFirstError` is `true` and there is one or more failures. | --- # DataStax Node.js Driver - TransitionalModePlainTextAuthenticator [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.TransitionalModePlainTextAuthenticator/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.TransitionalModePlainTextAuthenticator/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.TransitionalModePlainTextAuthenticator/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * class TransitionalModePlainTextAuthenticator[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.TransitionalModePlainTextAuthenticator/index.html#class-transitional-mode-plain-text-authenticator) ====================================================================================================================================================================================================================== Authenticator that accounts for DSE authentication configured with transitional mode: normal. In this situation, the client is allowed to connect without authentication, but DSE would still send an AUTHENTICATE response. This Authenticator handles this situation by sending back a dummy credential. Global This class is global Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.TransitionalModePlainTextAuthenticator/index.html#constructor) ------------------------------------------------------------------------------------------------------------------------------------------------ new ### TransitionalModePlainTextAuthenticator[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.TransitionalModePlainTextAuthenticator/index.html#transitional-mode-plain-text-authenticator) () --- # DataStax Node.js Driver - tracker [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.tracker/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.tracker/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.tracker/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.tracker/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.tracker/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.tracker/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.tracker/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.tracker/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.tracker/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module tracker[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.tracker/index.html#module-tracker) ======================================================================================================================== Tracker module. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.tracker/index.html#classes) ---------------------------------------------------------------------------------------------------------- * `[RequestLogger](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.tracker/class.RequestLogger/) ` Interfaces[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.tracker/index.html#interfaces) ---------------------------------------------------------------------------------------------------------------- * `[RequestTracker](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.tracker/interface.RequestTracker/) ` --- # DataStax Node.js Driver - metrics [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.metrics/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.metrics/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.metrics/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.metrics/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/module.metrics/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/module.metrics/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/module.metrics/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/module.metrics/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module metrics[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/index.html#module-metrics) ======================================================================================================================== The `metrics` module contains interfaces and implementations used by the driver to expose measurements of its internal behavior and of the server as seen from the driver side. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/index.html#classes) ---------------------------------------------------------------------------------------------------------- * `[DefaultMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/class.DefaultMetrics/) ` Interfaces[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/index.html#interfaces) ---------------------------------------------------------------------------------------------------------------- * `[ClientMetrics](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/interface.ClientMetrics/) ` --- # DataStax Node.js Driver - Query timestamps [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/query-timestamps/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/query-timestamps/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/query-timestamps/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/query-timestamps/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/query-timestamps/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/query-timestamps/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/query-timestamps/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/query-timestamps/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/query-timestamps/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/query-timestamps/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/query-timestamps/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/query-timestamps/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/query-timestamps/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Query timestamps[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/index.html#query-timestamps) =================================================================================================================================== In Cassandra, each mutation has a microsecond-precision timestamp, which is used to order operations relative to each other. The timestamp can be provided by the client or assigned server-side based on the time the server processes the request. Letting the server assign the timestamp can be a problem when the order of the writes matter: with unlucky timing (different coordinators, network latency, etc.), two successive requests from the same client might be processed in a different order server-side, and end up with out-of-order timestamps. Client-side generation[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/index.html#client-side-generation) ----------------------------------------------------------------------------------------------------------------------------------------------- ### Using a timestamp generator[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/index.html#using-a-timestamp-generator) The operation timestamp can be sent as part of the request. The driver uses [`MonotonicTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) by default to generate the request timestamps. You can provide a different generator when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, policies: { timestampGeneration: new MyCustomTimestampGenerator() } }); To implement a custom timestamp generator, you must implement `TimestampGenerator` base class. In addition, you can also set the default timestamp on a per-execution basis in the query options: session.execute(query, params, { timestamp: timestamp }); #### Accuracy[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/index.html#accuracy) As defined by ECMAScript, the `Date` object has millisecond resolution. The [`MononoticTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) uses a incremental counter to generate the sub-millisecond part of the timestamp until the next clock tick. #### Monotonicity[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/index.html#monotonicity) The [`MononoticTimestampGenerator`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.policies/module.timestampGeneration/class.MonotonicTimestampGenerator/) implementation also guarantees that the returned timestamps will always be monotonically increasing, even if multiple updates happen under the same millisecond. Note that to guarantee such monotonicity, if more than one thousand timestamps are generated within the same millisecond, or in the event of a system clock skew, the implementation might return timestamps that drift out into the future. When this happens, the built-in generator logs a periodic warning message. See their non-default constructors for ways to control the warning interval. ### Provide the timestamp in the query[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps/index.html#provide-the-timestamp-in-the-query) Alternatively, if you are using an old server version, you can explicitly provide the timestamp in your CQL query (not recommended): client.execute('INSERT INTO my_table(c1, c2) VALUES (1, 1) USING TIMESTAMP 1482156745633040'); --- # DataStax Node.js Driver - Promise and callback-based API [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/promise-callback/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/promise-callback/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/promise-callback/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/promise-callback/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/promise-callback/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/promise-callback/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/promise-callback/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/promise-callback/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/promise-callback/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/promise-callback/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/promise-callback/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/promise-callback/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/promise-callback/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/promise-callback/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Promise and callback-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/promise-callback/index.html#promise-and-callback-based-api) =============================================================================================================================================================== The driver supports both [promises](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) and callbacks for the asynchronous methods exposed in the `Client` and `Metadata` prototypes, you can choose the approach that suits your needs. Promise-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/promise-callback/index.html#promise-based-api) ------------------------------------------------------------------------------------------------------------------------------------- client.execute('SELECT name, email FROM users') .then(result => console.log('User with email %s', result.rows[0].email)); When a `callback` is not provided as the last argument, the driver will return a `Promise`, without the need to promisify the driver module. Returned promises are instances of [`Promise` global object](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) and are created using the default constructor: `new Promise(executor)`. In case you want the driver to use a third party `Promise` module (ie: [bluebird](http://bluebirdjs.com/) ) to create the `Promise` instances, you can optionally provide your own factory method when creating the `Client` instance, for example: const BbPromise = require('bluebird'); const client = new Client({ contactPoints, localDataCenter, promiseFactory: BbPromise.fromCallback }); Callback-based API[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/promise-callback/index.html#callback-based-api) --------------------------------------------------------------------------------------------------------------------------------------- All asynchronous methods of the driver supports an optional `callback` as the last argument. client.execute('SELECT name, email FROM users', function(err, result) { assert.ifError(err); console.log('User with email %s', result.rows[0].email); }); --- # DataStax Node.js Driver - Concurrent Execution API [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/concurrent-api/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/concurrent-api/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/concurrent-api/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/concurrent-api/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/concurrent-api/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/concurrent-api/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/concurrent-api/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Concurrent Execution API[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/index.html#concurrent-execution-api) ================================================================================================================================================= The DataStax Node.js driver provides a set of [utilities for concurrent query execution](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.concurrent/) , to facilitate executing multiple queries in parallel while controlling the concurrency level. The concurrent execution API can useful when, for example, you want to insert a large group of rows from an `Array` or a `Stream` and evaluate failures, if any, at the end. Usage samples[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/index.html#usage-samples) --------------------------------------------------------------------------------------------------------------------------- ### Using a fixed query and an Array of arrays as parameters[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/index.html#using-a-fixed-query-and-an-array-of-arrays-as-parameters) When an `Array` of arrays is provided, one query per each item in the `Array` will be executed, using each item as parameters. const query = 'INSERT INTO table1 (id, value) VALUES (?, ?)'; const parameters = [[1, 'a'], [2, 'b'], [3, 'c'], ]; // ... const result = await executeConcurrent(client, query, parameters); You can visit the [code examples in the driver repository](https://github.com/datastax/nodejs-driver/tree/master/examples) to check out a working example. ### Using a fixed query and a readable stream[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/index.html#using-a-fixed-query-and-a-readable-stream) When a `Stream` instance is provided the driver will read from the input stream and execute one query per item emitted. The driver will throttle reads of the input stream based on the concurrency level configured and the amount of current in-flight requests. The `Stream` instance should be a readable, in object mode, and emit `Array` instances. Per each item emitted, one query will be executed. const stream = csvStream.pipe(transformLineToArrayStream); const result = await executeConcurrent(client, query, stream); ### Using a different queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/index.html#using-a-different-queries) const queryAndParameters = [\ { query: 'INSERT INTO videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ { query: 'INSERT INTO user_videos (user_id, id, name) VALUES (?, ?, ?)',\ params: [ userId, id, name ] },\ { query: 'INSERT INTO latest_videos (id, name, user_id) VALUES (?, ?, ?)',\ params: [ id, name, userId ] },\ ]; const result = await executeConcurrent(client, queryAndParameters); ### Execute all queries and deal with execution errors at the end[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/index.html#execute-all-queries-and-deal-with-execution-errors-at-the-end) When setting `raiseOnFirstError` to `false`, the driver will continue to execute the queries even when one or more errors are encountered. The returned `Promise` will be resolved and you can inspect the property `errors` to obtain each individual error information. const result = await executeConcurrent(client, query, parameters, { raiseOnFirstError: false }); for (let err of result.errors) { // ... } ### Defining concurrency level[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/index.html#defining-concurrency-level) Use the `concurrencyLevel` option property to set the maximum amount of requests that can be executed simultaneously. It defaults to `100`. const result = await executeConcurrent(client, query, parameters, { concurrencyLevel: 200 }); Note that increasing the amount of simultaneous requests will result in further queueing at the driver level and the server nodes level. You should find the optimal to get high throughput and low latency, based on your cluster size and hardware specifications. Using a higher concurrency level setting than optimal might result in query timeouts. ### Collecting all the ResultSet instances of each individual execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api/index.html#collecting-all-the-result-set-instances-of-each-individual-execution) In the case you want the driver to collect each individual `ResultSet` instance, you can use the `collectResults` flag. const result = await executeConcurrent(client, query, parameters, { collectResults: true }); for (let rs of result.resultItems) { // ... } --- # DataStax Node.js Driver - Home [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * DataStax Node.js Driver for Apache Cassandra®[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#data-stax-node-js-driver-for-apache-cassandra) =================================================================================================================================================================== A modern, [feature-rich](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#features) and highly tunable Node.js client library for Apache Cassandra and [DSE](https://www.datastax.com/products/datastax-enterprise) using exclusively Cassandra’s binary protocol and Cassandra Query Language. Installation[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#installation) ------------------------------------------------------------------------------------------------- $ npm install cassandra-driver [![Build Status](https://api.travis-ci.com/datastax/nodejs-driver.svg?branch=master)](https://travis-ci.org/datastax/nodejs-driver) [![Build status](https://ci.appveyor.com/api/projects/status/m21t2tfdpmkjex1l/branch/master?svg=true)](https://ci.appveyor.com/project/datastax/nodejs-driver/branch/master) Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#features) ----------------------------------------------------------------------------------------- * Simple, Prepared, and [Batch](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/batch/) statements * Asynchronous IO, parallel execution, request pipelining * [Connection pooling](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/connection-pooling/) * Auto node discovery * Automatic reconnection * Configurable [load balancing](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#load-balancing-policy) and [retry policies](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#retry-policy) * Works with any cluster size * Built-in [object mapper](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/) * Both [promise and callback-based API](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/promise-callback/) * [Row streaming and pipes](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#row-streaming-and-pipes) * Built-in TypeScript support Documentation[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#documentation) --------------------------------------------------------------------------------------------------- * [Documentation index](https://docs.datastax.com/en/developer/nodejs-driver/latest/) * [CQL types to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/) * [API docs](https://docs.datastax.com/en/developer/nodejs-driver/latest/api/) * [FAQ](https://docs.datastax.com/en/developer/nodejs-driver/latest/faq/) Getting Help[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#getting-help) ------------------------------------------------------------------------------------------------- You can use the [project mailing list](https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user) or create a ticket on the [Jira issue tracker](https://datastax-oss.atlassian.net/projects/NODEJS/issues) . Basic usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#basic-usage) ----------------------------------------------------------------------------------------------- const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['h1', 'h2'], localDataCenter: 'datacenter1', keyspace: 'ks1' }); const query = 'SELECT name, email FROM users WHERE key = ?'; client.execute(query, [ 'someone' ]) .then(result => console.log('User with email %s', result.rows[0].email)); The driver supports both [promises and callbacks](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/promise-callback/) for the asynchronous methods, you can choose the approach that suits your needs. Note that in order to have concise code examples in this documentation, we will use the promise-based API of the driver along with the `await` keyword. If you are using [DataStax Astra](https://www.datastax.com/products/datastax-astra) you can configure your client by setting the secure bundle and the user credentials: const client = new cassandra.Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); ### Prepare your queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#prepare-your-queries) Using prepared statements provides multiple benefits. Prepared statements are parsed and prepared on the Cassandra nodes and are ready for future execution. Also, when preparing, the driver retrieves information about the parameter types which **allows an accurate mapping between a JavaScript type and a Cassandra type**. The driver will prepare the query once on each host and execute the statement with the bound parameters. // Use query markers (?) and parameters const query = 'UPDATE users SET birth = ? WHERE key=?'; const params = [ new Date(1942, 10, 1), 'jimi-hendrix' ]; // Set the prepare flag in the query options await client.execute(query, params, { prepare: true }); console.log('Row updated on the cluster'); ### Row streaming and pipes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#row-streaming-and-pipes) When using `#eachRow()` and `#stream()` methods, the driver parses each row as soon as it is received, yielding rows without buffering them. // Reducing a large result client.eachRow( 'SELECT time, val FROM temperature WHERE station_id=', ['abc'], (n, row) => { // The callback will be invoked per each row as soon as they are received minTemperature = Math.min(row.val, minTemperature); }, err => { // This function will be invoked when all rows where consumed or an error was encountered } ); The `#stream()` method works in the same way but instead of callback it returns a [Readable Streams2](https://nodejs.org/api/stream.html#stream_class_stream_readable) object in `objectMode` that emits instances of `Row`. It can be **piped** downstream and provides automatic pause/resume logic (it buffers when not read). client.stream('SELECT time, val FROM temperature WHERE station_id=', [ 'abc' ]) .on('readable', function () { // 'readable' is emitted as soon a row is received and parsed let row; while (row = this.read()) { console.log('time %s and value %s', row.time, row.val); } }) .on('end', function () { // Stream ended, there aren't any more rows }) .on('error', function (err) { // Something went wrong: err is a response error from Cassandra }); ### User defined types[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#user-defined-types) [User defined types (UDT)](https://cassandra.apache.org/doc/latest/cql/types.html#udts) are represented as JavaScript objects. For example: Consider the following UDT and table CREATE TYPE address ( street text, city text, state text, zip int, phones set ); CREATE TABLE users ( name text PRIMARY KEY, email text, address frozen
); You can retrieve the user address details as a regular JavaScript object. const query = 'SELECT name, address FROM users WHERE key = ?'; const result = await client.execute(query, [ key ], { prepare: true }); const row = result.first(); const address = row.address; console.log('User lives in %s, %s - %s', address.street, address.city, address.state); Read more information about using [UDTs with the Node.js Driver](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/udts/) . ### Paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#paging) All driver methods use a default `fetchSize` of 5000 rows, retrieving only first page of results up to a maximum of 5000 rows to shield an application against accidentally retrieving large result sets in a single response. `stream()` method automatically fetches the following page once the current one was read. You can also use `eachRow()` method to retrieve the following pages by using `autoPage` flag. See \[paging documentation for more information\]\[doc-paging\]. ### Batch multiple statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#batch-multiple-statements) You can execute multiple statements in a batch to update/insert several rows atomically even in different column families. const queries = [\ {\ query: 'UPDATE user_profiles SET email=? WHERE key=?',\ params: [ emailAddress, 'hendrix' ]\ }, {\ query: 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)',\ params: [ 'hendrix', 'Changed email', new Date() ]\ }\ ]; await client.batch(queries, { prepare: true }); console.log('Data updated on cluster'); Object Mapper[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#object-mapper) --------------------------------------------------------------------------------------------------- The driver provides a built-in [object mapper](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/) that lets you interact with your data like you would interact with a set of documents. Retrieving objects from the database: const videos = await videoMapper.find({ userId }); for (let video of videos) { console.log(video.name); } Updating an object from the database: await videoMapper.update({ id, userId, name, addedDate, description }); You can read more information about [getting started with the Mapper in our documentation](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/getting-started/) . * * * Data types[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#data-types) --------------------------------------------------------------------------------------------- There are few data types defined in the ECMAScript specification, this usually represents a problem when you are trying to deal with data types that come from other systems in JavaScript. The driver supports all the CQL data types in Apache Cassandra (3.0 and below) even for types with no built-in JavaScript representation, like decimal, varint and bigint. Check the documentation on working with [numerical values](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/numerical/) , [uuids](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/uuids/) and [collections](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/collections/) . Logging[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#logging) --------------------------------------------------------------------------------------- Instances of `Client()` are `EventEmitter` and emit `log` events: client.on('log', (level, loggerName, message, furtherInfo) => { console.log(`${level} - ${loggerName}: ${message}`); }); The `level` being passed to the listener can be `verbose`, `info`, `warning` or `error`. Visit the [logging documentation](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/logging/) for more information. Compatibility[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#compatibility) --------------------------------------------------------------------------------------------------- * Apache Cassandra versions 2.1 and above. * DataStax Enterprise versions 4.8 and above. * Node.js versions 8 and above. Note: DataStax products do not support big-endian systems. Credits[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#credits) --------------------------------------------------------------------------------------- This driver is based on the original work of [Jorge Bay](https://github.com/jorgebay) on [node-cassandra-cql](https://github.com/jorgebay/node-cassandra-cql) and adds a series of advanced features that are common across all other [DataStax drivers](https://github.com/datastax) for Apache Cassandra. The development effort to provide an up to date, high performance, fully featured Node.js Driver for Apache Cassandra will continue on this project, while [node-cassandra-cql](https://github.com/jorgebay/node-cassandra-cql) will be discontinued. License[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/index.html#license) --------------------------------------------------------------------------------------- © DataStax, Inc. Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --- # DataStax Node.js Driver - Getting Started [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/getting-started/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/getting-started/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/getting-started/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/getting-started/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/getting-started/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/getting-started/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/getting-started/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/getting-started/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/getting-started/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/getting-started/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/getting-started/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/getting-started/) * Getting started[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/index.html#getting-started) ======================================================================================================================= Getting started with the DataStax Node.js driver for Apache Cassandra. Connecting to a cluster[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/index.html#connecting-to-a-cluster) --------------------------------------------------------------------------------------------------------------------------------------- To connect to an Apache Cassandra cluster, you need to provide the address or host name of at least one node in the cluster and the local data center (DC) name. The driver will discover all the nodes in the cluster and connect to all the nodes in the local data center. Typically, you should create only a single `Client` instance for a given Cassandra cluster and use it across your application. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); client.connect(); At this point, the driver will be connected to all the nodes in the local data center and discovered the rest of the nodes in your cluster. Even though calling `connect()` is not required (the `execute()` method internally calls to connect), it is recommended you call to `#connect()` on application startup, this way you can ensure that you start your app once your are connected to your cluster. When using [DataStax Astra](https://www.datastax.com/products/datastax-astra) you can configure your client by setting the secure bundle and the user credentials: const client = new cassandra.Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); Retrieving data[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/index.html#retrieving-data) ----------------------------------------------------------------------------------------------------------------------- The `execute()` method can be used to send a CQL query to a Cassandra node. const query = "SELECT name, email, birthdate FROM users WHERE key = 'mick-jagger'"; client.execute(query) .then(result => { const row = result.first(); // The row is an Object with column names as property keys. console.log('My name is %s and my email is %s', row['name'], row['email']); }); Execution methods in the driver return a `Promise`, you can await on the promise to be fulfilled using [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) . Note that for the rest of the documentation, Promise method `then()` and `await` will be used interchangeably. ### Using query parameters and prepared statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/index.html#using-query-parameters-and-prepared-statements) Instead of hard-coding your parameters in your query, you can use parameter markers in your queries and provide the parameters as an Array. const query = 'SELECT name, email, birthdate FROM users WHERE key = ?'; const result = await client.execute(query, ['mick-jagger']); This way you can reuse the query and forget about escaping / stringifying the parameters in your query. Additionally, if you plan to reuse a query within your application (it is generally the case, your parameter value changes but there is only a small number of different queries for a given schema), **you can benefit from using prepared statements**. Using prepared statements increases performance compared to plain executes, especially for repeated queries, as the query only needs to be parsed once by the Cassandra node. It has the **additional benefit of providing metadata of the parameters to the driver, allowing better type mapping between JavaScript and Cassandra** without the need of additional info (hints) from the user. // Recommended: use query markers for parameters const query = 'SELECT name, email, birthdate FROM users WHERE key = ?'; // Recommended: set the prepare flag in your queryOptions const result = await client.execute(query, ['mick-jagger'], { prepare: true }); See the [data types documentation to see how CQL types are mapped to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/) . Inserting data[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/index.html#inserting-data) --------------------------------------------------------------------------------------------------------------------- You can use the `#execute()` method to execute any CQL query. const query = 'INSERT INTO users (key, name, email, birthdate) VALUES (?, ?, ?)'; const params = ['mick-jagger', 'Sir Mick Jagger', 'mick@rollingstones.com', new Date(1943, 6, 26)]; await client.execute(query, params, { prepare: true }); The promise is fulfilled when the data is inserted. ### Setting the consistency level[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/index.html#setting-the-consistency-level) To specify how consistent the data must be for a given read or write operation, you can set the [consistency level](https://docs.datastax.com/en/dse/6.7/dse-arch/datastax_enterprise/dbInternals/dbIntConfigConsistency.html) per query. const { types } = cassandra; await client.execute(query, params, { consistency: types.consistencies.quorum }); The promise is fulfilled when the data has been written in the number of replicas satisfying the consistency level specified. You can also provide a default consistency level for all your queries when creating the `Client` instance (defaults to `localOne`). const client = new Client({ queryOptions: { consistency: types.consistencies.localQuorum }, // ... rest of the options }); Mapper (optional)[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/index.html#mapper-optional) ------------------------------------------------------------------------------------------------------------------------- The driver provides [a built-in object mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/) that lets you interact with your data like you would interact with a set of documents. const userVideos = await videoMapper.find({ userId }); for (let video of userVideos) { console.log(video.name); } Visit the [Getting Started with the Mapper Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/getting-started/) for more information. Authentication (optional)[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/index.html#authentication-optional) ----------------------------------------------------------------------------------------------------------------------------------------- Using an authentication provider on an auth-enabled Cassandra cluster: const authProvider = new cassandra.auth.PlainTextAuthProvider('my_user', 'p@ssword1!'); //Set the auth provider in the clientOptions when creating the Client instance const client = new Client({ contactPoints, localDataCenter, authProvider }); Working with mixed workloads[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/index.html#working-with-mixed-workloads) ------------------------------------------------------------------------------------------------------------------------------------------------- The driver features [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles) that provide a mechanism to group together a set of configuration options and reuse them across different query executions. [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles) are specially useful when dealing with different workloads like Graph and CQL workloads, allowing you to use a single `Client` instance for all workloads, for example: const client = new cassandra.Client({ contactPoints: ['host1'], localDataCenter: 'oltp-us-west', profiles: [\ new ExecutionProfile('time-series', {\ consistency: consistency.localOne,\ readTimeout: 30000,\ serialConsistency: consistency.localSerial\ }),\ new ExecutionProfile('graph', {\ loadBalancing: new DefaultLoadBalancingPolicy('graph-us-west'),\ consistency: consistency.localQuorum,\ readTimeout: 10000,\ graphOptions: { name: 'myGraph' }\ })\ ] }); // Use an execution profile for a CQL query client.execute('SELECT * FROM system.local', null, { executionProfile: 'time-series' }); // Use an execution profile for a gremlin query client.executeGraph('g.V().count()', null, { executionProfile: 'graph' }); --- # DataStax Node.js Driver - ExecutionOptions [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/class.ExecutionOptions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/class.ExecutionOptions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/class.ExecutionOptions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/class.ExecutionOptions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/class.ExecutionOptions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/class.ExecutionOptions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/class.ExecutionOptions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/class.ExecutionOptions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * class ExecutionOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#class-execution-options) ================================================================================================================================================= A base class that represents a wrapper around the user provided query options with getter methods and proper default values. Note that getter methods might return `undefined` when not set on the query options or default `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` options. Global This class is global Constructor[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#constructor) -------------------------------------------------------------------------------------------------------------------------- new ### ExecutionOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#execution-options) () Creates a new instance of `[ExecutionOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/) `. Methods[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#methods) ------------------------------------------------------------------------------------------------------------------ ### getCaptureStackTrace[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-capture-stack-trace) () Determines if the stack trace before the query execution should be maintained. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | ### getConsistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-consistency) () Gets the `[Consistency level](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/#constant.consistencies) ` to be used for the execution. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getCustomPayload[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-custom-payload) () Key-value payload to be passed to the server. On the server side, implementations of QueryHandler can use this data. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) ` | | ### getFetchSize[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-fetch-size) () Gets the amount of rows to retrieve per page. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getFixedHost[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-fixed-host) () When a fixed host is set on the query options and the query plan for the load-balancing policy is not used, it gets the host that should handle the query. Returns: | Type | Description | | --- | --- | | `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` | | ### getHints[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-hints) () Gets the type hints for parameters given in the query, ordered as for the parameters. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) ` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `\> | | ### getKeyspace[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-keyspace) () Gets the keyspace for the query when set at query options level. Note that this method will return `undefined` when the keyspace is not set at query options level. It will only return the keyspace name when the user provided a different keyspace than the current `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` keyspace. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) ` | | ### getLoadBalancingPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-load-balancing-policy) () Gets the load balancing policy used for this execution. Returns: | Type | Description | | --- | --- | | `LoadBalancingPolicy` | A `LoadBalancingPolicy` instance, it can’t be `undefined`. | ### getPageState[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-page-state) () Gets the Buffer representing the paging state. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `Buffer` | | ### getRawQueryOptions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-raw-query-options) () Gets the query options as provided to the execution method without setting the default values. Returns: | Type | Description | | --- | --- | | `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` | | ### getReadTimeout[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-read-timeout) () Gets the timeout in milliseconds to be used for the execution per coordinator. A value of `0` disables client side read timeout for the execution. Default: `undefined`. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getRetryPolicy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-retry-policy) () Gets the `[retry policy](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/module.retry/) ` to be used. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `RetryPolicy` | A `RetryPolicy` instance, it can’t be `undefined`. | ### getRoutingKey[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-routing-key) () Gets the partition key(s) to determine which coordinator should be used for the query. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `Buffer` or `[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) `<`Buffer`\> | | ### getSerialConsistency[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-serial-consistency) () Gets the the consistency level to be used for the serial phase of conditional updates. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) ` | | ### getTimestamp[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#get-timestamp) () Gets the provided timestamp for the execution in microseconds from the unix epoch (00:00:00, January 1st, 1970). When a timestamp generator is used, this method returns `undefined`. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) `, `Long`, `[undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined) ` or `[null](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null) ` | | ### isAutoPage[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#is-auto-page) () Determines whether the driver must retrieve the following result pages automatically. This setting is only considered by the `[Client#eachRow()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#function.each-row) ` method. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | ### isBatchCounter[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#is-batch-counter) () Determines whether its a counter batch. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#function.batch) `, it will be ignored by other methods. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | A `Boolean` value, it can’t be `undefined`. | ### isBatchLogged[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#is-batch-logged) () Determines whether the batch should be written to the batchlog. Only valid for `[Client#batch()](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/#function.batch) `, it will be ignored by other methods. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | A `Boolean` value, it can’t be `undefined`. | ### isIdempotent[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#is-idempotent) () Determines whether the query can be applied multiple times without changing the result beyond the initial application. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | ### isPrepared[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#is-prepared) () Determines whether the query must be prepared beforehand. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | A `Boolean` value, it can’t be `undefined`. | ### isQueryTracing[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/index.html#is-query-tracing) () Determines whether query tracing is enabled for the execution. Abstract This function is abstract Returns: | Type | Description | | --- | --- | | `[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) ` | | --- # DataStax Node.js Driver - Mapper [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/mapper/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/mapper/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/mapper/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/mapper/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/mapper/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/mapper/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/mapper/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/mapper/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Mapper[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/index.html#mapper) ===================================================================================================== The driver provides an object mapper that lets you interact with your data like you would interact with a set of documents. Mapper Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/index.html#mapper-features) ----------------------------------------------------------------------------------------------------------------------- * No / minimal configuration required: no need to specify the schema manually, it uses the driver schema metadata * Support denormalized schemas and materialized views: one model can be mapped to multiple tables * Convention-based mapping * Support bypassing query generation / bring your own queries and map results * Minimal performance impact compared to the core driver Basic Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/index.html#basic-usage) --------------------------------------------------------------------------------------------------------------- Retrieving objects from the database: const videos = await videoMapper.find({ userId }); for (let video of videos) { console.log(video.name); } Updating an object from the database: await videoMapper.update({ id, userId, name, addedDate, description }); Note that execution methods return a `Promise`, to simplify the code examples in the documentation [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) are used. You can continue by reading the [Getting Started Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/getting-started/) or other topics in the Mapper documentation: * [Getting Started Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/getting-started/) * [Queries](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/queries/) * [Defining Mappings](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/defining-mappings/) * [Limitations and FAQ](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/limitations-and-faq/) --- # DataStax Node.js Driver - Logging [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/logging/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/logging/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/logging/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/logging/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/logging/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/logging/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/logging/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/logging/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/logging/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Logging[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/logging/index.html#logging) ======================================================================================================== The DataStax Node.js driver uses [events](https://nodejs.org/api/events.html) to expose logging information decoupled from any specific logging framework. The driver’s `Client` inherits from [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) and it triggers `'log'` events. client.on('log', (level, loggerName, message, furtherInfo) => { console.log(`${level} - ${loggerName}: ${message}`); }); The level being passed to the listener can be `'verbose'`, `'info'`, `'warning'` or `'error'`. `verbose` level is only suitable for debugging and it’s usually too noisy. We recommend that you gather logging events from `info` and above on production environments. Tracking query latency and size[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/logging/index.html#tracking-query-latency-and-size) -------------------------------------------------------------------------------------------------------------------------------------------------------- The `RequestLogger` logs queries executed by the driver and it allows tracking requests considered slow and/or large. A request is considered “slow” when it takes longer to complete than a configured threshold in milliseconds. A request is considered to be large when the request size is greater than a configured threshold in bytes. To turn on this feature, you first need to create an instance of `RequestLogger` and use it when creating the `Client` instance: const cassandra = require('cassandra-driver'); const requestTracker = new cassandra.tracker.RequestLogger({ slowThreshold: 1000 }); const client = new Client({ contactPoints, localDataCenter, requestTracker }); You can subscribe to `'slow'`, `'large'`, `'normal'` and `'failure'` events using the emitter object instance: requestTracker.emitter.on('slow', message => console.log(message)); An example message would be: [10.1.1.1:9042] Slow request, took 305 ms (request size 35 bytes / response size 1 KB): SELECT col1, col2 FROM table1 WHERE id = ? [1] Note that events will be emitted only when certain options are defined: * `'slow'` events will only be emitted if `slowThreshold` is set. * `'large'` events will only be emitted if `requestSizeThreshold` is set. * `'normal'` events will only be emitted if `logNormalRequests` is set to `true`. This setting can be changed at runtime using the `RequestLogger` property of the same name. * `'failure'` events will only be emitted if `logErroredRequests` is set to `true`. This setting can be changed at runtime using the property of the same name. You can provide your own tracker implementing `RequestTracker` interface. --- # DataStax Node.js Driver - Three simple rules for coding with the driver [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/coding-rules/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/coding-rules/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/coding-rules/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/coding-rules/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/coding-rules/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/coding-rules/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/coding-rules/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/coding-rules/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/coding-rules/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/coding-rules/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/coding-rules/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/coding-rules/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/coding-rules/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/coding-rules/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/coding-rules/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/coding-rules/) * Three simple rules for coding with the driver[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/coding-rules/index.html#three-simple-rules-for-coding-with-the-driver) ================================================================================================================================================================================ When writing code that uses the driver, there are three simple rules that you should follow that make your code efficient: * Only use one `Client` instance per keyspace or use a single Client and explicitly specify the keyspace in your queries and reuse it in across your modules in the application lifetime. * If you execute a statement more than once, use a prepared statement. * In some situations you can reduce the number of network roundtrips and also have atomic operations by using batches. Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/coding-rules/index.html#client) -------------------------------------------------------------------------------------------------- The `Client` instance allows you to configure different important aspects of the way connections and queries are handled. At this level, you can configure everything from contact points (address of the nodes to be contacted initially before the driver performs node discovery), the request routing policy, retry and reconnection policies, and so on. Generally such settings are set once at the application level. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['10.1.1.3', '10.1.1.4', '10.1.1.5'], localDataCenter: 'us-east-1' }); A `Client` instance is a long-lived object, your code should share the same `Client` instance across your application. Prepared statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/coding-rules/index.html#prepared-statements) ---------------------------------------------------------------------------------------------------------------------------- Using prepared statements provides multiple benefits. A prepared statement is parsed and prepared on the Cassandra nodes and is ready for future execution. When binding parameters are provided, only they (and the query id) are sent over the wire. These performance gains add up when using the same queries (with different parameters) repeatedly. Additionally, when preparing, the driver retrieves information about the parameter types which allows an accurate mapping between a JavaScript type and a CQL type. Preparing and executing statements in the driver does not require two chained asynchronous calls. You can set the `prepare` flag in the query options and the driver handles the rest. const query = 'SELECT id, name FROM users WHERE id = ?'; client.execute(query, [ id ], { prepare: true }); Batch statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/coding-rules/index.html#batch-statements) ---------------------------------------------------------------------------------------------------------------------- The batch statement combines multiple data modification statements (`INSERT`, `UPDATE`, or `DELETE`) into a single logical operation that is sent to the server in a single request. Batching together multiple operations also ensures that they are executed in an atomic way, (that is, either all succeed or none). To make the best use of `batch()`, read about [atomic batches in Cassandra 1.2](http://www.datastax.com/dev/blog/atomic-batches-in-cassandra-1-2) , [static columns and batching of conditional updates](http://www.datastax.com/dev/dev/blog/cql-in-2-0-6) , and [CQL documentation](https://docs.datastax.com/en/cql/3.3/cql/cql_using/useBatchTOC.html) . But take into account that incorrect use of batch statements may increase load to servers. Batch queries should be prepared, by setting the `prepare` flag, when possible. const queries = [\ { query: 'UPDATE user_profiles SET email=? WHERE key=?',\ params: [emailAddress, 'hendrix']},\ { query: 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)',\ params: ['hendrix', 'Changed email', new Date()]}\ ]; const queryOptions = { prepare: true, consistency: cassandra.types.consistencies.localQuorum }; client.batch(queries, queryOptions) .then(() => console.log('Data updated on cluster')); --- # DataStax Node.js Driver - Geospatial types [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/geotypes/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/geotypes/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/geotypes/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/geotypes/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/geotypes/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Geospatial types[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/geotypes/index.html#geospatial-types) --------------------------------------------------------------------------------------------------------------------------- [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) comes with a set of additional CQL types to represent geospatial data: * `PointType` * `LineStringType` * `PolygonType`. cqlsh> CREATE TABLE points_of_interest(name text PRIMARY KEY, coords 'PointType'); cqlsh> INSERT INTO points_of_interest (name, coords) VALUES ('Eiffel Tower', 'POINT(48.8582 2.2945)'); The driver includes encoders and representations of these types in the `geometry` module that can be used directly as parameters in queries. All Javascript geospatial types implement `toString()`, that returns the string representation in [Well-known text](https://en.wikipedia.org/wiki/Well-known_text) format, and `toJSON()`, that returns the JSON representation in [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) format. Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/geotypes/index.html#usage) ----------------------------------------------------------------------------------------------------- const cassandra = require('cassandra-driver'); const Point = cassandra.geometry.Point; const insertQuery = 'INSERT INTO points_of_interest (name, coords) VALUES (?, ?)'; const selectQuery = 'SELECT coords FROM points_of_interest WHERE name = ?'; await client.execute(insertQuery, [ 'Eiffel Tower', new Point(48.8582, 2.2945) ]); const result = await client.execute(selectQuery, [ 'Eiffel Tower' ]); const row = result.first(); const point = row['coords']; console.log(point instanceof Point); // true console.log('x: %d, y: %d', point.x, point.y); // x: 48.8582, y: 2.2945 console.log(point.toString()); // 'POINT (48.8582 2.2945)' --- # DataStax Node.js Driver - Upgrade Guide [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/upgrade-guide/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/upgrade-guide/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/upgrade-guide/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/upgrade-guide/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/upgrade-guide/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Upgrade guide[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#upgrade-guide) ================================================================================================================= The purpose of this guide is to detail the changes made by the successive versions of the DataStax Node.js Driver that are relevant to for an upgrade from prior versions. If you have any questions or comments, you can [post them on the mailing list](https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user) . 4.4[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#4-4) --------------------------------------------------------------------------------------------- ### New default load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#new-default-load-balancing-policy) The driver uses the new `DefaultLoadBalancingPolicy` implementation as default load balancing policy. The new policy attempts to fairly distribute the load based on the amount of in-flight request per hosts. The local replicas are initially shuffled and [between the first two nodes in the shuffled list, the one with fewer in-flight requests is selected as coordinator](https://www.eecs.harvard.edu/%7Emichaelm/postscripts/mythesis.pdf) . ### Upgrade guide for DSE driver users[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#upgrade-guide-for-dse-driver-users) The DSE driver and the Apache Cassandra driver have been merged into a single package. There’s a dedicated [guide for DSE driver users that plan to migrate to the `cassandra-driver`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/upgrade-from-dse-driver) . * * * 4.2[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#4-2) --------------------------------------------------------------------------------------------- ### Tuple constructor with one parameter[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#tuple-constructor-with-one-parameter) The `Tuple` constructor had an undocumented behaviour when invoked with a single parameter which was an `Array`, the driver used the `Array` instance as `Tuple` elements. We removed this behaviour that was used internally. `Tuple.fromArray()` method should be used to build a `Tuple` from an `Array` of elements. 4.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#4-0) --------------------------------------------------------------------------------------------- The following is a list of changes made in version 4.0 of the driver that are relevant when upgrading from version 3.x. ### localDataCenter is now a required Client option[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#local-data-center-is-now-a-required-client-option) When using `DCAwareRoundRobinPolicy`, which is used by default, a local data center must now be provided to the `Client` options parameter as `localDataCenter`. This is necessary to prevent routing requests to nodes in remote data centers. ### Selection of contact points is now evaluated in random order[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#selection-of-contact-points-is-now-evaluated-in-random-order) The list of contact points provided as a Client option is now shuffled before selecting a node to connect to as part of initialization. This change was made for instances where configuration is shared between many clients. In this case, it is better to distribute initial connections to different nodes in the cluster instead of choosing the same node each time as the initial connection makes a number of queries to discover cluster topology and schema. ### Changes to the retry and load-balancing policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#changes-to-the-retry-and-load-balancing-policies) `ExecutionOptions` is introduced as a wrapper around the `QueryOptions`. The `ExecutionOptions` contains getter methods to obtain the values of each option, defaulting to the execution profile options or the ones defined in the `ClientOptions`. Previously, a shallow copy of the provided `QueryOptions` was used, resulting in unnecessary allocations and evaluations. The `LoadBalancingPolicy` and `RetryPolicy` base classes changed method signatures to take `ExecutionOptions` instances as argument instead of `QueryOptions`. Note that no breaking change was introduced for execution methods such as `Client#execute()`, `Client#batch()`, `Client#eachRow()` and `Client#stream()`. This change only affects custom implementations of the policies. ### Query idempotency and retries[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#query-idempotency-and-retries) The configured `RetryPolicy` is not engaged when a query errors with a `WriteTimeoutException` or request error and the query was not idempotent. In order to control the possibility of retrying when an timeout/error is encountered, you must mark the query as idempotent. You can define it at `QueryOptions` level when calling the execution methods. client.execute(query, params, { prepare: true, isIdempotent: true }) Additionally, you can define the default idempotence for all executions when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, queryOptions: { isIdempotent: true } }); Previously, a similar behaviour was available using `IdempotenceAwareRetryPolicy`, that is now marked as deprecated. ### Removed `retryOnTimeout` property of `QueryOptions`[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#removed-retry-ontimeout-property-of-query-options) `retryOnTimeout`, the property that controlled whether a request should be tried when a response wasn’t obtained after a period of time is no longer available. The behaviour should be now controlled using `onRequestError()` method on the `RetryPolicy` for idempotent queries. ### Changes on `OperationInfo` of the retry module[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#changes-on-operation-info-of-the-retry-module) The retry policy methods takes [`OperationInfo`](https://docs.datastax.com/en/developer/nodejs-driver/latest/api/module.policies/module.retry/type.OperationInfo/) as a parameter. Some `OperationInfo` properties changes or were removed. * Deprecated properties `handler`, `request` and `retryOnTimeout` were removed. * `options` property was replaced by `executionOptions` which is an instance of `ExecutionOptions`. ### Removed `meta` property from `ResultSet`[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#removed-meta-property-from-result-set) On earlier versions of the driver, the `ResultSet` exposed the property `meta` which contained the raw result metadata. This property was removed in the latest version. ### Removed `DCAwareRoundRobinPolicy` `usedHostsPerRemoteDC` constructor parameter[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#removed-dc-aware-round-robin-policy-used-hosts-per-remotedc-constructor-parameter) `DCAwareRoundRobinPolicy` no longer supports routing queries to hosts in remote data centers. Because of this `usedHostsPerRemoteDC` has been removed as a constructor parameter. This change was made because handling data center outages is better suited at a service level rather than within an application client. * * * 3.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#3-0) --------------------------------------------------------------------------------------------- ### Changes in CQL aggregates metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#changes-in-cql-aggregates-metadata) The `initCondition` property of `Aggregate`, the class that represents the metadata information of a CQL aggregate, changes from `Object` to `String`. * * * 2.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#2-0) --------------------------------------------------------------------------------------------- The following is a list of changes made in version 2.0 of the driver that are relevant when upgrading from version 1.x. ### API Changes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/index.html#api-changes) 1. `uuid` and `timeuuid` values are decoded as [`Uuid`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/uuids) and [`TimeUuid`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/uuids) instances. 2. `decimal` values are decoded as [`BigDecimal`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) instances. 3. `varint` values are decoded as [`Integer`](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/numerical) instances. 4. `inet` values are decoded as `InetAddress` instances. --- # DataStax Node.js Driver - Frequently Asked Questions [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/faq/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/faq/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/faq/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/faq/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/faq/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/faq/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/faq/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/faq/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/faq/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/faq/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/faq/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/faq/) * Frequently Asked Questions[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/index.html#frequently-asked-questions) ================================================================================================================================= ### Which versions of Apache Cassandra and DSE does the driver support?[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/index.html#which-versions-of-apache-cassandra-and-dse-does-the-driver-support) The driver supports all Apache Cassandra versions starting from 2.1 and [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) versions from 4.8 to the latest version. ### How do I generate a random uuid or a time-based uuid?[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/index.html#how-do-i-generate-a-random-uuid-or-a-time-based-uuid) Use the [Uuid and TimeUuid classes](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/datatypes/uuids) inside the types module. ### Should I create one `Client` instance per module in my application?[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/index.html#should-i-create-one-client-instance-per-module-in-my-application) Normally you should use one `Client` instance per application. You should share that instance between modules within your application. ### Should I shut down the pool after executing a query?[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/index.html#should-i-shut-down-the-pool-after-executing-a-query) No, only call `client.shutdown()` once in your application’s lifetime, normally when you shutdown your application. ### How can I use a list of values with the IN operator in a WHERE clause?[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/index.html#how-can-i-use-a-list-of-values-with-the-in-operator-in-a-where-clause) To provide a dynamic list of values in a single parameter, use the `IN` operator followed by the question mark placeholder without parenthesis in the query. The parameter containing the list of values should be of an instance of Array. For example: const query = 'SELECT * FROM table1 WHERE key1 = ? AND key2 IN ?'; const key1 = 'param1'; const allKeys2 = [ 'val1', 'val2', 'val3' ]; client.execute(query, [ key1, allKeys2 ], { prepare: true }); ### Can I use a single `Client` instance for graph and CQL?[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/index.html#can-i-use-a-single-client-instance-for-graph-and-cql) Yes, you can. You should use [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/execution-profiles/) to define your settings for CQL and graph workloads, for example: define which datacenter should be used for graph or for CQL. --- # DataStax Node.js Driver - Features [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/features/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/features/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/features/) * Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/index.html#features) ================================================================================================== The DataStax Node.js Driver is feature-rich and highly tunable Node.js client library for Apache Cassandra, DSE and DataStax products. Usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/index.html#usage) -------------------------------------------------------------------------------------------- * [Address resolution](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/address-resolution) * [Authentication](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth) * [Batch statements](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/batch) * [Cluster and schema metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/metadata) * [Concurrent execution API](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/concurrent-api) * [Connecting to DataStax Apollo database](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/cloud) * [Connection pooling](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/connection-pooling) * [CQL data types to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes) * [Execution profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles) * [Fetching large result sets](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/paging) * [Geospatial types support](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/geotypes) * [Graph support](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support) * [Logging](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/logging) * [Mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper) * [Native protocol](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/native-protocol) * [Parameterized queries](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/parameterized-queries) * [Promise and callback support](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/promise-callback) * [Query timestamps](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps) * [Query warnings](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-warnings) * [Speculative query executions](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions) * [TLS/SSL](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tls) * [Tuning policies](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tuning-policies) * [User-defined functions and aggregates](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/udfs) --- # DataStax Node.js Driver - TLS/SSL [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/tls/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/tls/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/tls/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tls/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/tls/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/tls/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/tls/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/tls/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/tls/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * TLS/SSL[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tls/index.html#tls-ssl) ==================================================================================================== You can secure traffic between the driver and Apache Cassandra with TLS/SSL. There are two aspects to that: * Client-to-node encryption, where the traffic is encrypted and the client verifies the identity of the Apache Cassandra nodes it connects to. * Optional client certificate authentication, where Apache Cassandra nodes also verify the identity of the client. This section describes the driver-side configuration, it assumes that you’ve already configured SSL encryption in Apache Cassandra, you can checkout the [server documentation that covers the basic procedures](https://docs.datastax.com/en/cassandra/3.0/cassandra/configuration/secureSSLClientToNode.html) . Driver configuration[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tls/index.html#driver-configuration) ------------------------------------------------------------------------------------------------------------------------------ Use `sslOptions` property in the [`ClientOptions`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.ClientOptions/) to enable client TLS/SSL encryption: const client = new Client({ contactPoints, localDataCenter, sslOptions: { rejectUnauthorized: true }}); await client.connect(); You can define the same object properties as the options in the [standard Node.js `tls.connect()` method](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) . The main difference is that server certificate validation against the list of supplied CAs is disabled by default. You should specify `rejectUnauthorized: true` in your settings to enable it. ### Enabling client certificate authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/tls/index.html#enabling-client-certificate-authentication) Much like in [Node.js standard tls module](https://nodejs.org/api/tls.html) , you can use `cert` and `key` properties to provide the certificate chain and private key. Additionally, you can override the trusted CA certificates using `ca` property: const sslOptions = { // Necessary only if the server requires client certificate authentication. key: fs.readFileSync('client-key.pem'), cert: fs.readFileSync('client-cert.pem'), // Necessary only if the server uses a self-signed certificate. ca: [ fs.readFileSync('server-cert.pem') ], rejectUnauthorized: true }; const client = new Client({ contactPoints, localDataCenter, sslOptions }); --- # DataStax Node.js Driver - Connecting to your DataStax Apollo database using a secure connection bundle [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/cloud/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/cloud/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/cloud/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/cloud/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/cloud/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/cloud/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Connecting to your DataStax Apollo database using a secure connection bundle[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/cloud/index.html#connecting-to-your-data-stax-apollo-database-using-a-secure-connection-bundle) ================================================================================================================================================================================================================================================= Quickstart[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/cloud/index.html#quickstart) ------------------------------------------------------------------------------------------------------------ Use the `ClientOptions` property `cloud` to connect to your [DataStax Apollo database on Constellation](https://constellation.datastax.com/) using your secure connection bundle (`secure-connect-DATABASE_NAME.zip`) and `credentials` property to provide your [CQL credentials](https://cassandra.apache.org/doc/latest/cql/security.html#cql-roles) . Here is an example of the minimum configuration needed to connect to your DataStax Apollo database using the secure connection bundle: const client = new Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' } }); Configurable settings when using a secure connection bundle[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/cloud/index.html#configurable-settings-when-using-a-secure-connection-bundle) -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can configure your `Client` instance using other `ClientOptions` properties, for example: const client = new Client({ cloud: { secureConnectBundle: 'path/to/secure-connect-DATABASE_NAME.zip' }, credentials: { username: 'user_name', password: 'p@ssword1' }, keyspace: 'my_ks' }); Note that `contactPoints` and `sslOptions` should not be set when using `secureConnectBundle`. --- # DataStax Node.js Driver - Authentication [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/auth/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/auth/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/auth/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/auth/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/auth/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/auth/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth/index.html#authentication) =================================================================================================================== The driver includes three authentication providers: * `PlainTextAuthProvider`: Plain-text authentication for Apache Cassandra and DSE. * `DsePlainTextAuthProvider`: Plain-text authentication for DSE unified auth. * `DseGssapiAuthProvider`: GSSAPI authentication for DSE. In case you are using plain-text authentication on the server, you can set the `credentials` when creating the `Client` instance. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints, localDataCenter, credentials: { username: 'my_username', password: 'my_p@ssword1!' } }); Setting the authentication provider[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth/index.html#setting-the-authentication-provider) ------------------------------------------------------------------------------------------------------------------------------------------------------------- For other authentication methods, you can configure the provider in the `Client` options: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints, localDataCenter, authProvider: new cassandra.auth.DseGssapiAuthProvider() }); Note that to use the `DseGssapiAuthProvider` you need to add the dependency to `kerberos` version `~1.0.0` in your application. DSE Unified Authentication[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth/index.html#dse-unified-authentication) ------------------------------------------------------------------------------------------------------------------------------------------- DSE Unified Authentication allows you to: * Proxy Login: Authenticate using a fixed set of authentication credentials but allow authorization of resources based on another user id. * Proxy Execute: Authenticate using a fixed set of authentication credentials but execute requests based on another user id. ### Proxy Login[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth/index.html#proxy-login) Proxy login allows you to authenticate with a user but act as another one. You need to ensure the authenticated user has the permission to use the authorization of resources of the other user. In the following example, we allow user “ben” to authenticate but use the authorization of “alice”. We grant login permission to “ben” by using a `GRANT` CQL query: GRANT PROXY.LOGIN ON ROLE 'alice' TO 'ben' Once “ben” is granted proxy login as “alice”: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: [ 'host1', 'host2' ], localDataCenter, authProvider: new cassandra.auth.DsePlainTextAuthProvider('ben', 'ben', 'alice') }); // All requests will be executed using the authorizationId 'alice' client.execute(query, params, { prepare: true }); ### Proxy Execute[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/auth/index.html#proxy-execute) Proxy execute allows you to execute requests as another user than the authenticated one. You need to ensure the authenticated user has the permission to use the authorization of resources of the specified user. In the following example will allow the user “ben” to execute requests as “alice”: We grant execute permission to “ben” by using a `GRANT` CQL query: GRANT PROXY.EXECUTE on role user1 to server Once “ben” is granted permission to execute queries as “alice”: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: [ 'host1', 'host2' ], localDataCenter, authProvider: new cassandra.auth.DsePlainTextAuthProvider('ben', 'ben') }); // The following requests will be executed as 'alice' client.execute(query, params, { prepare: true, executeAs: 'alice' }); Please see the [official documentation](https://docs.datastax.com/en/latest-dse/datastax_enterprise/unifiedAuth/unifiedAuthTOC.html) for more details. --- # DataStax Node.js Driver - Upgrading from the DSE Driver [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/upgrade-from-dse-driver/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/upgrade-from-dse-driver/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/upgrade-from-dse-driver/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/upgrade-from-dse-driver/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/upgrade-guide/upgrade-from-dse-driver/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Upgrading from the DSE Driver[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/upgrade-from-dse-driver/index.html#upgrading-from-the-dse-driver) ========================================================================================================================================================================= This guide is intended for users of the DSE driver that plan to migrate to the `cassandra-driver`. The `cassandra-driver` now supports all DataStax products and features, such as Unified Authentication, Kerberos, geo types and graph traversal executions, allowing you to use a single driver for Apache Cassandra, DSE or other DataStax products. Upgrading from `dse-driver` to `cassandra-driver` can be as simple as changing the import statement to point to the dse package: const { Client } = require('dse-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); Becomes: const { Client } = require('cassandra-driver'); const client = new Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); Submodules[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/upgrade-from-dse-driver/index.html#submodules) ----------------------------------------------------------------------------------------------------------------------------------- Most of the child modules are in the same path. const { auth, types, geometry, policies, mapping } = require('dse-driver'); Becomes: const { auth, types, geometry, policies, mapping } = require('cassandra-driver'); The only notable module path distinctions are Graph and Search types that are under `datastax` module. const { graph, search } = require('dse-driver'); Becomes: const { datastax } = require('cassandra-driver'); const { graph, search } = datastax; Load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/upgrade-from-dse-driver/index.html#load-balancing-policy) --------------------------------------------------------------------------------------------------------------------------------------------------------- The default load balancing policy on the `dse-driver` was `DseLoadBalancingPolicy`. In the `cassandra-driver`, a policy with the same behaviour is called `DefaultLoadBalancingPolicy`, which is the default. --- # DataStax Node.js Driver - geometry [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.geometry/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.geometry/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.geometry/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.geometry/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module geometry[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.geometry/index.html#module-geometry) =========================================================================================================================== Geometry module. Contains the classes to represent the set of additional CQL types for geospatial data that come with DSE 5.0. Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.geometry/index.html#classes) ----------------------------------------------------------------------------------------------------------- * `[LineString](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.geometry/class.LineString/) ` * `[Point](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.geometry/class.Point/) ` * `[Polygon](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.geometry/class.Polygon/) ` --- # DataStax Node.js Driver - Speculative query execution [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/speculative-executions/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/speculative-executions/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/speculative-executions/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/speculative-executions/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/features/speculative-executions/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/features/speculative-executions/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/features/speculative-executions/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/features/speculative-executions/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/features/speculative-executions/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/features/speculative-executions/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/features/speculative-executions/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/features/speculative-executions/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Speculative query execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/index.html#speculative-query-execution) =============================================================================================================================================================== Sometimes a server node might be experiencing difficulties (for example, long GC pause) and take longer than usual to reply. Queries sent to that node experience higher latencies than expected. One thing we can do to improve that is preemptively start a second execution of the query against another node, before the first node has replied or errored out. If that second node replies faster, we can send the response back to the client (we also cancel the first query): ![Text Diagram]() Or the first node could reply just after the second execution was started. In this case, we cancel the second execution. In other words, whichever node replies faster wins and completes the client query: ![Text Diagram]() Note that “cancelling” in this context simply means marking the operation to discard the response when it later arrives. Speculative executions are disabled by default. The following sections cover the practical details and how to enable them. Query idempotence[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/index.html#query-idempotence) ------------------------------------------------------------------------------------------------------------------------------------------- One important aspect to consider is whether queries are idempotent, (that is, whether they can be applied multiple times without changing the result beyond the initial application). If a query is not idempotent, the driver never schedules speculative executions for it, because there is no way to guarantee that only one node will apply the mutation. Examples of queries that are not idempotent are: * counter operations * prepending or appending to a list column * using non-idempotent CQL functions, like `now()` or `uuid()` In the driver, this is determined by [`isIdempotent` flag in the `QueryOptions`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/type.QueryOptions/) . Because the driver does not parse query strings, in most cases it has no information about what the query actually does. Therefore, for all other types of statements, it defaults to `false`. You must set it manually with one of the mechanisms described below. You can override the value for each execution: const query = 'SELECT * FROM users WHERE key = ?'; client.execute(query, [ 'usr1' ], { prepare: true, isIdempotent: true }); Additionally, if you know for a fact that your application does not use any of the non-idempotent CQL queries listed above, you can change the default cluster-wide: // Make all statements idempotent by default: const client = new Client({ contactPoints, localDataCenter, queryOptions: { isIdempotent: true } }); Enabling speculative execution[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/index.html#enabling-speculative-execution) --------------------------------------------------------------------------------------------------------------------------------------------------------------------- Speculative executions are controlled by an instance of `SpeculativeExecutionPolicy` provided when initializing the `Client`. This policy defines the threshold after which a new speculative execution is triggered. The driver provides a `ConstantSpeculativeExecutionPolicy` that schedules a given number of speculative executions, separated by a fixed delay, the policy is exported under the `.policies.speculativeExecution` module. This simple policy uses a constant threshold: const { Client, policies } = require('cassandra-driver'); const ConstantSpeculativeExecutionPolicy = policies.speculativeExecution.ConstantSpeculativeExecutionPolicy; const client = new Client({ contactPoints, policies: { speculativeExecution: new ConstantSpeculativeExecutionPolicy( 200, // delay before a new execution is launched 2) // maximum amount of additional executions } }); Given the configuration above, an idempotent query would be handled this way: * start the initial execution at t0 * if no response has been received at t0 + 200 milliseconds, start a speculative execution on another node * if no response has been received at t0 + 400 milliseconds, start another speculative execution on a third node As with the rest of policies in the driver, you can provide your own implementation by extending the `SpeculativeExecutionPolicy` prototype. How speculative executions affect retries[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/index.html#how-speculative-executions-affect-retries) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Regardless of speculative executions, the driver has a retry mechanism: * on an internal error, it will try the next host * if the consistency level cannot be reached (for example, unavailable error or read or write timeout), it delegates the decision to the `RetryPolicy`, which might trigger a retry on the same host Turning speculative executions on does not change this behavior. Each parallel execution trigger retries independently: ![Text Diagram]() The only impact is that all executions of the same query always share the same query plan, so each host is used by at most one execution. Tuning and practical details[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/speculative-executions/index.html#tuning-and-practical-details) ----------------------------------------------------------------------------------------------------------------------------------------------------------------- The goal of speculative executions is to improve overall latency (the time between `execute(query)` and `complete` in the diagrams above) at high percentiles. On the flipside, they cause the driver to send more individual requests, so throughput does not necessarily improve. One side-effect of speculative executions is that many requests are cancelled, which can lead to a phenomenon called stream id exhaustion: each TCP connection can handle multiple simultaneous requests, identified by a unique number called stream id. When a request gets cancelled, we can’t reuse its stream id immediately because we might still receive a response from the server later. If this happens often, the number of available stream ids diminishes over time, and when it goes below a given threshold we close the connection and create a new one. If requests are often cancelled, so will see connections being recycled at a high rate. This problem is more likely to happen with old server versions (Apache Cassandra version 2.0 or below and DSE 4.6 or below) which only support version 1 and 2 of the native protocol where each TCP connection only has 128 available stream ids. With modern server versions, there are 32K stream ids per connection, so higher cancellation rates can be sustained. Another issue that might arise is that you get unintuitive results because of request ordering. Suppose you run the following query with speculative executions enabled: insert into my_table (k, v) values (1, 1); The first execution is a bit too slow, so a second execution gets triggered. Finally, the first execution completes, so the client code gets back an acknowledgement, and the second execution is cancelled. However, cancelling only means that the driver stops waiting for the server’s response, the request could still be on the wire; let us assume that this is the case. Now you run the following query, which completes successfully: delete from my_table where k = 1; But now the second execution of the first query finally reaches its target node, which applies the mutation. The row that you’ve just deleted is back! **Using [query timestamps](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/query-timestamps) **, which are enabled by default, prevents this issue to appear as each request will have a client-level timestamp which will define the order to apply the mutations. --- # DataStax Node.js Driver - API docs [DataStax Node.js Driver 4.6 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.6 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/api/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/api/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/api/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/api/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/api/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/api/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/api/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/api/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/api/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/api/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/api/) * API documentation[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/index.html#api-documentation) =============================================================================================================== Top level objects Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/index.html#modules) ------------------------------------------------------------------------------------------- * `[geometry](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.geometry/) ` * `[datastax](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.datastax/) ` * `[types](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.types/) ` * `[auth](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.auth/) ` * `[policies](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.policies/) ` * `[mapping](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.mapping/) ` * `[metadata](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metadata/) ` * `[concurrent](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.concurrent/) ` * `[errors](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.errors/) ` * `[tracker](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.tracker/) ` * `[metrics](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.metrics/) ` Classes[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/index.html#classes) ------------------------------------------------------------------------------------------- * `[TransitionalModePlainTextAuthenticator](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.TransitionalModePlainTextAuthenticator/) ` * `[Client](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Client/) ` * `[ExecutionProfile](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionProfile/) ` * `[ExecutionOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.ExecutionOptions/) ` * `[Encoder](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Encoder/) ` * `[Host](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.Host/) ` * `[HostMap](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/class.HostMap/) ` Types[](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/index.html#types) --------------------------------------------------------------------------------------- * `[ClientOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ClientOptions/) ` * `[QueryOptions](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.QueryOptions/) ` * `[ResultCallback](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/type.ResultCallback/) ` --- # DataStax Node.js Driver - Three simple rules for coding with the driver [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/coding-rules/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/coding-rules/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/coding-rules/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/coding-rules/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/coding-rules/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/coding-rules/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/coding-rules/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/coding-rules/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/coding-rules/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/coding-rules/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/coding-rules/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/coding-rules/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/coding-rules/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/coding-rules/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/coding-rules/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/coding-rules/) * Three simple rules for coding with the driver[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/coding-rules/index.html#three-simple-rules-for-coding-with-the-driver) ================================================================================================================================================================================ When writing code that uses the driver, there are three simple rules that you should follow that make your code efficient: * Only use one `Client` instance per keyspace or use a single Client and explicitly specify the keyspace in your queries and reuse it in across your modules in the application lifetime. * If you execute a statement more than once, use a prepared statement. * In some situations you can reduce the number of network roundtrips and also have atomic operations by using batches. Client[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/coding-rules/index.html#client) -------------------------------------------------------------------------------------------------- The `Client` instance allows you to configure different important aspects of the way connections and queries are handled. At this level, you can configure everything from contact points (address of the nodes to be contacted initially before the driver performs node discovery), the request routing policy, retry and reconnection policies, and so on. Generally such settings are set once at the application level. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['10.1.1.3', '10.1.1.4', '10.1.1.5'], localDataCenter: 'us-east-1' }); A `Client` instance is a long-lived object, your code should share the same `Client` instance across your application. Prepared statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/coding-rules/index.html#prepared-statements) ---------------------------------------------------------------------------------------------------------------------------- Using prepared statements provides multiple benefits. A prepared statement is parsed and prepared on the Cassandra nodes and is ready for future execution. When binding parameters are provided, only they (and the query id) are sent over the wire. These performance gains add up when using the same queries (with different parameters) repeatedly. Additionally, when preparing, the driver retrieves information about the parameter types which allows an accurate mapping between a JavaScript type and a CQL type. Preparing and executing statements in the driver does not require two chained asynchronous calls. You can set the `prepare` flag in the query options and the driver handles the rest. const query = 'SELECT id, name FROM users WHERE id = ?'; client.execute(query, [ id ], { prepare: true }); Batch statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/coding-rules/index.html#batch-statements) ---------------------------------------------------------------------------------------------------------------------- The batch statement combines multiple data modification statements (`INSERT`, `UPDATE`, or `DELETE`) into a single logical operation that is sent to the server in a single request. Batching together multiple operations also ensures that they are executed in an atomic way, (that is, either all succeed or none). To make the best use of `batch()`, read about [atomic batches in Cassandra 1.2](http://www.datastax.com/dev/blog/atomic-batches-in-cassandra-1-2) , [static columns and batching of conditional updates](http://www.datastax.com/dev/dev/blog/cql-in-2-0-6) , and [CQL documentation](https://docs.datastax.com/en/cql/3.3/cql/cql_using/useBatchTOC.html) . But take into account that incorrect use of batch statements may increase load to servers. Batch queries should be prepared, by setting the `prepare` flag, when possible. const queries = [\ { query: 'UPDATE user_profiles SET email=? WHERE key=?',\ params: [emailAddress, 'hendrix']},\ { query: 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)',\ params: ['hendrix', 'Changed email', new Date()]}\ ]; const queryOptions = { prepare: true, consistency: cassandra.types.consistencies.localQuorum }; client.batch(queries, queryOptions) .then(() => console.log('Data updated on cluster')); --- # DataStax Node.js Driver - Graph support [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/features/graph-support/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/features/graph-support/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/features/graph-support/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/features/graph-support/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Graph support[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/index.html#graph-support) ========================================================================================================================== `Client` includes the `executeGraph()` method to execute graph queries: const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'dc1', graphOptions: { name: 'demo' } }); // executeGraph() method returns a Promise client.executeGraph('g.V()') .then(function (result) { const vertex = result.first(); console.log(vertex.label); }); Alternatively, you can use the callback-based execution: client.executeGraph('g.V()', function (err, result) { assert.ifError(err); const vertex = result.first(); // ... }); Graph Options[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/index.html#graph-options) -------------------------------------------------------------------------------------------------------------------------- You can set default graph options when initializing `Client` which will be used for all graph statements. For example, to avoid providing a `graphName` option in each `executeGraph()` call: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'dc1', graphOptions: { name: 'demo' } }); These options may be overridden by specifying the [execution profile](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles) when calling `executeGraph()`: // Use a different graph name than the one provided when creating the client instance const result = await client.executeGraph(query, params, { executionProfile: 'graph-oltp' }); const vertex = result.first(); console.log(vertex.label); You can check out more info on [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles) . Handling Results[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/index.html#handling-results) -------------------------------------------------------------------------------------------------------------------------------- Graph queries return a `GraphResultSet`, which is an [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable) of items. The format of the data returned is dependent on the data requested. Retrieving property values: const result = await client.executeGraph('g.V().hasLabel("person").values("name")'); for (const name of result) { console.log(name); } Retrieving vertices: const result = await client.executeGraph('g.V().hasLabel("person")'); for (const vertex of result) { console.log(vertex.label); } Retrieving edges: const result = await client.executeGraph('g.E()'); for (const edge of result) { console.log(edge.label); } ### Parameters[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/index.html#parameters) Graph traversal execution supports named parameters. Parameters must be passed in as an object: const traversal = 'g.addV(vertexLabel).property("name", username)'; await client.executeGraph(traversal, { vertexLabel: 'person', username: 'marko' }); ### Graph types[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/index.html#graph-types) The DataStax Node.js driver supports a wide variety of TinkerPop types and [DSE types](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/) . For graph types that don’t have a native JavaScript representation, the driver provides the [`types` module](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.types/) . For example: const { types } = require('cassandra-driver'); const { Uuid, InetAddress } = types; const traversal = 'g.addV("sample").property("uid", uid).property("ip_address", address)'; await client.execute(traversal, { uid: Uuid.random(), address: InetAddress.fromString('10.0.0.100') }); The same types are also supported for traversal execution results: const rs = await client.execute('g.V().hasLabel("sample").values("ip_address")'); for (const ip of rs) { console.log(ip instanceof InetAddress); // true } #### User-defined types[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/graph-support/index.html#user-defined-types) User-defined types (UDTs) are supported in the Node.js driver using JavaScript objects. const rs = await client.execute('g.V().hasLabel("sample").values("user_address")'); for (const address of rs) { console.log(`User address is ${address.street}, ${address.city} ${address.state}`); } In order to use a UDT as a parameter, you must wrap the object instance using `asUdt()` function to provide additional information to properly represent the UDT on the server. const { datastax } = require('cassandra-driver'); const { asUdt } = datastax.graph; // Get the UDT metadata const udtInfo = await client.metadata.getUdt(graphName, 'address'); // Build the UDT const address = asUdt({ street: '123 Priam St.', city: 'My City', state: 'MY' }, udtInfo); const traversal = 'g.addV("sample").property("uid", uid).property("user_address", address)'; // Use the UDT as parameter await client.execute(traversal, { uid: Uuid.random(), address }); --- # DataStax Node.js Driver - datastax [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/api/module.datastax/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/api/module.datastax/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/api/module.datastax/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.datastax/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/api/module.datastax/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * module datastax[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.datastax/index.html#module-datastax) =========================================================================================================================== DataStax module. Contains modules and classes to represent functionality that is specific to DataStax products. Modules[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.datastax/index.html#modules) ----------------------------------------------------------------------------------------------------------- * `[graph](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.datastax/module.graph/) ` * `[search](https://docs.datastax.com/en/developer/nodejs-driver/4.5/api/module.datastax/module.search/) ` --- # DataStax Node.js Driver - Upgrade Guide [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/upgrade-guide/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/upgrade-guide/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/upgrade-guide/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/upgrade-guide/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/upgrade-guide/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/upgrade-guide/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/upgrade-guide/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/upgrade-guide/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * Upgrade guide[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#upgrade-guide) ================================================================================================================= The purpose of this guide is to detail the changes made by the successive versions of the DataStax Node.js Driver that are relevant to for an upgrade from prior versions. If you have any questions or comments, you can [post them on the mailing list](https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user) . 4.4[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#4-4) --------------------------------------------------------------------------------------------- ### New default load balancing policy[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#new-default-load-balancing-policy) The driver uses the new `DefaultLoadBalancingPolicy` implementation as default load balancing policy. The new policy attempts to fairly distribute the load based on the amount of in-flight request per hosts. The local replicas are initially shuffled and [between the first two nodes in the shuffled list, the one with fewer in-flight requests is selected as coordinator](https://www.eecs.harvard.edu/%7Emichaelm/postscripts/mythesis.pdf) . ### Upgrade guide for DSE driver users[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#upgrade-guide-for-dse-driver-users) The DSE driver and the Apache Cassandra driver have been merged into a single package. There’s a dedicated [guide for DSE driver users that plan to migrate to the `cassandra-driver`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/upgrade-from-dse-driver) . * * * 4.2[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#4-2) --------------------------------------------------------------------------------------------- ### Tuple constructor with one parameter[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#tuple-constructor-with-one-parameter) The `Tuple` constructor had an undocumented behaviour when invoked with a single parameter which was an `Array`, the driver used the `Array` instance as `Tuple` elements. We removed this behaviour that was used internally. `Tuple.fromArray()` method should be used to build a `Tuple` from an `Array` of elements. 4.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#4-0) --------------------------------------------------------------------------------------------- The following is a list of changes made in version 4.0 of the driver that are relevant when upgrading from version 3.x. ### localDataCenter is now a required Client option[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#local-data-center-is-now-a-required-client-option) When using `DCAwareRoundRobinPolicy`, which is used by default, a local data center must now be provided to the `Client` options parameter as `localDataCenter`. This is necessary to prevent routing requests to nodes in remote data centers. ### Selection of contact points is now evaluated in random order[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#selection-of-contact-points-is-now-evaluated-in-random-order) The list of contact points provided as a Client option is now shuffled before selecting a node to connect to as part of initialization. This change was made for instances where configuration is shared between many clients. In this case, it is better to distribute initial connections to different nodes in the cluster instead of choosing the same node each time as the initial connection makes a number of queries to discover cluster topology and schema. ### Changes to the retry and load-balancing policies[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#changes-to-the-retry-and-load-balancing-policies) `ExecutionOptions` is introduced as a wrapper around the `QueryOptions`. The `ExecutionOptions` contains getter methods to obtain the values of each option, defaulting to the execution profile options or the ones defined in the `ClientOptions`. Previously, a shallow copy of the provided `QueryOptions` was used, resulting in unnecessary allocations and evaluations. The `LoadBalancingPolicy` and `RetryPolicy` base classes changed method signatures to take `ExecutionOptions` instances as argument instead of `QueryOptions`. Note that no breaking change was introduced for execution methods such as `Client#execute()`, `Client#batch()`, `Client#eachRow()` and `Client#stream()`. This change only affects custom implementations of the policies. ### Query idempotency and retries[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#query-idempotency-and-retries) The configured `RetryPolicy` is not engaged when a query errors with a `WriteTimeoutException` or request error and the query was not idempotent. In order to control the possibility of retrying when an timeout/error is encountered, you must mark the query as idempotent. You can define it at `QueryOptions` level when calling the execution methods. client.execute(query, params, { prepare: true, isIdempotent: true }) Additionally, you can define the default idempotence for all executions when creating the `Client` instance: const client = new Client({ contactPoints, localDataCenter, queryOptions: { isIdempotent: true } }); Previously, a similar behaviour was available using `IdempotenceAwareRetryPolicy`, that is now marked as deprecated. ### Removed `retryOnTimeout` property of `QueryOptions`[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#removed-retry-ontimeout-property-of-query-options) `retryOnTimeout`, the property that controlled whether a request should be tried when a response wasn’t obtained after a period of time is no longer available. The behaviour should be now controlled using `onRequestError()` method on the `RetryPolicy` for idempotent queries. ### Changes on `OperationInfo` of the retry module[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#changes-on-operation-info-of-the-retry-module) The retry policy methods takes [`OperationInfo`](https://docs.datastax.com/en/developer/nodejs-driver/latest/api/module.policies/module.retry/type.OperationInfo/) as a parameter. Some `OperationInfo` properties changes or were removed. * Deprecated properties `handler`, `request` and `retryOnTimeout` were removed. * `options` property was replaced by `executionOptions` which is an instance of `ExecutionOptions`. ### Removed `meta` property from `ResultSet`[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#removed-meta-property-from-result-set) On earlier versions of the driver, the `ResultSet` exposed the property `meta` which contained the raw result metadata. This property was removed in the latest version. ### Removed `DCAwareRoundRobinPolicy` `usedHostsPerRemoteDC` constructor parameter[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#removed-dc-aware-round-robin-policy-used-hosts-per-remotedc-constructor-parameter) `DCAwareRoundRobinPolicy` no longer supports routing queries to hosts in remote data centers. Because of this `usedHostsPerRemoteDC` has been removed as a constructor parameter. This change was made because handling data center outages is better suited at a service level rather than within an application client. * * * 3.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#3-0) --------------------------------------------------------------------------------------------- ### Changes in CQL aggregates metadata[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#changes-in-cql-aggregates-metadata) The `initCondition` property of `Aggregate`, the class that represents the metadata information of a CQL aggregate, changes from `Object` to `String`. * * * 2.0[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#2-0) --------------------------------------------------------------------------------------------- The following is a list of changes made in version 2.0 of the driver that are relevant when upgrading from version 1.x. ### API Changes[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/upgrade-guide/index.html#api-changes) 1. `uuid` and `timeuuid` values are decoded as [`Uuid`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/uuids) and [`TimeUuid`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/uuids) instances. 2. `decimal` values are decoded as [`BigDecimal`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) instances. 3. `varint` values are decoded as [`Integer`](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/numerical) instances. 4. `inet` values are decoded as `InetAddress` instances. --- # DataStax Node.js Driver - Frequently Asked Questions [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/faq/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/faq/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/faq/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/faq/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/faq/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/faq/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/faq/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/faq/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/faq/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/faq/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/faq/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/faq/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/faq/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/faq/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/faq/) * Frequently Asked Questions[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/index.html#frequently-asked-questions) ================================================================================================================================= ### Which versions of Apache Cassandra and DSE does the driver support?[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/index.html#which-versions-of-apache-cassandra-and-dse-does-the-driver-support) The driver supports all Apache Cassandra versions starting from 2.1 and [DataStax Enterprise](http://www.datastax.com/products/datastax-enterprise) versions from 4.8 to the latest version. ### How do I generate a random uuid or a time-based uuid?[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/index.html#how-do-i-generate-a-random-uuid-or-a-time-based-uuid) Use the [Uuid and TimeUuid classes](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/uuids) inside the types module. ### Should I create one `Client` instance per module in my application?[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/index.html#should-i-create-one-client-instance-per-module-in-my-application) Normally you should use one `Client` instance per application. You should share that instance between modules within your application. ### Should I shut down the pool after executing a query?[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/index.html#should-i-shut-down-the-pool-after-executing-a-query) No, only call `client.shutdown()` once in your application’s lifetime, normally when you shutdown your application. ### How can I use a list of values with the IN operator in a WHERE clause?[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/index.html#how-can-i-use-a-list-of-values-with-the-in-operator-in-a-where-clause) To provide a dynamic list of values in a single parameter, use the `IN` operator followed by the question mark placeholder without parenthesis in the query. The parameter containing the list of values should be of an instance of Array. For example: const query = 'SELECT * FROM table1 WHERE key1 = ? AND key2 IN ?'; const key1 = 'param1'; const allKeys2 = [ 'val1', 'val2', 'val3' ]; client.execute(query, [ key1, allKeys2 ], { prepare: true }); ### Can I use a single `Client` instance for graph and CQL?[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/faq/index.html#can-i-use-a-single-client-instance-for-graph-and-cql) Yes, you can. You should use [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles/) to define your settings for CQL and graph workloads, for example: define which datacenter should be used for graph or for CQL. --- # DataStax Node.js Driver - Getting Started [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/getting-started/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/getting-started/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/getting-started/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/getting-started/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/getting-started/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/getting-started/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/getting-started/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/getting-started/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/getting-started/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/getting-started/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/getting-started/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/getting-started/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/getting-started/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/getting-started/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/getting-started/) * Getting started[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/index.html#getting-started) ======================================================================================================================= Getting started with the DataStax Node.js driver for Apache Cassandra. Connecting to a cluster[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/index.html#connecting-to-a-cluster) --------------------------------------------------------------------------------------------------------------------------------------- To connect to an Apache Cassandra cluster, you need to provide the address or host name of at least one node in the cluster and the local data center (DC) name. The driver will discover all the nodes in the cluster and connect to all the nodes in the local data center. Typically, you should create only a single `Client` instance for a given Cassandra cluster and use it across your application. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' }); client.connect(); At this point, the driver will be connected to all the nodes in the local data center and discovered the rest of the nodes in your cluster. Even though calling `connect()` is not required (the `execute()` method internally calls to connect), it is recommended you call to `#connect()` on application startup, this way you can ensure that you start your app once your are connected to your cluster. Retrieving data[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/index.html#retrieving-data) ----------------------------------------------------------------------------------------------------------------------- The `execute()` method can be used to send a CQL query to a Cassandra node. const query = "SELECT name, email, birthdate FROM users WHERE key = 'mick-jagger'"; client.execute(query) .then(result => { const row = result.first(); // The row is an Object with column names as property keys. console.log('My name is %s and my email is %s', row['name'], row['email']); }); Execution methods in the driver return a `Promise`, you can await on the promise to be fulfilled using [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) . Note that for the rest of the documentation, Promise method `then()` and `await` will be used interchangeably. ### Using query parameters and prepared statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/index.html#using-query-parameters-and-prepared-statements) Instead of hard-coding your parameters in your query, you can use parameter markers in your queries and provide the parameters as an Array. const query = 'SELECT name, email, birthdate FROM users WHERE key = ?'; const result = await client.execute(query, ['mick-jagger']); This way you can reuse the query and forget about escaping / stringifying the parameters in your query. Additionally, if you plan to reuse a query within your application (it is generally the case, your parameter value changes but there is only a small number of different queries for a given schema), **you can benefit from using prepared statements**. Using prepared statements increases performance compared to plain executes, especially for repeated queries, as the query only needs to be parsed once by the Cassandra node. It has the **additional benefit of providing metadata of the parameters to the driver, allowing better type mapping between JavaScript and Cassandra** without the need of additional info (hints) from the user. // Recommended: use query markers for parameters const query = 'SELECT name, email, birthdate FROM users WHERE key = ?'; // Recommended: set the prepare flag in your queryOptions const result = await client.execute(query, ['mick-jagger'], { prepare: true }); See the [data types documentation to see how CQL types are mapped to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/datatypes/) . Inserting data[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/index.html#inserting-data) --------------------------------------------------------------------------------------------------------------------- You can use the `#execute()` method to execute any CQL query. const query = 'INSERT INTO users (key, name, email, birthdate) VALUES (?, ?, ?)'; const params = ['mick-jagger', 'Sir Mick Jagger', 'mick@rollingstones.com', new Date(1943, 6, 26)]; await client.execute(query, params, { prepare: true }); The promise is fulfilled when the data is inserted. ### Setting the consistency level[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/index.html#setting-the-consistency-level) To specify how consistent the data must be for a given read or write operation, you can set the [consistency level](https://docs.datastax.com/en/dse/6.7/dse-arch/datastax_enterprise/dbInternals/dbIntConfigConsistency.html) per query. const { types } = cassandra; await client.execute(query, params, { consistency: types.consistencies.quorum }); The promise is fulfilled when the data has been written in the number of replicas satisfying the consistency level specified. You can also provide a default consistency level for all your queries when creating the `Client` instance (defaults to `localOne`). const client = new Client({ queryOptions: { consistency: types.consistencies.localQuorum }, // ... rest of the options }); Mapper (optional)[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/index.html#mapper-optional) ------------------------------------------------------------------------------------------------------------------------- The driver provides [a built-in object mapper](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/) that lets you interact with your data like you would interact with a set of documents. const userVideos = await videoMapper.find({ userId }); for (let video of userVideos) { console.log(video.name); } Visit the [Getting Started with the Mapper Guide](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/mapper/getting-started/) for more information. Authentication (optional)[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/index.html#authentication-optional) ----------------------------------------------------------------------------------------------------------------------------------------- Using an authentication provider on an auth-enabled Cassandra cluster: const authProvider = new cassandra.auth.PlainTextAuthProvider('my_user', 'p@ssword1!'); //Set the auth provider in the clientOptions when creating the Client instance const client = new Client({ contactPoints, localDataCenter, authProvider }); Working with mixed workloads[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/getting-started/index.html#working-with-mixed-workloads) ------------------------------------------------------------------------------------------------------------------------------------------------- The driver features [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles) that provide a mechanism to group together a set of configuration options and reuse them across different query executions. [Execution Profiles](https://docs.datastax.com/en/developer/nodejs-driver/4.5/features/execution-profiles) are specially useful when dealing with different workloads like Graph and CQL workloads, allowing you to use a single `Client` instance for all workloads, for example: const client = new cassandra.Client({ contactPoints: ['host1'], localDataCenter: 'oltp-us-west', profiles: [\ new ExecutionProfile('time-series', {\ consistency: consistency.localOne,\ readTimeout: 30000,\ serialConsistency: consistency.localSerial\ }),\ new ExecutionProfile('graph', {\ loadBalancing: new DefaultLoadBalancingPolicy('graph-us-west'),\ consistency: consistency.localQuorum,\ readTimeout: 10000,\ graphOptions: { name: 'myGraph' }\ })\ ] }); // Use an execution profile for a CQL query client.execute('SELECT * FROM system.local', null, { executionProfile: 'time-series' }); // Use an execution profile for a gremlin query client.executeGraph('g.V().count()', null, { executionProfile: 'graph' }); --- # DataStax Node.js Driver - Home [DataStax Node.js Driver 4.5 (Earlier version)](https://docs.datastax.com/en/developer/nodejs-driver/index.html) 4.5 * [4.8](https://docs.datastax.com/en/developer/nodejs-driver/4.8/) * [4.7](https://docs.datastax.com/en/developer/nodejs-driver/4.7/) * [4.6](https://docs.datastax.com/en/developer/nodejs-driver/4.6/) * [4.5](https://docs.datastax.com/en/developer/nodejs-driver/4.5/) * [4.4](https://docs.datastax.com/en/developer/nodejs-driver/4.4/) * [4.3](https://docs.datastax.com/en/developer/nodejs-driver/4.3/) * [4.2](https://docs.datastax.com/en/developer/nodejs-driver/4.2/) * [4.1](https://docs.datastax.com/en/developer/nodejs-driver/4.1/) * [4.0](https://docs.datastax.com/en/developer/nodejs-driver/4.0/) * [3.6](https://docs.datastax.com/en/developer/nodejs-driver/3.6/) * [3.5](https://docs.datastax.com/en/developer/nodejs-driver/3.5/) * [3.4](https://docs.datastax.com/en/developer/nodejs-driver/3.4/) * [3.3](https://docs.datastax.com/en/developer/nodejs-driver/3.3/) * [3.2](https://docs.datastax.com/en/developer/nodejs-driver/3.2/) * [3.1](https://docs.datastax.com/en/developer/nodejs-driver/3.1/) * [3.0](https://docs.datastax.com/en/developer/nodejs-driver/3.0/) * DataStax Node.js Driver for Apache Cassandra®[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#data-stax-node-js-driver-for-apache-cassandra) =================================================================================================================================================================== A modern, [feature-rich](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#features) and highly tunable Node.js client library for Apache Cassandra and [DSE](https://www.datastax.com/products/datastax-enterprise) using exclusively Cassandra’s binary protocol and Cassandra Query Language. Installation[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#installation) ------------------------------------------------------------------------------------------------- $ npm install cassandra-driver [![Build Status](https://api.travis-ci.com/datastax/nodejs-driver.svg?branch=master)](https://travis-ci.org/datastax/nodejs-driver) [![Build status](https://ci.appveyor.com/api/projects/status/m21t2tfdpmkjex1l/branch/master?svg=true)](https://ci.appveyor.com/project/datastax/nodejs-driver/branch/master) Features[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#features) ----------------------------------------------------------------------------------------- * Simple, Prepared, and [Batch](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/batch/) statements * Asynchronous IO, parallel execution, request pipelining * [Connection pooling](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/connection-pooling/) * Auto node discovery * Automatic reconnection * Configurable [load balancing](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#load-balancing-policy) and [retry policies](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/tuning-policies/#retry-policy) * Works with any cluster size * Built-in [object mapper](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/) * Both [promise and callback-based API](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/promise-callback/) * [Row streaming and pipes](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#row-streaming-and-pipes) * Built-in TypeScript support Documentation[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#documentation) --------------------------------------------------------------------------------------------------- * [Documentation index](https://docs.datastax.com/en/developer/nodejs-driver/latest/) * [CQL types to JavaScript types](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/) * [API docs](https://docs.datastax.com/en/developer/nodejs-driver/latest/api/) * [FAQ](https://docs.datastax.com/en/developer/nodejs-driver/latest/faq/) Getting Help[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#getting-help) ------------------------------------------------------------------------------------------------- You can use the [project mailing list](https://groups.google.com/a/lists.datastax.com/forum/#!forum/nodejs-driver-user) or create a ticket on the [Jira issue tracker](https://datastax-oss.atlassian.net/projects/NODEJS/issues) . Basic usage[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#basic-usage) ----------------------------------------------------------------------------------------------- const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['h1', 'h2'], localDataCenter: 'datacenter1', keyspace: 'ks1' }); const query = 'SELECT name, email FROM users WHERE key = ?'; client.execute(query, [ 'someone' ]) .then(result => console.log('User with email %s', result.rows[0].email)); The driver supports both [promises and callbacks](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/promise-callback/) for the asynchronous methods, you can choose the approach that suits your needs. Note that in order to have concise code examples in this documentation, we will use the promise-based API of the driver along with the `await` keyword. ### Prepare your queries[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#prepare-your-queries) Using prepared statements provides multiple benefits. Prepared statements are parsed and prepared on the Cassandra nodes and are ready for future execution. Also, when preparing, the driver retrieves information about the parameter types which **allows an accurate mapping between a JavaScript type and a Cassandra type**. The driver will prepare the query once on each host and execute the statement with the bound parameters. // Use query markers (?) and parameters const query = 'UPDATE users SET birth = ? WHERE key=?'; const params = [ new Date(1942, 10, 1), 'jimi-hendrix' ]; // Set the prepare flag in the query options await client.execute(query, params, { prepare: true }); console.log('Row updated on the cluster'); ### Row streaming and pipes[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#row-streaming-and-pipes) When using `#eachRow()` and `#stream()` methods, the driver parses each row as soon as it is received, yielding rows without buffering them. // Reducing a large result client.eachRow( 'SELECT time, val FROM temperature WHERE station_id=', ['abc'], (n, row) => { // The callback will be invoked per each row as soon as they are received minTemperature = Math.min(row.val, minTemperature); }, err => { // This function will be invoked when all rows where consumed or an error was encountered } ); The `#stream()` method works in the same way but instead of callback it returns a [Readable Streams2](https://nodejs.org/api/stream.html#stream_class_stream_readable) object in `objectMode` that emits instances of `Row`. It can be **piped** downstream and provides automatic pause/resume logic (it buffers when not read). client.stream('SELECT time, val FROM temperature WHERE station_id=', [ 'abc' ]) .on('readable', function () { // 'readable' is emitted as soon a row is received and parsed let row; while (row = this.read()) { console.log('time %s and value %s', row.time, row.val); } }) .on('end', function () { // Stream ended, there aren't any more rows }) .on('error', function (err) { // Something went wrong: err is a response error from Cassandra }); ### User defined types[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#user-defined-types) [User defined types (UDT)](https://cassandra.apache.org/doc/latest/cql/types.html#udts) are represented as JavaScript objects. For example: Consider the following UDT and table CREATE TYPE address ( street text, city text, state text, zip int, phones set ); CREATE TABLE users ( name text PRIMARY KEY, email text, address frozen
); You can retrieve the user address details as a regular JavaScript object. const query = 'SELECT name, address FROM users WHERE key = ?'; const result = await client.execute(query, [ key ], { prepare: true }); const row = result.first(); const address = row.address; console.log('User lives in %s, %s - %s', address.street, address.city, address.state); Read more information about using [UDTs with the Node.js Driver](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/udts/) . ### Paging[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#paging) All driver methods use a default `fetchSize` of 5000 rows, retrieving only first page of results up to a maximum of 5000 rows to shield an application against accidentally retrieving large result sets in a single response. `stream()` method automatically fetches the following page once the current one was read. You can also use `eachRow()` method to retrieve the following pages by using `autoPage` flag. See \[paging documentation for more information\]\[doc-paging\]. ### Batch multiple statements[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#batch-multiple-statements) You can execute multiple statements in a batch to update/insert several rows atomically even in different column families. const queries = [\ {\ query: 'UPDATE user_profiles SET email=? WHERE key=?',\ params: [ emailAddress, 'hendrix' ]\ }, {\ query: 'INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)',\ params: [ 'hendrix', 'Changed email', new Date() ]\ }\ ]; await client.batch(queries, { prepare: true }); console.log('Data updated on cluster'); Object Mapper[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#object-mapper) --------------------------------------------------------------------------------------------------- The driver provides a built-in [object mapper](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/) that lets you interact with your data like you would interact with a set of documents. Retrieving objects from the database: const videos = await videoMapper.find({ userId }); for (let video of videos) { console.log(video.name); } Updating an object from the database: await videoMapper.update({ id, userId, name, addedDate, description }); You can read more information about [getting started with the Mapper in our documentation](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/mapper/getting-started/) . * * * Data types[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#data-types) --------------------------------------------------------------------------------------------- There are few data types defined in the ECMAScript specification, this usually represents a problem when you are trying to deal with data types that come from other systems in JavaScript. The driver supports all the CQL data types in Apache Cassandra (3.0 and below) even for types with no built-in JavaScript representation, like decimal, varint and bigint. Check the documentation on working with [numerical values](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/numerical/) , [uuids](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/uuids/) and [collections](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/datatypes/collections/) . Logging[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#logging) --------------------------------------------------------------------------------------- Instances of `Client()` are `EventEmitter` and emit `log` events: client.on('log', (level, loggerName, message, furtherInfo) => { console.log(`${level} - ${loggerName}: ${message}`); }); The `level` being passed to the listener can be `verbose`, `info`, `warning` or `error`. Visit the [logging documentation](https://docs.datastax.com/en/developer/nodejs-driver/latest/features/logging/) for more information. Compatibility[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#compatibility) --------------------------------------------------------------------------------------------------- * Apache Cassandra versions 2.1 and above. * DataStax Enterprise versions 4.8 and above. * Node.js versions 8 and above. Note: DataStax products do not support big-endian systems. Credits[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#credits) --------------------------------------------------------------------------------------- This driver is based on the original work of [Jorge Bay](https://github.com/jorgebay) on [node-cassandra-cql](https://github.com/jorgebay/node-cassandra-cql) and adds a series of advanced features that are common across all other [DataStax drivers](https://github.com/datastax) for Apache Cassandra. The development effort to provide an up to date, high performance, fully featured Node.js Driver for Apache Cassandra will continue on this project, while [node-cassandra-cql](https://github.com/jorgebay/node-cassandra-cql) will be discontinued. License[](https://docs.datastax.com/en/developer/nodejs-driver/4.5/index.html#license) --------------------------------------------------------------------------------------- © DataStax, Inc. Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---