Maintain the data dictionary

Who can do this

Any member can read descriptions in the Columns tab and on the Data Dictionary page. Editing a table’s name or description in the app requires an Admin. Column descriptions are written by asking Ronja, from the Ronja CLI, or over the API — and anyone with the User role can write them on their own draft of a table. Tables viewed from another feature and committed historical versions are always read-only.

Ronja’s answers are only as good as her understanding of your tables. Two things build that understanding: what a table means, and what each of its columns means. Both are written once and read everywhere — in the app, in chat, and by search.

Describe your tables

Descriptions are the plainest way to say what a table means. Ronja drafts many of them herself — those are labeled “AI-generated · click to edit”, and correcting them is exactly the point. Descriptions matter at the feature level too: a feature’s description is “used by the agent when choosing which feature to use.”

1. Open the table from its feature page.
2. Click the description under the table title (placeholder Add a description…).
3. Type what the table actually contains and save.

Once you’ve written one, it’s yours: Ronja won’t regenerate over it on a later build, and she can’t be talked into overwriting it either — ask her in a chat to change it and she’ll say it was written by a person, and point you back here. Descriptions Ronja wrote herself she’ll happily reword on request.

Clearing your description lifts that protection, but on most tables it does not hand the job back. Ronja writes a table’s description once and doesn’t return to it on her own, so a cleared description stays empty until someone writes a new one — you, here, or Ronja if you ask her in a chat. The exception is an Integration table, where she re-describes the table whenever its columns change: there, clearing it really does hand it back.

Describe your columns

A column description is one sentence saying what the values mean. It earns its keep most on a code or a status column, where no statistic can tell anyone that status of 2 means won — and it is the only place that fact can live.

There is no column editor in the app: the Columns tab and the Data Dictionary show column descriptions but do not take them. There are three ways to write one.

• Ask Ronja. In any chat, tell her what a column means — “on orders, status is 1 quoted, 2 won, 3 lost” — and she writes it as she creates or updates the table. In a shared feature that takes the Admin role; in a private feature its owner can do it. She never replaces a description a person wrote: she reports that column back and documents the rest.
• From the Ronja CLI. Keep the prose in the same folder as the SQL, in version control, and push it with the rest.
• Over the API — see the API reference for how to reach it.

Two rules apply wherever you write from.

Your data decides which columns exist. A description attaches to a column the table has actually measured. Describing a name your data does not have is not an error and does not invent a column: Ronja keeps what you wrote and attaches it by itself the moment a build produces a column with that name. Every write tells you which names landed and which are waiting — which is what makes it safe to keep a file of descriptions in version control next to data that is rebuilt nightly or renamed in staging.

Descriptions land after a build, not before. A table that has never been built has measured nothing, so document a table once it holds data. Descriptions written before then are kept, not lost — they simply attach on the first build.

Documenting a table you don’t own

You do not need to be an Admin to describe the columns of a shared table. Edits to a shared table go through your own draft, and column descriptions are one of the things a draft may carry. The admin who reviews it sees them: the review shows a COLUMN DOCUMENTATION section with each column’s wording before and after, and flags the case where your change would hand a column Ronja wrote back to her automatic describer, or claim one of hers as person-written.

Caution

Adding or changing a column description on a draft you have already submitted withdraws the submission. Submit it again once the wording is final.

Read the columns

The Columns tab is the per-table column view. For every column it shows Field · Type · Rows · Missing · Cardinality · Examples, with the column’s description on a second line under its name — a fast way to spot gaps, check what a column really contains, and see what still needs describing.

The Type badge uses a short, plain-language label such as Text, Number, or Yes / no. Hover over it, focus it with the keyboard, or tap it to read an explanation and the underlying technical type.

A column Ronja has flagged as personal data carries a PII badge and shows no example values. That is deliberate: sample values are the part of a catalog most likely to put a real name or account number in front of someone who only wanted the schema. The counts beside it are still shown.

1. Open a table and switch to the Columns tab. The feature page’s Data Explorer uses the same tab name.
2. Flip the toggle for system columns if you need them — they’re hidden by default.

Per-column statistics at a glance.

Browse the feature’s Data Dictionary

Every feature has a Data Dictionary page at /features/<feature ID>/data-dictionary. It has two tabs:

• Columns — every column of every table in the feature on one page, with its description under its name and the same statistics the column view shows: Column · Table · Kind · Rows · Missing · Cardinality · Examples, and the same PII badge and withheld examples as the column view. The table name links straight to the table. A column appears here once its table has been built.
• File facts — the facts Ronja extracted from the feature’s documents, grouped by source and property. A different question, and the only page that answers it.

The search box and the All / Text / Numeric filter apply to whichever tab you are on. On Columns, search matches the column’s name, its table’s name and its description, so you can look for a column by what it means rather than by what it is called. Text and Numeric narrow to those column types; a date or a structured column matches only All.

On a very wide feature the page shows the first columns and says so — open a table for the rest.

Link a dictionary table

If your team already maintains definitions in a table of their own — a glossary, a field register exported from another system — you can point Ronja at it, so she reads your definitions when she works with the tables it covers:

1. Open the table that holds your definitions.
2. Open the … menu and click Mark as data dictionary.
3. Open the … menu again and click Linked tables….
4. Pick each data table with Select a table…, then click Done.

This tells Ronja where to look; it does not copy anything. The linked tables’ own column descriptions are unchanged, and the Columns tab and Data Dictionary keep showing what was written there. Use it alongside column descriptions, not instead of them.

Why it pays off

Descriptions are part of how Ronja finds things. A described column is findable by what it means as well as by its name, so “which table holds the customer’s payment terms” reaches a column called pmt_terms_cd once somebody has said what it is. The more your tables explain themselves, the less she has to guess.

For the things a dictionary can’t hold — procedures, terminology, definitions — use notes; for a rule that should hold in every conversation, use a policy. How Ronja learns explains how the surfaces fit together.