Skip to content

Cassandra CQL Protocol Documentation

This directory contains consolidated documentation for HeliosDB's Apache Cassandra CQL protocol support and compatibility.

Quick Start

Connect to HeliosDB using cqlsh or any Cassandra driver:

# Using cqlsh
cqlsh localhost 9042

# Create keyspace
CREATE KEYSPACE my_keyspace WITH REPLICATION = {
    'class': 'SimpleStrategy',
    'replication_factor': 1
};

USE my_keyspace;

# Create table
CREATE TABLE users (
    user_id UUID PRIMARY KEY,
    name TEXT,
    email TEXT
);

Contents

File Description
README.md Overview and quick start (this file)
CONFIGURATION.md Connection and protocol configuration
COMPATIBILITY.md CQL v4/v5 feature compatibility
EXAMPLES.md CQL examples and usage patterns

Feature Overview

Protocol Support

HeliosDB implements Apache Cassandra Native Protocol with full feature support:

  • Protocol v4/v5: Complete implementation
  • Frame encoding/decoding: Zero-copy parsing
  • Compression: LZ4, Snappy algorithms
  • Authentication: SASL, PasswordAuthenticator
  • Streaming: Multi-frame request/response

Protocol Completeness

Feature Status Notes
Binary Protocol (v4/v5) 100% Full support
Frame Compression 100% LZ4, Snappy
Authentication 100% SASL/Password
Prepared Statements 100% Full caching
Batch Operations 100% All batch types
Paging 100% Cursor-based
Events 100% SCHEMA_CHANGE, etc.

Architecture

Cassandra Client (cqlsh, DataStax driver)
           |
    CQL Binary Protocol (TCP port 9042)
           |
    Frame Codec (Compression, Auth)
           |
    CQL Parser & Executor
           |
    Wide-Column -> Relational Mapping
           |
    HeliosDB Storage Engine

Storage Mapping

Cassandra wide-column model is mapped to HeliosDB's relational storage:

Cassandra Concept HeliosDB Mapping
Keyspace Schema
Table Table
Partition Key Primary Key
Clustering Column Composite Primary Key
Regular Column Column
Collection Types JSONB
TTL Row-level expiration
Tombstones Soft delete with cleanup

Connection Parameters

Parameter Default Description
host localhost Server hostname
port 9042 CQL native port
keyspace - Default keyspace
username - Authentication user
password - Authentication password

Driver Compatibility

Language Driver Version Status
Java DataStax 4.x Full
Python cassandra-driver 3.x Full
Node.js cassandra-driver 4.x Full
Go gocql 1.x Full
C# CassandraCSharpDriver 3.x Full
C++ cpp-driver 2.x Full

Performance

Operation Latency Throughput
SELECT <1ms overhead 100K+ ops/sec
INSERT <1ms overhead 50K+ ops/sec
UPDATE <1ms overhead 50K+ ops/sec
Batch (100) <5ms overhead 10K batches/sec

CQL Features

Data Types

  • Primitives: ASCII, VARCHAR, BIGINT, INT, BOOLEAN, DOUBLE, FLOAT, BLOB, UUID, TIMESTAMP
  • Collections: LIST, SET, MAP (stored as JSONB)
  • Advanced: UDT, TUPLE, COUNTER, TIMEUUID, DURATION

DDL Support

  • Keyspace management (CREATE, ALTER, DROP)
  • Table management with all options
  • Secondary indexes
  • Materialized views

DML Support

  • SELECT with filtering
  • INSERT with TTL
  • UPDATE with conditions
  • DELETE with timestamps
  • BATCH operations

Last Updated: December 2025 Consolidation Status: Complete