Queries linked to tables
Each table is tied to the queries it serves. Six months from now you can still answer “why does this table exist?” and know when it is safe to drop.
For Cassandra · ScyllaDB · Astra · Cosmos DB
Design Cassandra tables by query, not by guesswork.
List your access patterns, get Chebotko diagrams with partition and clustering keys, and export CQL. Or import your existing cluster and finally see why each table exists.
Click a query to see the table that serves it.
Sound familiar?
“Nobody remembers why orders_by_customer_and_status exists, so nobody dares to drop it.”“The spreadsheet that maps queries to tables went stale six months ago.”
“We deleted a user and forgot three tables that held copies of their data.”
CQL tells you what a table looks like, never why it exists.
How it works
- 1
Write your queries
In plain words: “messages in a channel, newest first”. These are your access patterns.
- 2
byquery shapes the tables
Partition key, clustering order and a Chebotko diagram, each table tied to the query it serves.
- 3
Export CQL, or go the other way
Generate the CQL, or import an existing cluster and rebuild the queries behind it.
Every table has a reason. byquery shows it.
Chebotko diagrams, generated
Partition keys, clustering order and static columns marked on every table, plus the arrows that show how one query leads to the next. Generated from your queries, so there is nothing to draw by hand.
- K partition key
- C↑ C↓ clustering column, sort order
- S static column
Import from your cluster
Connect to a cluster or drop in your CQL files. byquery suggests what the schema can’t say: logical references like tenant_id → tenants and tables that hold copies of the same data. You confirm or dismiss each one.
Also in the box
Duplicate-data map
Delete a tenant? See the 7 tables that hold a copy of its data and need cleanup.
Partition health checks
Warnings for partitions that grow without limit, hot partitions, ALLOW FILTERING and oversized rows.
CQL and migration export
The model is plain text, so it lives in git next to the code that queries it.
Unused tables Later
Find tables no query touches anymore, from query logs.
MCP server
The agent proposes. You review it in the diagram.
byquery ships with a local MCP server, the same governed path as the Schemity MCP server. From Claude Code, Cursor or any MCP host, the agent adds a query and stages the table that serves it. byquery draws the staged table next to the ones it duplicates, and nothing reaches a cluster until you approve it.
- The agent reads queries, tables and keys. Never rows, never credentials.
- Reads change nothing. Proposals are unsaved edits, drawn in the diagram for you to approve or undo.
- Runs on
127.0.0.1only. Your schema goes where your agent host already sends your code.
How it compares
| Spreadsheet + CQL | Generic drawing tool | Enterprise modeling suite | byquery | |
|---|---|---|---|---|
| Queries linked to tables | Partly | – | By hand | ✓ |
| Cassandra key notation (K, C↑↓, S) | – | By hand | ✓ | ✓ |
| Import from a live cluster | – | – | ✓ | ✓ |
| Suggests references and duplicated data | – | – | – | ✓ |
| Stays in sync with code | – | – | Partly | ✓ |
| MCP server for AI agents | – | – | – | ✓ |
| Price | Free | Free or cheap | $$$ per seat | Free during beta |
Questions
What is a Chebotko diagram?
A diagram for Cassandra-style databases, introduced by Artem Chebotko, that shows each table with its partition key (K), clustering columns and sort order (C↑/C↓) and static columns (S), and the application queries that move from one table to the next. It answers the question an ER diagram can’t: which query is each table for?
Do my credentials or data leave my machine?
No. byquery runs on your computer. When you import from a cluster, the connection goes straight from your machine to your database. It reads the schema only, never your rows.
Which databases are supported?
Apache Cassandra 3, 4 and 5, ScyllaDB, DataStax Astra, and Azure Cosmos DB’s Cassandra API. Anything that speaks CQL should work.
Will it be paid?
Free during the beta. After that, it stays free for education, with paid plans for individuals and teams. If that changes whether you would use it, reply to any of our emails and say so.
Which AI agents work with the MCP server?
Any MCP host: Claude Code, Claude Desktop, Cursor, Codex, OpenCode and others. The server is local, so with a local model your schema never leaves your machine.
When can I use it?
The first version is being built now. Waitlist members get invites in small batches, earliest signups first, and the feature you pick on the form tells us what to build first.
Who is building it?
The makers of Schemity, a desktop database design tool for SQL databases. byquery brings the same idea to query-first databases.
Get early access
Early users shape the roadmap. We read every reply.