Organização do catálogo

O Catálogo é a lista de tudo que existe no seu workspace: as tabelas, as colunas, as descrições. Com cinco tabelas, qualquer arrumação funciona. Com quinhentas, a diferença entre um catálogo que se navega e um depósito onde ninguém acha nada está em três decisões simples: como separar as camadas, como nomear as coisas e como descrevê-las. Vale combinar isso cedo, porque depois cada tabela nova herda (ou quebra) a convenção.

Uma convenção de camadas

A convenção de camadas fica a critério de cada empresa. Não existe regra fixa: o que importa é ter uma e mantê-la visível no Catálogo, para bater o olho e saber em que estágio uma tabela está.

A sugestão da Nekt é a arquitetura medallion: Bronze (espelho da fonte), Silver (limpo e tipado) e Gold (juntando fontes, com regra de negócio). Mas adapte ao seu caso. Em agências, por exemplo, é comum usar uma camada por cliente, para manter o isolamento dos dados de cada um.

Há duas formas de tornar a camada visível, e você escolhe uma e mantém:

• Por schema: cada camada é um schema separado (bronze.pedidos, silver.pedidos, gold.faturamento). A separação fica estrutural, o Catálogo já agrupa por schema, e fica difícil misturar sem querer.
• Por prefixo: a camada vira um prefixo no nome da tabela (bronze_pedidos, silver_pedidos, gold_faturamento). Útil quando tudo vive num schema só, e mantém as camadas de uma mesma entidade lado a lado na lista ordenada.

As duas funcionam. O que não funciona é misturar: metade por schema, metade por prefixo, e ninguém sabe onde procurar. Escolha uma e trate como regra do workspace.

O padrão de nome por camada fica assim, seja como prefixo ou como schema:

Naming previsível

Um bom nome de tabela é aquele que a pessoa (ou o agente) consegue adivinhar antes de procurar. Isso vem de poucas regras, aplicadas sempre:

• snake_case sempre: tudo minúsculo, palavras separadas por underscore. Sem camelCase, sem espaço, sem acento. cliente_canal_mensal, nunca ClienteCanal ou cliente canal.
• Consistência de singular e plural: escolha um padrão e siga. Se as tabelas de entidade são no plural (pedidos, clientes), não apareça com produto no singular no meio. A inconsistência força a pessoa a lembrar, e ninguém lembra.
• Padrão entidade_grão: deixe o nome dizer sobre o que a tabela fala e em qual granularidade. pedidos_diario é um pedido por dia, cliente_canal_mensal é uma linha por cliente, canal e mês. O grão no nome evita a pergunta "essa tabela está agregada por quê?".
• Sem nomes crípticos nem abreviações pessoais: tbl1, base_v2 e dados_final não dizem nada a quem chega depois (e "final" nunca é final). Abreviação que só faz sentido na sua cabeça é dívida para o time inteiro.

Descrições e Camada Semântica

Nome bom leva a pessoa até a tabela certa. A descrição é o que explica o que ela realmente contém: o que é uma linha, o que aquela coluna de valor inclui, de onde o dado veio. Na Nekt, essas descrições não são só documentação parada. Elas alimentam a Camada Semântica, que é o contexto que a IA lê pelo MCP para entender o seu dado.

A consequência é direta: uma tabela bem descrita é consumida melhor por agentes. Quando alguém pergunta "quanto faturamos por canal", o agente que enxerga uma coluna faturamento_liquido descrita como "receita sem frete e sem pedidos cancelados" responde certo. O que enxerga só valor sem descrição chuta. Descrever tabela e coluna é o trabalho que separa um dado que a IA usa de um dado que a IA ignora.

Como isso escala

A convenção parece burocracia quando o catálogo é pequeno. O valor aparece quando ele cresce. Um catálogo sem convenção vira um depósito: nomes que ninguém entende, camadas misturadas, tabelas duplicadas porque a pessoa não achou a que já existia. Cada nova pergunta começa com uma arqueologia.

Com convenção, o oposto acontece. Qualquer pessoa que chega sabe que gold_ é dado pronto para consumo, que o grão está no nome, que a descrição explica o resto. E o agente de IA, que lê o catálogo pelo MCP, encontra o que precisa sem você ter que explicar. O catálogo vira um mapa, não um sótão.