Cassandra Database Node

Overview

The Cassandra Database Node enables you to perform operations on a Cassandra database—such as querying, inserting, updating, and deleting records—directly within your Martini workflow.

For general details on database nodes and a list of supported databases (both NoSQL and SQL), see Workflow Database Node.

What You Will Learn

• How to add and configure a Cassandra Database Node in your workflow
• How to use Cassandra CQL queries with dynamic placeholders
• How to map workflow properties to Cassandra query inputs and from outputs

When to Use This

Use this node when you need to:

• Execute Cassandra database operations (read/write) using your workflow.
• Automate data flows between your workflow and an external Cassandra database.
• Integrate Cassandra query logic directly into your workflow for seamless backend automation.

See more use cases in Workflow Database Node: When To Use This.

Prerequisites

Before you start

1. Set up a Cassandra database: You need a running Cassandra database to store and retrieve data for your workflow.

2. Install Martini Designer: Martini Designer is required to build and manage workflows.
   See: Installation guide

3. Configure a Cassandra database connection in Martini:
   See: Creating and Configuring a Cassandra Connection in Martini

While using this feature

1. Create a Martini package: See: How to Create a Package

2. Create a workflow
   The workflow is where you'll add and configure the Cassandra Database Node.
   See: Workflow Creation Steps

Getting Started

The goal of this Getting Started section is to help you quickly set up and run a workflow that inserts data into a Cassandra database using the Cassandra Database Node.

Follow these steps for a fast hands-on experience:

Step 1: Database Setup

1. A Cassandra database and keyspace with a table named GUEST containing the columns firstname, lastname, and email must be configured within your Cassandra cluster.

Sample CQL to create the table:

CREATE KEYSPACE IF NOT EXISTS tutorial 
WITH replication = {'class':'SimpleStrategy', 'replication_factor' : 1};

USE tutorial;

CREATE TABLE guest (
    id UUID PRIMARY KEY,
    firstname text,
    lastname text,
    email text
);

✅ Validation: Run DESCRIBE TABLE guest; in cqlsh to verify table creation.

Step 2: Workflow Creation

1. Create a workflow.
2. Add the properties customerFirstName, customerLastName, and customerEmail to your workflow's Inputs and Outputs or declare them as new properties in the workflow.

✅ Validation: Properties should appear in the workflow's Input panel.

Step 3: Node Configuration

1. Add a Cassandra Database Node (lets your workflow interact with your database) in your created workflow, and connect to your Start Trigger (the node that begins workflow execution) or any other trigger node.
2. Click the expand icon on the node (this opens the Configuration Panel).

Step 4: Query Setup

1. In the Query Tab, set:
   • Connection Name: your configured Cassandra connection name
   • Type: Insert
   • Keyspace: Select your desired keyspace from the dropdown (e.g., tutorial)
   • Query: Use CQL with placeholders (variables like :firstName that get replaced with workflow values), e.g.:

     INSERT INTO guest (id, firstname, lastname, email)
     VALUES (uuid(), :firstName, :lastName, :email)
     

Step 5: Data Mapping

1. Open the Data Mapper Panel on your Database Node (if not already open)

   • Click the expand icon on your Database Query Node
   • Click the Data Mapping Tab

2. Map workflow properties to query placeholders in the Data Mapping Panel (where you link workflow properties to CQL placeholders):

   • customerFirstName → firstName
   • customerLastName → lastName
   • customerEmail → email

✅ Validation: All workflow input properties should show mapping lines to the database node input placeholder properties.

Step 6: Testing

1. Save and run your workflow to test the database insertion:

   • Save: Press Ctrl+S (Windows/Linux) or Cmd+S (Mac) to save your workflow
   • Run: Click the Run button or press F8 to execute your workflow

2. Check your table to see the new customer is inserted.

Verification query:

SELECT * FROM guest;

💡 Next Steps: You may add another Cassandra Database node to view rows in your table, add further business or validation logic, etc.

