Schema
The semantic layer is what RDST knows about your database beyond column names and types. Filling it in improves every answer Ask gives you from then on.
What the semantic layer is
A database schema tells RDST that posts has a post_type_id column holding
integers. It does not tell RDST that 1 means a question and 2 means an
answer. That kind of knowledge lives in your team's heads, or in a wiki page
somewhere, and a model writing SQL against your data has to guess at it.
The semantic layer is where that knowledge gets written down, so RDST can read it before generating anything.
It holds descriptions of what each table is for, explanations of columns whose names do not carry their meaning, what enum values stand for, business terms specific to your company, and how tables relate to one another.
A useful way to think about it is as the notes you would leave for whoever inherits this database.
Letting RDST write it
Schema discovery profiles every table, examining column shapes, null rates, sample values, and row counts, then writes a description and some business context for each one.
You can start it from the prompt on Home, or from Discover schema in the Ask header. It runs in the background and uses read-only queries, so it is safe against a database that is serving traffic.
This gets you most of the way for tables whose purpose is inferable. It cannot
know what your company means by "churned", or that status = 3 is the state your
support team calls "escalated".
Filling in what only you know
Anything RDST inferred can be corrected, and anything it could not know can be added.
The entries worth your time are the ones a newcomer would ask about:
- Enum and status codes, with what each value means
- Columns whose names are abbreviations or legacy
- Tables that look similar but serve different purposes
- Terms your company uses in a specific way
Every improvement here applies to every future question. Ask reads the semantic layer before writing any query, so time spent on a table you query often pays back repeatedly.
Effect on Ask
The Ask header reports which mode it is in. Live introspection, no semantic layer means it is working from column names and types alone, which functions but produces more guessing and more clarifying questions.
With the semantic layer filled in, generated SQL lands on the right interpretation more often, and the questions Ask does come back with are sharper, because it knows which readings of your question are plausible against your schema.
From the command line
The same data is managed by rdst schema: rdst schema init bootstraps it from
the database, rdst schema annotate --use-llm fills in descriptions, and
rdst schema edit opens it in your editor. It is stored per target under
~/.rdst/semantic-layer/.
Ask
Ask a question about your data in plain English and get the answer back. RDST writes the SQL, checks that it is safe and valid, runs it, and shows you the rows.
Queries
The registry of every query RDST has collected. Slow Queries, Health Check, and Ask all write here automatically, and anything in the list can be analyzed or compared against a Readyset cache.