cqlz family
cql-ai
CQL HPC
Type safety is not enough when your tables hold billions of rows. cql-ai reads your .cql files in CI and warns when a statement is likely to be a performance bottleneck on your data: large partitions, scatter-gather, tombstones, write amplification. Trained on measured latencies, not on rules.
A warning before it hurts production
$ cql-ai check queries/ --schema schema/
warning: AI predicts a large result bottleneck (100% confidence, about 40x the cost of a point read) on line 1
--> queries/events.cql:1:1
|
1 | SELECT * FROM events WHERE part = ?
|
= help: cost is dominated by the number of rows/bytes returned: add a LIMIT, page, or project fewer columns
= note: data shape: 200 partitions x 10k rows per partition
warning: AI predicts a server scan bottleneck (100% confidence, about 22x the cost of a point read) on line 3
--> queries/events.cql:3:1
|
3 | SELECT count(*) FROM events WHERE part = ?A four-statement file checks in about 0.2 s wall clock, including process start. The same query is a problem on a 10,000-row partition and fine on a 10-row one, so you tell the model about your data with one comment above the table:
-- hpc: partitions=200000 rows=10000 row_bytes=300
CREATE TABLE events (part text, clust text, data text, PRIMARY KEY ((part), clust));Measured bottlenecks
| Label | Measured definition (relative to a baseline on the same table) |
|---|---|
LargeResult | read ≥ 3× a point read, returns ≥ 100 rows or 32 KiB, and LIMIT 1 removes most of the cost |
ServerScan | read ≥ 3× a point read but returns almost nothing (count, filtering) |
FanOut | read ≥ 3× a point read touching many partitions (IN, token scans, indexes) |
TombstoneScan | ≥ 2× slower than the same statement on a clean twin table (queue pattern) |
WriteCost | write ≥ 1.8× a plain insert (batches across partitions) |
LightweightTxn | IF NOT EXISTS and friends pay a Paxos round trip |
Plus a cost estimate: how many times a point read (or a plain insert) the statement is expected to cost. Labels come from running every training statement on a real database, with counterfactuals such as the same statement with LIMIT 1 and on a clean twin table.
Better than rules, and data shape is the difference
Model trained on ScyllaDB measurements only (1,597 statements). Macro-F1 over the labels present, on data the model never saw.
| Test set | Statements | Macro-F1 | Cost error (log10) | Rank correlation |
|---|---|---|---|---|
| unseen worlds | 631 | 0.855 | 0.135 | 0.920 |
| unseen workload families (YCSB, KillrVideo comments) | 756 | 0.889 | 0.136 | 0.891 |
| other engine (Cassandra 5.0) | 2,614 | 0.802 | 0.179 | 0.848 |
A cost error of 0.135 means the predicted slowdown is typically within a factor of 1.4 of the measured one. The weak spots are WriteCost (precision 0.5–0.6) and TombstoneScan on the other engine (precision 0.48).
Public workloads, measured
| Workload shape | Source |
|---|---|
| key-value, tabular, IoT time series | NoSQLBench baselines (Apache-2.0) |
| blog posts, counters | cassandra-stress profiles from Apache Cassandra |
| user table | YCSB core workloads |
cpu time series | TSBS layout |
| comments | KillrVideo |
90 worlds per engine, from 10 to 400,000 partitions and from 1 to 60,000 rows per partition, plus tombstone-heavy and indexed variants: about 2,650 measured statements each on ScyllaDB and Cassandra 5.0. Published as cql-hpc-bench.
cqlc check, which is exact and about 400× faster for the anti-patterns it knows; it answers a different question: how slow will this be on my data?