Module parser 

SSTable Binary Format Parser Module

This module provides parsing functionality for Apache Cassandra SSTable binary formats. It handles deserialization of binary data structures from SSTable files (Data.db, Index.db, Statistics.db, etc.) produced by Cassandra 5.0+.

Architecture Overview

This is one of four parsing subsystems in cqlite-core:

Module	Purpose
cql/	Full CQL text → AST parsing
parser/	SSTable binary format parsing (this module)
schema/cql_parser.rs	CREATE TABLE → TableSchema
query/parser.rs	Lightweight DML → ParsedQuery

See docs/architecture/parser-overview.md for the complete architecture overview.

Module Architecture

parser/ (SSTable Binary Format Parsing)
│
├── Core Binary Parsing
│   ├── vint.rs              - Variable-length integer (VInt) encoding
│   └── header.rs            - SSTable header parsing (magic numbers, version detection)
│
├── Statistics Parsing
│   ├── statistics.rs        - Statistics.db basic format
│   └── enhanced_statistics_parser.rs - Statistics.db enhanced format (nb/oa)
│
├── CQL Type Deserialization
│   ├── types.rs             - All CQL primitive types (int, text, uuid, etc.)
│   └── complex_types.rs     - Collections, UDTs, tuples, frozen types
│
└── High-Level Interface
    └── binary.rs            - SSTableParser facade

Note: Test modules (*_test.rs, *_tests.rs) and benchmarks (*_benchmarks.rs) are omitted from the diagram. See feature flag benchmarks for performance testing.

Key Distinction: parser/ vs cql/

Module	Purpose	Input	Output
parser/	SSTable binary parsing	Raw bytes from .db files	Structured Rust values
cql/	CQL text parsing	Query strings (“SELECT…”)	Abstract Syntax Trees

This module (parser/) handles binary deserialization:

• Reading bytes from SSTable files (Data.db, Statistics.db, etc.)
• Decoding VInt-encoded integers per Cassandra’s wire format
• Deserializing CQL values (int → i32, text → String, uuid → Uuid)

For CQL text parsing (CREATE TABLE, SELECT, etc.), see the crate::cql module.

Sub-module Reference

Variable-Length Integer Encoding

• vint - VInt encoding/decoding per Cassandra specification

SSTable Headers

• header - SSTable header parsing with version detection (oa/nb/legacy formats)

Statistics Files

• statistics - Statistics.db parsing for row counts, timestamps, min/max metadata
• enhanced_statistics_parser - Enhanced Statistics.db format for Cassandra 5.0’s nb (nested btree) and oa (open addressing) formats

CQL Type Deserialization

• types - All 20+ CQL primitive types: int, bigint, text, blob, uuid, timestamp, date, time, inet, varint, decimal, duration, boolean, float, double, ascii, timeuuid
• complex_types - Collections (list, set, map), UDTs, tuples, with depth tracking for nested types

High-Level Interface

• binary - SSTableParser facade providing unified access to parsing functionality

Usage Examples

use cqlite_core::parser::{parse_vint, SSTableHeader, CqlType};

// Parse variable-length integer from raw bytes
let bytes = [0x8A, 0x01]; // VInt-encoded value
let (remaining, value) = parse_vint(&bytes)?;

// Parse SSTable header to detect format version
let header = SSTableHeader::parse(&file_bytes)?;
println!("SSTable format: {:?}", header.format_type);

Backward Compatibility

The parse_cql_schema function is maintained for backward compatibility with existing code. New code should use crate::cql::parse_cql_schema_enhanced which provides better error handling and configuration options.

Related Documentation

• SSTable format specification: docs/sstables-definitive-guide/
• Known limitations: docs/sstables-definitive-guide/chapters/appendix-f-known-limitations.md

Re-exports

pub use binary::CQLiteParseError;

pub use binary::ParseResult;

pub use binary::SSTableParser;

pub use crate::error::Result as CqlResult;

pub use complex_types::*;

pub use enhanced_statistics_parser::*;

pub use header::*;

pub use statistics::*;

pub use types::*;

pub use vint::*;

Modules

binary

Binary format parsing for backward compatibility

complex_types

Complex Type Parsing for Cassandra Data Types

enhanced_statistics_parser

Enhanced Statistics.db parser for Cassandra 5.0 ‘nb’ format

header

SSTable header parsing for Cassandra 5+ ‘oa’ format

repair_metadata

Repair-state metadata decode from the Statistics.db STATS component (issue #988, epic #968).

statistics

Statistics.db parser for Cassandra 5+ SSTable format

toc_walk_metrics

Minimal process-wide counter for Statistics.db Table-of-Contents (TOC) walks (issue #1658, epic #1606).

types

CQL type system parsing and serialization

vint

Variable-length integer encoding/decoding for Cassandra SSTable format

Functions

parse_cql_schemaDeprecated

Parse CQL CREATE TABLE statement (backward compatibility function)