---
title: "Cassandra CQL Protocol Documentation"
---

# Cassandra CQL Protocol Documentation

:::caution[What the listener serves today]
HeliosDB Full opens listeners for PostgreSQL, MySQL, Oracle, MongoDB,
Cassandra, Redis and SQL Server plus an HTTP gateway; MongoDB, Cassandra and SQL
Server clients can connect and authenticate, and reading and writing HeliosDB tables
through them is planned. Standard Cassandra drivers, including
the DataStax drivers and cqlsh, cannot connect yet; driver compatibility for the CQL
listener is planned. The features on this page describe the planned surface.
:::

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:

```bash
# 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 | Result | 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 | Result |
|----------|--------|---------|--------|
| 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](https://www.heliosdb.com/docs/full/reference/protocols/cassandra/configuration/)** - Connection configuration
- **[COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/cassandra/compatibility/)** - Feature compatibility
- **[EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/cassandra/examples/)** - CQL examples
- **[Parent Directory](https://www.heliosdb.com/docs/full/reference/protocols/readme/)** - Protocol overview
- **[PROTOCOL_COMPATIBILITY_MATRIX.md](https://www.heliosdb.com/docs/full/reference/protocols/protocol_compatibility_matrix/)** - Cross-protocol comparison