Working with Embedded Cassandra Database

The embedded Cassandra service used by the Iotellect server is sufficient for a wide range of use cases, but exceptionally large or specialized systems may require unique database configurations.

For a full side‑by‑side comparison with external Cassandra, see Working with External Cassandra Database.

If you are upgrading Cassandra from 3.x to 5.x, see Data Migration Guide.

Embedded Cassandra uses a configuration model that is different from an external Cassandra deployment.

In embedded mode, Iotellect supports two configuration variants:

(1) embedded Cassandra with internal/default settings,

(2) embedded Cassandra with external YAML fine-tuning.

Both variants are selected on each Iotellect node in Server Configuration / Storage tab / NoSQL Storage subtab using the Use Embedded Service and Use External YAML Configuration File properties. (enables tuning via cassandra.yaml, applicable only when embedded service is enabled). For more details, see the section below.

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.

By default, the Iotellect server configures the embedded Cassandra service by applying databaseCassandra* parameters from its own configuration file (server.xml by default), along with certain internal default values.

The cassandra.yaml file is shipped with the Iotellect server (located in the Iotellect installation directory) is intended for use with the embedded Cassandra server only. Its purpose is to provide administrators with additional flexibility beyond the built-in configuration model.

Enabling cassandra.yaml does not convert the embedded database into an external or high-performance Cassandra deployment.

Use of cassandra.yaml in embedded mode remains limited to single-node operation managed by Iotellect. For production scalability, clustering, fault tolerance, and dedicated resource management, a separately installed external Cassandra cluster must be used.

When embedded mode is enabled:

• By default, Iotellect Server reads Cassandra-related settings from the databaseCassandra* parameters in server.xml.

• Network, storage, cluster name, ports, and memory-related settings are derived from the server configuration.

• If cassandra.yaml is used for embedded tuning, Cassandra server settings are taken from that file.

The embedded Cassandra engine is integrated with Iotellect Server lifecycle management.
Changing Cassandra configuration parameters may cause:

• inconsistent node identity

• incorrect network binding

• failed startup

• cluster membership issues

• data file schema mismatches

If cassandra.yaml is used to tune embedded Cassandra, configuration changes should be applied carefully and validated after restart.

This ensures consistent node behavior and reliable operation of the embedded database service.

In order to output embedded Cassandra logs to an external file:

1. Open the logging configuration file, which is typically logging.xml in the root directory of your Iotellect installation.

2. In the <Loggers>...</Loggers> section, remove the following lines:

   <Logger name="org.apache.cassandra.cql3.QueryProcessor" level="off"/>
   <Logger name="org.apache.cassandra.db.Memtable" level="off"/>
   <Logger name="org.apache.cassandra.io.sstable.SSTableDeletingTask" level="off"/>

3. In the <Loggers>...</Loggers> section, add the following lines:

         <Logger name="org.apache.cassandra" level="info" additivity="false">
             <AppenderRef ref="cassandra"/>
         </Logger>

4. In the <Appenders>...</Appenders> section, add the following lines:

        <File name="cassandra" fileName="logs/cassandra.log" append="false">
           <ThresholdFilter level="debug"/>
           <PatternLayout pattern="%d{dd.MM.yyyy HH:mm:ss,SSS} %-5p %-25c %m    -    [%t] %C.%M (%F:%L)%n%throwable{full}"/>
        </File>

5. Optionally, configure log file rotation by adding a Log4J Rolling File Appender to the logging.xml file.

The cassandra.yaml file in Iotellect is a modified copy of the standalone Cassandra default configuration file.

All the modifications are augmented with a comment header such as:

########################################################################################################################
NOTE
########################################################################################################################
This parameter was changed from default 'true' to 'false' according to internal config
########################################################################################################################

The file is located in the Iotellect server home (installation) directory.

The Iotellect distribution bundle also contains a backup file named cassandra.default.yaml with all the initial values kept intact. The file is not used by Iotellect and may serve as a rollback point in case of configuration failure.

You should not change cluster name. However, if this is unavoidable, you can add the following JVM options to the ag_server.vmoptions file (or another corresponding file):

-Dcassandra.ignore_rack=true
-Dcassandra.ignore_dc=true

This prevents server startup failure when cluster metadata differs.

For connection and configuration recommendations for a separately deployed Cassandra instance or cluster, see Working with External Cassandra Database.

To configure embedded Cassandra using the cassandra.yaml file:

Enable the “Use External YAML Configuration File” flag in the Server Configuration / Storage tab / NoSQL Storage subtab and restart the Iotellect server.

When this option is enabled:

• The embedded Cassandra service reads configuration from cassandra.yaml located in the Iotellect server installation directory.

• The databaseCassandra* parameters in server.xml are ignored.

Note that switching configuration sources may cause issues with an existing database. For example, if cassandra.yaml contains a different value for the cluster_name parameter, the server may fail to start.

This mechanism allows fine-tuning of the embedded Cassandra configuration.
It does not convert the embedded deployment into an external or multi-node Cassandra instance.

nodetool is a built-in Cassandra tool for getting various insights from the Cassandra nodes. It can be extremely useful for hunting down performance issues.

To use nodetool with the Iotellect embedded Cassandra service:

1. Download a Cassandra installation bundle compatible with the Cassandra version bundled with your Iotellect installation (Cassandra 3.x for AG 6.3, Cassandra 5.x for AG 6.4 and later) and extract it to any folder.

2. Make sure the Iotellect server is running with embedded Cassandra service enabled.

3. Make sure you have a compatible Java runtime set in your JAVA_HOME environment variable or corresponding java executable in your PATH variable. You can check the latter by issuing java -version command.

4. Navigate to the extracted bin/ directory and run the following command:

$ ./nodetool --port 11111 status

The --port option refers to embedded Cassandra' JMX port. If you run nodetool from a different machine, you also need to specify --host option with Iotellect IP address or host name.

The output of the command should look like:

Datacenter: datacenter1
========================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
-- Address    Load       Tokens       Owns (effective)  Host ID                               Rack
UN  127.0.0.1  1.35 MiB   256          100,0%            38512adb-b868-4ea1-9593-bf3b9950e687  rack1

The basic information commands of nodetool are status, version and info. There are many other helpful commands described in the documentation and in the tool itself (just run it without options or with the help command).

You can use the cqlsh utility from a Cassandra distribution compatible with the Cassandra version bundled with your Iotellect installation.

1. Ensure the Iotellect server is running with embedded Cassandra enabled.

2. Obtain the cqlsh tool from a Cassandra distribution matching your embedded Cassandra version (3.x for Iotellect 6.3, 5.x for Iotellect 6.4 and later).

3. Run:

$ ./cqlsh localhost 9042

If authentication is enabled:

$ ./cqlsh -u <username> -p <password>

After connecting, you should see output similar to:

Connected to <cluster_name> at 127.0.0.1:9042.
cqlsh>

To test a simple query:

cqlsh> SELECT count(*) FROM aggregate.ag_events;

Cassandra 3.x distributions typically require Python 2.7. Cassandra 5.x distributions use Python 3. Ensure the cqlsh version matches the Cassandra server version to avoid protocol compatibility issues.

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

Was this page helpful?

Tell us more

Send

Thank you!