Adding a Cassandra Database Node

To add a Cassandra Database Node to your workflow:

1. Add a new Database Node by following these steps.

2. Click the expand icon on the node.
   What you'll see: A configuration panel appears with two tabs—Query and Data Mapping—where you configure your database interaction.

3. Once your node is added, proceed to the Configuration Panel section to set up your CQL queries and data mappings.

Configuration Panel

The Configuration Panel is where you set up your CQL operation and map workflow properties to database fields. This panel lets you control how your workflow interacts with Cassandra.

Initial Setup Steps

1. Go to the Query Tab.
   What you'll see: Fields for selecting your connection, operation type, and entering your CQL statement.

2. In the Connection Name field, select your configured Cassandra connection from the dropdown.
   Martini will recognize your connection type and prepare the node for Cassandra configuration.

3. In the Type field, select the CQL operation type you want to perform (e.g., Insert, Select Single, Select Multi, Update, Delete, etc.).

4. In the Keyspace field, select your desired keyspace from the dropdown.

5. Once your connection, type, and keyspace are selected, you can configure the specific CQL operation and data mappings as described in the following sections.

The Configuration Panel contains two tabs: Query Tab and Data Mapping Tab. For a full walkthrough, see a more general description on the Configuration Panel.

Query Tab

This panel allows you to set up your CQL operation and define any placeholders you need for dynamic values.

Fields and Configuration:

Property	Required	Example Value	Description
Connection Name	Yes	cassandra-main	Name of your Cassandra connection. Note: Martini will be able to pick up the connection configuration and type from the name.
Query	Yes	SELECT * FROM GUEST;	CQL statement to execute
Query Placeholders	No	:propertyName Example: INSERT INTO GUEST (ID, FIRSTNAME, LASTNAME) VALUES (:id, :firstname, :lastname);	Use placeholders to insert workflow values into your CQL queries dynamically. Placeholders like :id, :firstname, and :lastname will appear as the input properties id, firstname, and lastname in the Data Mapping Tab. See Data Mapping Tab for more information on the layout and descriptions of the Data Mapping Tab.
Type	Yes	Insert	CQL operation type. Supported types include: - Delete - Delete Batch - Insert - Insert Batch - Select Multi - Select Single - Universal - Update - Update Batch
Keyspace	No	tutorial	Select the desired keyspace for your CQL operation.

Data Mapping Tab

The Data Mapping Tab allows you to access the Cassandra Database Node's Mapper Panel. It uses Martini's standard Data Mapper Panel with the Double Mapper Layout to connect and transform data between your workflow and your Cassandra database.

The Data Mapping Panel visually connects workflow properties to Cassandra database node inputs and outputs. You can map workflow inputs to the Cassandra database node inputs and route outputs from executed operations back into your workflow. You can also declare new properties and set expressions.

Getting Started: Data Mapping

1. Open the Data Mapper Panel on your Database Node (if not already open)

2. Click the expand icon on your Database Query Node

3. Click the Data Mapping Tab

4. The panel appears in the lower half of the Workflow Designer.

Expected result: The Mapper Panel shows two main areas: Input (left) and Output (right).

Input Mapper Layout (Left)

| Workflow Properties      | Mapping Lines | Cassandra Database Node Input Properties |
|--------------------------|---------------|-------------------------------------------|
|                          |               | input Model                               |
|                          |               | +--$martiniConnectionPool                 |
|                          |               | +--$keyspace                              |
|                          |               | +--$consistencyLevel                      |
|                          |               | +--$serialConsistencyLevel                |
|                          |               | +--$idempotent                            |
|        [input1]          |   ------->    | +--[databaseNodeIn1]                      |

For complete details on using the Data Mapper Panel, including creating map lines, set expressions, and property management, see the Data Mapping Guide.

Cassandra Database Node Input Properties: Key Terms

