Cassandra CQL Protocol Documentation

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

Related Documentation

• CONFIGURATION.md - Connection configuration
• COMPATIBILITY.md - Feature compatibility
• EXAMPLES.md - CQL examples
• Parent Directory - Protocol overview
• PROTOCOL_COMPATIBILITY_MATRIX.md - Cross-protocol comparison

---

Last Updated: December 2025 Consolidation Status: Complete