Records e Metadados: dados estruturados no Sutram
Introdução
Nem todo conhecimento é um arquivo. Muitas vezes o que importa é um registro estruturado: um documento com campos previsíveis — título, autor, data, categoria, número — que você quer criar de forma consistente, numerar automaticamente e filtrar depois.
Os Records do Sutram são exatamente isso: entradas tipadas, com metadados validados e um identificador (slug) gerado automaticamente, em vez de pastas soltas com nomes livres. É a diferença entre "uma pasta chamada Contrato ACME final v2 (2).pdf" e um registro CTR-2026-014 com autor, data e status preenchidos e conferidos.
Quando usar Records em vez de arquivos soltos
Use Records quando o conteúdo:
- Tem campos que se repetem e você quer preencher sempre da mesma forma (contratos, laudos, especificações, posts)
- Precisa de numeração ou identificação automática e sem colisão
- Vai ser filtrado e buscado por esses campos (por autor, categoria, ano…)
- Deve seguir um padrão entre pessoas e ao longo do tempo
Para material que não tem estrutura fixa — um anexo avulso, uma imagem, um rascunho — a pasta comum na aba Conteúdo já basta.
Requisito de plano: Records são um recurso dos planos pagos (a partir do Pro). As ferramentas de leitura de schema estão disponíveis em todos os planos; criar categorias e definições de metadados requer o recurso habilitado.
Conceitos Principais
O sistema de Records tem três camadas, da mais genérica para a mais concreta:
1. Definições de metadados (os campos)
Uma definição de metadados é um campo reutilizável, com um tipo. Ela descreve o que um dado significa e quais valores aceita:
| Tipo | Para quê | Exemplo |
|---|---|---|
| text | Texto livre | título, autor |
| enum | Lista fechada de valores permitidos | categoria (post, docs), status (rascunho, aprovado) |
| boolean | Verdadeiro/falso | confidencial |
| date | Data | publicado_em |
| computed | Valor derivado automaticamente (ex.: número sequencial) | número do documento |
As definições são criadas uma vez e reutilizadas por várias categorias.
2. Categorias de registro (o molde)
Uma categoria de registro é o molde que diz quais campos um registro daquele tipo usa, quais são obrigatórios, em que ordem, e como o slug é composto. Por exemplo, uma categoria "Documentação" pode exigir título, categoria e resumo, e opcionalmente publicado_em.
3. Records (a entrada)
Um Record é uma entrada concreta criada a partir de uma categoria: uma pasta com metadados validados contra o molde e um slug gerado automaticamente. Como os campos são conferidos na criação, todo registro da mesma categoria fica uniforme.
Geração de Slug
O slug é o nome/identificador do registro, montado automaticamente em duas etapas:
- Base numérica — definida pelas entradas
computed_fromde um campo computado. Ela determina quais valores formam a chave de unicidade para a numeração sequencial (ex.: idioma + área →PT-0100). - Composição do slug — definida pelas entradas
slug_fromda categoria. Ela define quais campos (incluindo a base numérica) compõem o slug final.
Assim, dois registros que compartilham a mesma base numérica recebem números sequenciais distintos (PT-0100-SWA-001, PT-0100-PPC-002), enquanto bases diferentes numeram de forma independente. O resultado é uma identificação previsível e sem colisão, sem ninguém precisar controlar contadores à mão.
Records e a Wiki
Records não vivem isolados: cada Record pode ter um nó-espelho na Wiki, que traz seu texto integral para a busca e o conecta ao grafo de conhecimento por menções [[slug]]. Ou seja, o dado estruturado que você organiza como Record também se torna conhecimento navegável. Veja Wiki e Grafo de Conhecimento.
Papéis e Permissões
| Ação | Proprietário / Admin | Membro | Visualizador |
|---|---|---|---|
| Ler categorias, metadados e registros | Sim | Sim | Sim |
| Criar, editar e excluir registros | Sim | Sim | Não |
| Definir/editar categorias e definições de metadados | Sim | Não | Não |
Criar e editar registros está aberto a proprietário, administrador e membro. Já a configuração do schema (categorias e definições de metadados) é restrita a proprietário e administrador. Visualizadores podem apenas ler.
Boas Práticas
- Defina o schema antes de criar em massa — acertar os campos e o slug primeiro evita retrabalho depois.
- Prefira enum a texto livre onde os valores são conhecidos — garante consistência e permite filtrar sem erros de digitação.
- Use campos computados para numeração — deixe o Sutram cuidar da sequência em vez de numerar manualmente.
- Pense no slug como endereço — campos estáveis no
slug_fromproduzem identificadores duráveis.
Perguntas Frequentes
P: Qual a diferença entre um Record e uma pasta comum?
R: Uma pasta comum tem só um nome livre. Um Record é criado a partir de uma categoria, com metadados validados e um slug automático — então todos os registros do mesmo tipo ficam uniformes e identificáveis.
P: Preciso de programação para usar Records?
R: Não. Você define categorias e metadados e cria registros pela interface do Sutram. As mesmas operações também estão disponíveis via o MCP Server, para automação com IA.
P: Posso mudar o schema depois de já ter registros?
R: Sim, categorias e definições de metadados podem evoluir. Mudar campos que compõem o slug pode recalcular o identificador de novos registros — planeje os campos de slug com cuidado.
P: Quem pode criar registros?
R: Proprietário, administrador e membro criam e editam registros. Apenas proprietário e administrador definem categorias e metadados. Visualizadores só leem.
Versão do Documento: 1.0 Última Atualização: Julho de 2026 Autor: Equipe de Desenvolvimento Sutram