Property	Purpose	Applicable Operations
$martiniConnectionPool	Allows you to set the connection pool dynamically within the workflow. Defaults to the configured Martini connection pool if not set.	All operations
$keyspace	Allows you to set the keyspace dynamically within the workflow. Defaults to the configured keyspace if not set.	All operations
$consistencyLevel	Allows you to set the consistency level for the CQL operation dynamically. Controls read/write consistency across Cassandra nodes. Options include ONE, QUORUM, ALL, etc.	All operations
$serialConsistencyLevel	Optional. Allows you to set the serial consistency level for Lightweight Transactions (LWT) - operations that provide ACID-like guarantees for INSERT and UPDATE statements that use the IF clause. Options: SERIAL (default), LOCAL_SERIAL For detailed information about LWT operations and consistency levels, see Cassandra Serial Consistency.	LWT operations (INSERT and UPDATE statements with IF clauses like INSERT ... IF NOT EXISTS)
$idempotent	Optional. Indicates whether the CQL statement is idempotent (can be safely retried). Helps with query optimization and retry logic. Set to true for operations that can be safely retried, or false for operations that should not be retried.	All operations
[databaseNodeInX]	Custom input properties generated from CQL query placeholders. Workflow properties can be mapped to these to dynamically set values needed for Cassandra read and write operations. See Custom Input Properties for details.	All operations with placeholders

For more information on Cassandra consistency levels and idempotence, see:

• Query Idempotence
• Data Consistency

Custom Input Properties

Custom input properties (represented as [databaseNodeInX] in this documentation) are generated from your CQL query placeholders. In the actual UI, these properties match the placeholder names you define in your CQL query, and will appear in the Data Mapping Panel for you to map workflow properties to.

For example, if your CQL query is SELECT * FROM companies WHERE name = :companyName, where the placeholder is :companyName, the property companyName will appear as a custom input property in the Data Mapping Panel.

Eg:

| Workflow Properties      | Mapping Lines | Cassandra Database Node Input Properties |
|--------------------------|---------------|-------------------------------------------|
|                          |               | input Model                               |
|                          |               | +--$martiniConnectionPool                 |
|                          |               | +--$keyspace                              |
|                          |               | +--$consistencyLevel                      |
|                          |               | +--$serialConsistencyLevel                |
|                          |               | +--$idempotent                            |
|        [input1]          |   ------->    | +--companyName                            |

For write operations, suppose you have a CQL insert statement like INSERT INTO companies (id, name, industry) VALUES (:id, :name, :industry). Martini will generate input properties in the Cassandra Database Node for id, name, and industry, allowing you to dynamically map workflow values to these properties in the Data Mapping Panel.

| Workflow Properties      | Mapping Lines | Cassandra Database Node Input Properties |
|--------------------------|---------------|-------------------------------------------|
|                          |               | input Model                               |
|                          |               | +--$martiniConnectionPool                 |
|                          |               | +--$keyspace                              |
|                          |               | +--$consistencyLevel                      |
|                          |               | +--$serialConsistencyLevel                |
|                          |               | +--$idempotent                            |
|        [input1]          |   ------->    | +--id                                     |
|                          |               | +--name                                   |
|                          |               | +--industry                               |

You can map workflow properties to these custom input properties, allowing you to dynamically set the values needed for Cassandra read and write operations at runtime, enabling powerful data-driven operations.

Output Mapper Layout (Right)

The output mapper shows the data returned from your Cassandra database operations. Different CQL operation types produce different outputs that you can map to workflow properties for further processing.

For complete details on using the Data Mapper Panel, including creating map lines, set expressions, and property management, see the Data Mapping Guide.

Select Single Operations

When you execute Select Single queries, your Cassandra database returns a single record through an output model with properties matching the column names from the fetched record:

