Working with External Cassandra Database

The embedded Cassandra service used by the Iotellect server is sufficient for a wide range of use cases. However, production deployments requiring scalability, clustering, or dedicated database infrastructure should use an external Cassandra instance or cluster.

Iotellect offers the flexibility to connect with an external Cassandra instance, giving administrators detailed control over the database infrastructure.

Cassandra Configuration Model in External Mode

When Iotellect Server connects to an external Cassandra cluster, Cassandra server configuration is managed entirely by Cassandra itself.
Cassandra server configuration is defined in cassandra.yaml and related configuration files located in the Cassandra installation directory.
In this mode:

  • Iotellect Server does not configure or modify cassandra.yaml.

  • databaseCassandra* parameters in server.xml are used only to configure the client-side connection from Iotellect Server to Cassandra (hosts, credentials, keyspace, etc.).

  • All operational settings (cluster name, topology, network binding, compaction, storage, memory limits) are defined in Cassandra configuration.

How Parameters Are Resolved

When connecting to external Cassandra:

  • Node identity, topology, and cluster name come from cassandra.yaml.

  • Network settings such as listen_address, broadcast_address, and rpc_address must be defined in the external Cassandra configuration.

  • Iotellect Server reads only the contact points, credentials, and keyspace information from server.xml — not Cassandra operational settings.

Why Cassandra Server Configuration Is Not Taken from server.xml

The Iotellect Server server does not attempt to override or modify the configuration of an external Cassandra instance.
In external mode:

  • Cassandra server configuration is defined exclusively in cassandra.yaml.

  • The databaseCassandra* parameters in server.xml are used only for connection settings.

The external Cassandra cluster must be fully configured and operational before connecting Iotellect Server.

Any conflicting configuration (for example, cluster name mismatch) may prevent Iotellect Server from establishing a connection.

Summary

Deployment mode

Active configuration

Ignored configuration

External Cassandra

Cassandra server settings: cassandra.yaml (operational settings on the Cassandra host)
Iotellect connection settings: server.xml (databaseCassandra* parameters used by Iotellect to connect)

Iotellect does not modify cassandra.yaml
Cassandra operational settings are not taken from server.xml (only connection settings are)

This model provides full compatibility with multi-node production clusters and avoids accidental configuration overrides.

Embedded vs External Cassandra Overview

Feature

Embedded Cassandra

External Cassandra

Cassandra Server Configuration

Iotellect Server settings (server.xml) and optional cassandra.yaml (embedded tuning)

cassandra.yaml only (in the Cassandra server’s own directory)

Multi-node deployment

No

Yes

JVM options (including memory constraints like Xmx, Xss, etc.)

Shared with Iotellect Server process

Separate for each Cassandra process

Recommended use cases

Getting started, prototyping, sandboxing, small production deployment

Production deployment, scaling, fault tolerance

For fine-tuning the embedded Cassandra service managed by Iotellect, see Working with Embedded Cassandra Database.

Iotellect settings for external Cassandra are configured on every Iotellect node in Server Configuration, Storage tab, NoSQL Storage subtab.

For the full list of NoSQL Storage fields and recommended values (including Database Host and Port vs Seeds/Contact Points, Replication Factor, and other tuning options), refer to NoSQL storage description.

Deploying an External Cassandra Instance

To deploy an external Cassandra instance:

  1. Install Java 17 or JDK 17.

  2. Install (unpack) the latest version of Apache Cassandra.

  3. Edit config/cassandra.yaml

    • Configure data directory and commitlog directory (preferably to different physical drives).

    • Ensure native transport is enabled (start_native_transport) and the native transport port is set (default 9042).

    • Specify the IP address of the Cassandra server in seeds, listen_address and rpc_address.

      If you modify the listen_address in your cassandra.yaml file to an IP address other than 127.0.0.1, you must also specify this address in the Iotellect server server.xml with the following option:

      <databaseCassandraHost>your_cassandra_ip_address</databaseCassandraHost>

  4. Set JAVA_HOME environment variable to JRE/JDK's root folder.

  5. Set CASSANDRA_HOME environment variable to Cassandra installation folder.

  6. Edit bin/cassandra

    • Change Xms and Xmx settings to a higher value, leaving at least 2-4 Gb of RAM for an operating system.

  7. Launch bin/cassandra and make sure Cassandra started listening for incoming connections.

  8. Adjust memory settings (Xms, Xmx) in Cassandra startup scripts according to available system resources.

    Start Cassandra and verify that it is listening for incoming connections.

Optimizing Cassandra Performance for Write-Heavy Workloads

Write-heavy workload means many insert operations. The faster you insert data, the faster you need to compact in order to keep the stable count down. Thus you will need to edit the following parameters in cassandra.yaml:

  • Increase the number of concurrent_compactors.

  • Increase the value of compaction_throughput_mb_per_sec or disable throttling by setting this parameter to zero.

You may need to change compaction strategy of particular tables. The following parameters might need to be changed:

  • compaction - the preferable strategy is TimeWindowCompactionStrategy. It was particularly designed for time series and expiring TTL workloads. For its customization you will only need to change compaction_window_unit and compaction_window_size. Also unchecked_tombstone_compaction must be set to true to make Cassandra drop expired sstables in real-time.

  • gc_grace_seconds - should be decreased or set to zero (only if you're using a single-node cluster).

To change compaction parameters you will need to execute a query using CQL interactive terminal. Launch bin/cqlsh to connect to your current Cassandra node:

USE aggregate;
ALTER TABLE <table _name> 
  WITH compaction = {'class' : 'TimeWindowCompactionStrategy', 'compaction_window_unit' : 'HOURS', 'compaction_window_size' : '1', 'unchecked_tombstone_compaction' : 'true'} 
  AND gc_grace_seconds = 0;

Before tuning your database using listed parameters please check the documentation for Apache Cassandra. Tuning the database may be different in your particular case.

Network Timeout Settings

Consider changing timeout settings when you plan to perform time-consuming operations. Otherwise you might get TimedOutException while working with a database.

Parameter

Description

range_request_timeout_in_ms

How long the coordinator should wait for seq or index scans to complete.

read_request_timeout_in_ms

How long the coordinator should wait for read operations to complete.

write_request_timeout_in_ms

How long the coordinator should wait for writes to complete.

request_timeout_in_ms

The default timeout for other, miscellaneous operations.

Be judicial when raising timeout rates, and understand the memory and CPU usage of the operations being performed. Timeout rates are a protection against clients waiting too long on operations which never complete because of an error or underlying resource constraints.

Troubleshooting with Nodetool

nodetool is a built-in Cassandra tool for getting various insights from the Cassandra nodes.

Use the nodetool utility provided with your external Cassandra installation. Run it on a Cassandra node or from a machine with access to the Cassandra node’s JMX interface.

Refer to official Apache Cassandra documentation for available commands.

Direct Querying with CQLSH

cqlsh is an interactive tool for querying to Cassandra database node.

Use the cqlsh utility provided with your external Cassandra installation to connect to your Cassandra node or cluster.

For more details on cqlsh see this page of the documentation. The syntax of CQL is described here.

Was this page helpful?