Skip to content
HeliosDB HeliosDB Full

Cassandra CQL Quick Start Guide

Cassandra CQL Quick Start Guide

Get started with HeliosDB’s Cassandra CQL protocol support. Connect using your existing CQL drivers and tools with full protocol v4/v5 compatibility.

Prerequisites

  • HeliosDB server running (default CQL port: 9042)
  • cqlsh or a Cassandra driver (Python, Java, Node.js)
  • Basic familiarity with CQL syntax

Connection Details

ParameterDefault Value
Hostlocalhost
Port9042
ProtocolCQL Binary v4/v5
CompressionLZ4, Snappy
AuthenticationSASL, Password

5-Minute Getting Started

Step 1: Connect with cqlsh

Terminal window
# Basic connection
cqlsh localhost 9042


# With authentication
cqlsh localhost 9042 -u admin -p password

Step 2: Create a Keyspace

CREATE KEYSPACE my_app WITH REPLICATION = {
    'class': 'SimpleStrategy',
    'replication_factor': 1
};


USE my_app;

Step 3: Create a Table and Insert Data

CREATE TABLE users (
    user_id UUID PRIMARY KEY,
    name TEXT,
    email TEXT,
    created_at TIMESTAMP
);


INSERT INTO users (user_id, name, email, created_at)
VALUES (uuid(), 'Alice', 'alice@example.com', toTimestamp(now()));

Connecting with CQL Drivers

Python (cassandra-driver)

from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider


# With authentication
auth = PlainTextAuthProvider(username='admin', password='password')
cluster = Cluster(['localhost'], auth_provider=auth)
session = cluster.connect('my_app')


# Execute query
rows = session.execute("SELECT * FROM users LIMIT 10")
for row in rows:
    print(f"User: {row.name}, Email: {row.email}")


# Using prepared statements
prepared = session.prepare(
    "INSERT INTO users (user_id, name, email) VALUES (?, ?, ?)"
)
session.execute(prepared, [uuid.uuid4(), 'Bob', 'bob@example.com'])

Java (DataStax Driver)

import com.datastax.oss.driver.api.core.CqlSession;
import java.net.InetSocketAddress;


CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("localhost", 9042))
    .withLocalDatacenter("datacenter1")
    .withKeyspace("my_app")
    .build();


// Execute query
ResultSet rs = session.execute("SELECT * FROM users LIMIT 10");
for (Row row : rs) {
    System.out.println("User: " + row.getString("name"));
}


// Prepared statement
PreparedStatement prepared = session.prepare(
    "INSERT INTO users (user_id, name, email) VALUES (?, ?, ?)"
);
session.execute(prepared.bind(UUID.randomUUID(), "Charlie", "charlie@example.com"));

Node.js (cassandra-driver)

const cassandra = require('cassandra-driver');


const client = new cassandra.Client({
    contactPoints: ['localhost'],
    localDataCenter: 'datacenter1',
    keyspace: 'my_app',
    credentials: { username: 'admin', password: 'password' }
});


await client.connect();


// Execute query
const result = await client.execute('SELECT * FROM users LIMIT 10');
result.rows.forEach(row => console.log(`User: ${row.name}`));


// Prepared statement
const query = 'INSERT INTO users (user_id, name, email) VALUES (?, ?, ?)';
await client.execute(query, [cassandra.types.Uuid.random(), 'Diana', 'diana@example.com'],
    { prepare: true });

Basic CRUD Operations

CREATE (Insert)

-- Basic insert
INSERT INTO users (user_id, name, email, created_at)
VALUES (uuid(), 'User1', 'user1@example.com', toTimestamp(now()));


-- Insert with TTL (expires in 1 hour)
INSERT INTO users (user_id, name, email)
VALUES (uuid(), 'TempUser', 'temp@example.com')
USING TTL 3600;


-- Conditional insert (lightweight transaction)
INSERT INTO users (user_id, name, email)
VALUES (550e8400-e29b-41d4-a716-446655440000, 'Unique', 'unique@example.com')
IF NOT EXISTS;

READ (Select)

-- Select by primary key
SELECT * FROM users WHERE user_id = 550e8400-e29b-41d4-a716-446655440000;


-- Select with limit
SELECT name, email FROM users LIMIT 10;


-- Select as JSON
SELECT JSON * FROM users WHERE user_id = 550e8400-e29b-41d4-a716-446655440000;

UPDATE

-- Basic update
UPDATE users SET email = 'newemail@example.com'
WHERE user_id = 550e8400-e29b-41d4-a716-446655440000;


-- Conditional update (lightweight transaction)
UPDATE users SET email = 'verified@example.com'
WHERE user_id = 550e8400-e29b-41d4-a716-446655440000
IF email = 'unverified@example.com';

DELETE

-- Delete row
DELETE FROM users WHERE user_id = 550e8400-e29b-41d4-a716-446655440000;


-- Conditional delete
DELETE FROM users WHERE user_id = 550e8400-e29b-41d4-a716-446655440000
IF EXISTS;

Partition Key Design Tips

Single Partition Key

-- Good for direct lookups by user
CREATE TABLE users (
    user_id UUID PRIMARY KEY,
    name TEXT,
    email TEXT
);

Compound Partition Key (for time-series)

-- Partition by sensor and day to prevent hot spots
CREATE TABLE sensor_data (
    sensor_id UUID,
    day DATE,
    reading_time TIMESTAMP,
    value DOUBLE,
    PRIMARY KEY ((sensor_id, day), reading_time)
) WITH CLUSTERING ORDER BY (reading_time DESC);

Best Practices

TipDescription
Avoid Large PartitionsKeep partitions under 100MB
Time BucketingUse day/week/month buckets for time-series
Avoid ALLOW FILTERINGDesign schema to avoid full table scans
Use Clustering ColumnsFor sorting within partitions

Driver Configuration Examples

Python Connection Pool

from cassandra.cluster import Cluster
from cassandra.policies import DCAwareRoundRobinPolicy


cluster = Cluster(
    ['heliosdb-1', 'heliosdb-2', 'heliosdb-3'],
    port=9042,
    load_balancing_policy=DCAwareRoundRobinPolicy(local_dc='dc1'),
    protocol_version=4,
    compression=True
)
session = cluster.connect('my_app')

Java with Retry Policy

CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("localhost", 9042))
    .withLocalDatacenter("datacenter1")
    .withKeyspace("my_app")
    .withConfigLoader(DriverConfigLoader.programmaticBuilder()
        .withDuration(DefaultDriverOption.REQUEST_TIMEOUT, Duration.ofSeconds(30))
        .withInt(DefaultDriverOption.CONNECTION_POOL_LOCAL_SIZE, 4)
        .build())
    .build();

Key Features

FeatureStatusNotes
Binary Protocol v4/v5100%Full support
Prepared Statements100%Full caching
Batch Operations100%All batch types
TTL100%Row-level expiration
Lightweight Transactions100%IF EXISTS/IF NOT EXISTS
Collections100%LIST, SET, MAP

Next Steps

Last Updated: January 2026