Catalog organization
Layers, prefixes, and naming that keep the workspace navigable.
- Set a layering convention
- Name tables predictably
- Keep your catalog browsable as you grow
The Catalog is the list of everything that exists in your workspace: the tables, the columns, the descriptions. With five tables, any arrangement works. With five hundred, the difference between a catalog that is browsed and a deposit where no one finds anything lies in three simple decisions: how to separate the layers, how to name things and how to describe them. It's worth combining this early, because then each new table inherits (or breaks) convention.
A layering convention
The layering convention is criteria of each company. There is no fixed rule: the What matters is having one and keeping it visible in the Catalog, to beat the eye and know what stage a table is at.
Nekt's suggestion is the medallion architecture: Bronze (fountain mirror), Silver (clean and typed) and Gold (combining sources, with rule business). But adapt to your case. In agencies, by For example, it is common to use one layer per customer, for maintain the isolation of each person's data.
At the end of the day, the layer itself is less relevant than good table names, with clear prefixes and a good taxonomy. A perfect layer full of poorly named tables remains a labyrinth. Choose a layer convention, stick with it, and invest energy in names.
There are two ways to make the layer visible, and you choose one and maintains:
-
By schema: each layer is a separate schema
(
bronze.pedidos,silver.pedidos,gold.faturamento). The separation becomes structural, the The catalog already groups by schema, and it is difficult to mix it up accidentally. -
By prefix: the layer becomes a prefix in the name of the
table (
bronze_pedidos,silver_pedidos,gold_faturamento). Useful when everything lives in a single schema, and keeps layers of the same entity side by side in the list ordered.
Both work. What doesn't work is mixing: half per schema, half by prefix, and no one knows where to look. Choose one and treat as a workspace rule.
The name pattern per layer looks like this, either as a prefix or as scheme:
| Layer | Prefix/Schema | Table example |
|---|---|---|
| Bronze | bronze_ or bronze. |
bronze_hubspot_deals |
| Silver | silver_ or silver. |
silver_clientes |
| Gold | gold_ or gold. |
gold_cliente_canal_mensal |
Predictable naming
A good table name is one that the person (or agent) can guess before looking. This comes from a few rules, always applied:
-
snake_case always: all tiny, words
separated by underscore. No camelCase, no space, no accent.
cliente_canal_mensal, neverClienteCanalorcliente canal. -
Consistency of singular and plural: choose one
pattern and follow. If entity tables are plural
(
pedidos,clientes), do not appear withprodutoin the singular in the middle. Inconsistency forces person to remember, and no one remembers. -
entity_grain pattern: let the name tell about the
what the table talks about and at what granularity.
pedidos_diariois one order per day,cliente_canal_mensalis one line per customer, channel and month. The grain in the name avoids the question "is this table aggregated by what?" -
No cryptic names or personal abbreviations:
tbl1,base_v2anddados_finalthey don't say anything to those who arrive later (and "final" is never final). Abbreviation that only makes sense in your head It's a debt for the entire team.
| Table | Read as |
|---|---|
bronze_hubspot_deals |
gross, HubSpot deals |
silver_clientes |
treaty, client entity |
gold_cliente_canal_mensal |
consumption, grain client/channel/month |
Descriptions and Semantic Layer
A good name takes the person to the right table. A description This is what explains what it really contains: what is a row, what does that value column include, where does the data come from? came. At Nekt, these descriptions are not just documentation. They feed the Semantic Layer, which is the context that the AI reads through the MCP to understand your data.
The consequence is direct: a well-described table is better consumed
by agents. When someone asks "how much do we make per channel", the
agent who sees a column
faturamento_liquido described as "revenue without shipping and
no canceled orders" answers correctly. What you only see
valor no description kicks. Describing table and column is the
work that separates data that the AI uses from data that the AI ignores.
Describe the table the moment you create it, no later. That's when you have the context fresh in your head: what is a row, why that column exists, which rule applied. "Document then" becomes "never document", and then the knowledge remains only in your memory, out of reach of the team and the AI.
How does this scale
Convention looks like bureaucracy when the catalog is small. The value appears when he grows up. A catalog without convention becomes a deposit: names that no one understands, mixed layers, duplicate tables because the person didn't find what already existed. Each new question begins with archaeology.
With convention, the opposite happens. Anyone who arrives knows that
gold_ is given ready for consumption, the grain is in the
name, the description explains the rest. And the AI agent, which reads the
catalog through MCP, finds what you need without you having to explain. O
catalog becomes a map, not an attic.
An agency with 15 clients connected Meta Ads, Google Ads and CRM
of each: more than 40 sources in the same workspace. Without convention,
became a list of 200 tables with loose names, and finding "the expense
client X's media platform" was a gold mine. Adopted layer prefix
plus the entity_grain pattern: gold_midia_cliente_dia,
silver_crm_leads. Suddenly, the same name applies to
the 15 customers, a new person finds the table on their first guess,
and the agent putting together the report finds the right source on his own. A
The convention didn't make the catalog smaller, it made it navigable.