| Database Node Output Properties | Mapping Lines | Workflow Output Properties |
|---------------------------------|---------------|---------------------------|
|      output                     |               |      [workflowOutput]     |
|      +--columnName1             |   ------->    |                           |
|      +--columnName2             |   ------->    |                           |
|      +--columnName3             |   ------->    |                           |

Output Properties for Select Single

Property	Type	Description
output	Model	A model object containing properties for each column in the returned record. Column names become property names that you can map to workflow properties.

Important:

• After running, The output model will be populated with properties that match exactly the column names returned by your Select query
• If no record is found, the output model's properties will all be null

Select Multi Operations

When you execute Select Multi queries, Cassandra returns data through an inputCursor that allows you to process results efficiently:

| Database Node Output Properties | Mapping Lines | Workflow Output Properties |
|---------------------------------|---------------|---------------------------|
|      inputCursor                |   ------->    |      [workflowOutput]     |

Output Properties for Select Multi

Property	Type	Description
inputCursor	Cursor	Batch read operations only. A cursor object containing the query results. You can iterate through this cursor using a Repeat Node to process each row individually.

Important:

• Use a Repeat Node after your Cassandra Database Node to iterate through each row in the cursor
• The cursor automatically handles memory management for large result sets

Need help processing multiple records? For a detailed guide on how to loop through large result sets efficiently, see Batch Read Operations.

Write Operations (Insert, Update, Delete)

Write operations allow you to modify data in your Cassandra database. Single and batch operations have different output behaviors.

Single Write Operations (Insert, Update, Delete)

Single write operations in Cassandra do not return output properties that can be mapped in the Data Mapping Panel. The operation completes successfully if no error occurs.

Batch Write Operations (Insert Batch, Update Batch, Delete Batch)

| Database Node Output Properties | Mapping Lines | Workflow Output Properties |
|---------------------------------|---------------|---------------------------|
|      outputCursor                |   ------->    |      [workflowOutput]     |

Output Properties for Batch Write Operations

Property	Type	Description
updateCount	Integer	Total number of records affected across the entire batch operation
outputCursor	Cursor	Cursor for iterating through batch data

💡 Key Differences:

• Single operations: No output properties available for mapping
• Batch operations: Includes outputCursor for iteration
• No generated keys: Unlike SQL databases, Cassandra doesn't support auto-generated keys in the same way
• Batch processing: Use a Repeat Node with outputCursor to process each record in the batch

Need help processing multiple records? For detailed guides on how to loop through large result sets and perform bulk operations efficiently, see:

• Batch Read Operations
• Batch Write Operations
• Batch Delete Operations

For complete details on using the Data Mapper Panel, including creating map lines, set expressions, and property management, see the Data Mapping Guide.

Troubleshooting

Problem	Detection	Cause	Fix	Affected Versions
Connection error	Node fails with connection error	Invalid or missing Cassandra connection	Verify connection settings in Martini	v2.2+
Placeholder not mapped	Workflow fails or returns null values	Required input property not mapped	Map all placeholders in Data Mapping Panel	v2.2+
CQL syntax error	line x:x: no viable alternative at input..	Invalid CQL syntax or malformed placeholders	1. Fix CQL syntax according to Cassandra documentation 2. Ensure placeholders use colon prefix: :placeholder 3. Escape reserved keywords with quotes 4. Test query in cqlsh first	v2.2+
Data type mismatch	Could not convert 'string_value' to int	Workflow property type doesn't match Cassandra column type	1. Convert data types in workflow before mapping 2. Update table schema if possible 3. Use appropriate CQL type conversion functions 4. Add type validation in workflow	v2.2+

See Workflow Database Node: Troubleshooting for more general database troubleshooting guidance.

Helpful Resources

• Workflow Database Node — General database node concepts and data mapping
• Creating and Configuring a Cassandra Connection in Martini
• MongoDB Database Node
• SQL Database Node
• CQL Reference: Cassandra Query Language Documentation
• Community Q&A: Martini Community
  Have a Question? Post or search it here.