Introdução
Um guia passo a passo para levar um banco do seu schema real ao dado corrigido: faça engenharia reversa das coleções, trabalhe o diagrama ER editável, rode a auditoria com um health score, transforme os dados por uma escada de segurança e, no fim, gere a DDL ou aplique as mudanças de volta ao MongoDB.
Como ler este manual
Cada passo tem:
- Faça — a ação exata (clicar, digitar, rodar tal comando).
- Veja — o que deve acontecer na tela. Esse é o seu “passou / falhou”.
- Por quê — contexto adicional, só quando ajuda (pule se estiver com pressa).
Antes de começar
Conceito
O que é o Data Modeling
O Data Modeling faz engenharia reversa das suas coleções ao vivo em um diagrama ER editável, audita-o em busca de anti-padrões com um health score, e deixa você corrigir tanto o modelo quanto os dados — depois gerar a DDL ou aplicar as mudanças de volta ao banco.
Atenção
Quando uma conexão é necessária
Uma conexão ativa é exigida para Generate o modelo e para escrever no banco (correções da auditoria, transformações, Apply to DB). Todo o resto — editar o canvas, auditar, gerar DDL, import/export — funciona offline.
Você vai precisar de:
- 1Um deployment MongoDB conectado com pelo menos um banco que tenha dados para amostrar.
- 2Abrir a tela pelo card Home → Data Modeling, ou pelo menu Tools ▸ Schema & Data ▸ Data Modeling.
- 3Idealmente um banco de teste — a Etapa 4 pode escrever nos seus dados, então pratique onde um erro é inofensivo.
Tempo estimado para o walkthrough completo: ~25 minutos.
Gerar o modelo
Faça engenharia reversa de um banco ao vivo em um diagrama ER e congele-o como a baseline “Observado”.
Abra o Data Modeling
Com uma conexão ativa, abra a tela pelo card Home → Data Modeling, ou pelo menu Tools ▸ Schema & Data ▸ Data Modeling.
O canvas do Data Modeling abre, com um seletor de database na barra e um botão Generate.
Escolha o(s) database(s)
No seletor da barra, escolha o database a modelar — ou escolha vários para construir um modelo cross-DB.
O(s) database(s) escolhido(s) ficam selecionados, prontos para gerar.
Selecionar vários databases permite que a inferência encontre relações que cruzam os limites de banco, não só dentro de um DB.
Clique em Generate
Clique Generate para fazer a engenharia reversa do modelo a partir da conexão.
Uma barra de progresso percorre as etapas LISTING → SAMPLING → ANALYZING → INFERRING → DONE. Você pode Cancelar a qualquer momento.
Ele amostra cada coleção, infere campos e tipos, lê índices e validadores existentes, e infere relações a partir dos dados amostrados.
Leia as relações inferidas
As relações são inferidas de dois jeitos: por FK — campos como *_id / *Id / *Ref que casam com o _id de outra coleção e são confirmados contra os dados — e por campo compartilhado — o mesmo nome de identificador aparecendo entre coleções.
Conceito
Inferência, não mágica. A ferramenta só propõe uma relação quando o padrão do nome do campo e os valores amostrados batem com um _id de destino. Você pode editar ou apagar qualquer relação depois.
Inspecione o diagrama ER
O diagrama ER aparece: coleções como cards, campos com badges (PK/FK/UK/NN/ENUM/CK), e relações como linhas — azul = FK, âmbar = campo compartilhado, tracejada = inferida.
Note a baseline Observado
Esse estado gerado vira a baseline congelada “Observado” com a qual o Diff da Etapa 5 compara.
Tudo que você editar daqui em diante é medido como um delta contra esse snapshot — é assim que renames e adições são rastreados com precisão.
Editar o canvas
Organize, inspecione e molde o modelo — coleções, campos, validação e relações — tudo offline e com desfazer.
Mover, organizar, zoom e pan
Arraste os cards para movê-los (Ctrl/Cmd-clique para multi-seleção); clique ✦ Arrange para reempacotar o layout; use −/+/%/Fit para zoom; segure Alt+arrasto ou use o botão do meio para dar pan.
Os cards se reposicionam, o layout reempacota no Arrange, e a viewport dá zoom e pan suavemente.
Inspecione uma coleção
Duplo-clique num card de coleção para abrir o inspetor.
O inspetor abre mostrando os campos e índices daquela coleção.
Edite os campos
Use + Add field, renomeie (Enter), troque o tipo ou remova (×). Por campo, defina a Validação (required / enum / checks).
Novos campos aparecem; a validação produz os badges NN (required), ENUM e CK (check) no campo.
Adicione uma coleção
Clique + Add collection e informe o namespace como db.coleção. Renomeie coleções do mesmo jeito.
Um novo card de coleção aparece no canvas com o namespace que você digitou (por exemplo db.orders).
Crie e edite relações
Arraste do dot (○) de um campo até outra coleção para criar uma relação. Duplo-clique na linha edita lados/cardinalidade/nota; duplo-clique na seta inverte a direção; arraste um waypoint para curvar a linha; pressione ×/Delete para remover.
Uma linha de relação é desenhada entre os campos, e a edição se reflete nos lados, cardinalidade e forma dela.
Desfaça e refaça
Use Undo/Redo (↶ ↷) para andar para trás e para frente nas suas edições.
O canvas reverte ou reaplica cada edição em ordem.
Conceito
Tudo offline. Editar o canvas nunca toca no banco — só muda o modelo em memória até você aplicar explicitamente uma correção, transformação ou DDL.
Auditar + correção de 1 clique
Pontue o modelo, leia os verdicts por severidade, e aplique correções não destrutivas no modelo, no banco ou em ambos.
Rode a auditoria
Clique ✓ Auditar para abrir o painel de auditoria.
Um health score (A–E) aparece, mais os verdicts por severidade: 🔴 err / 🟡 warn / ℹ️ info. Filtros deixam mostrar todos / erros / avisos / info.
Leia os anti-padrões
Os anti-padrões detectados incluem: array sem limite, documento inchado (campos demais), campo de tipo misto, data como string, FK sem índice, coleção sem validação, e sem `_id`. Cada verdict diz o que foi detectado, por quê importa, e a boa prática.
Aplique uma correção de 1 clique
Num verdict corrigível, use a correção de 1 clique — por exemplo criar índice (para uma FK sem índice) ou aplicar validação ($jsonSchema). Escolha o alvo Modelo / Banco / Ambos e clique Aplicar.
A correção é aplicada de forma não destrutiva. Se o alvo incluir Banco ou Ambos, a escrita entra no changeset.
Essas correções são aditivas — criam um índice ou anexam um validador $jsonSchema; nunca apagam dados nem reescrevem documentos.
Envie um verdict para Transformar
Verdicts com a tag → Transformar (por exemplo data-como-string ou tipo-misto) abrem a escada de transformação coberta na Etapa 4.
Clicar na tag leva o verdict para o fluxo de transformação, já apontado para o campo ou coleção problemático.
Transformar dados (escada de segurança)
Esta etapa corrige os dados, não só o modelo. Toda escrita sobe uma escada de segurança de quatro degraus antes de tocar um único documento.
Faça o Preview da mudança
Abra a escada a partir de um verdict de auditoria, de um diff do modelo, de um pipeline customizado ou de um inline de referência. Comece pelo Preview.
O Preview mostra antes / depois dos primeiros documentos afetados — e não escreve nada.
Dry-run para as contagens
Rode o Dry-run para medir o impacto.
O Dry-run reporta afetados / total / bytes, e marca o job como “grande” quando passa de 250k docs ou 1 GB.
Atenção
O Dry-run não escreve
Tanto o Preview quanto o Dry-run são somente leitura. Eles calculam contagens e amostras sem modificar nenhum documento — nada é escrito até você chegar ao Apply.
Faça um Backup
Faça um Backup (opcional, mas forçado se o job for grande) — uma cópia com timestamp via $out.
Uma coleção de backup com timestamp é criada para você restaurar se a transformação der errado.
Aplique a transformação
Digite o nome da coleção para liberar o Apply. Depois Aplicar pipeline in-place (idempotente, via $merge) — ou executar em segundo plano como Tarefa para coleções grandes.
Os documentos são transformados. Cada escrita vira um AppliedChange registrado com o comando mongosh equivalente.
A escrita via $merge é idempotente — rodar a mesma transformação de novo converge para o mesmo resultado em vez de aplicar em dobro.
Use as variações
Experimente as variações: um pipeline customizado (cole seu próprio aggregation mais um destino — in-place ou nova coleção) e o inline (colapse uma coleção referenciada no pai via $lookup, com opção de remover o campo FK).
As duas variações rodam pela mesma escada de quatro degraus — Preview → Dry-run → Backup → Apply.
Diff Observado × Alvo
Compare o modelo editado contra a baseline Observado congelada e transforme um delta em uma transformação.
Abra o diff
Clique ⇆ Diff (habilita assim que houver mudanças) para listar o delta desde o “Observado”.
O diff lista coleções, campos, índices e validação adicionados / removidos / alterados como +N −M ~L.
Confirme os renames reconhecidos
Os renames são reconhecidos pelo log de edição — então um campo renomeado aparece como rename (não como remoção + adição), e os dados são preservados na transformação.
Gere uma transformação a partir de um delta
A partir de um item do delta, gere uma transformação customizada e aplique ao banco pela escada.
O construtor de transformação abre pré-preenchido a partir do delta, pronto para rodar via Preview → Dry-run → Backup → Apply.
DDL e aplicar ao banco
Gere um script mongosh para recriar o modelo, ou crie as coleções que faltam diretamente — sem sobrescrever o que já existe.
Gere o script de DDL
Escolha File ▸ DDL (mongosh) para gerar um script que recria o modelo.
O script contém createCollection com $jsonSchema, os índices, e índices de FK para cada relação (com uma opção “incluir FK inferidas”), gerado por database.
Copie ou baixe o script
Use Copiar ou Baixar para salvar a DDL gerada.
O script mongosh completo fica na sua área de transferência ou na pasta de Downloads, pronto para rodar.
Apply to DB
Clique Apply to DB para criar as coleções (com validator + índices) que ainda não existem.
As coleções que faltam são criadas; as existentes não são sobrescritas. Cada criação entra no changeset.
Atenção
O Apply to DB é somente aditivo. Ele nunca sobrescreve nem altera uma coleção que já existe — só preenche o que está faltando.
Importar/Exportar e histórico
Salve e carregue o modelo, exporte um relatório legível, e revise toda escrita feita no banco nesta sessão.
Abra e salve o modelo
Use File ▸ Open / Save para carregar ou guardar o modelo em JSON.
O modelo é escrito em / lido de um arquivo JSON, então você pode versioná-lo ou compartilhá-lo.
Exporte um relatório
Use Export HTML/PDF para produzir um relatório legível do modelo.
Um documento HTML ou PDF é gerado para compartilhar ou arquivar.
Revise o histórico de mudanças
Abra File ▸ Changes para revisar o log da sessão de toda escrita no banco.
Cada entrada registra timestamp · tipo · namespace · comando mongosh — a trilha de auditoria de tudo que esta sessão escreveu no banco.
Conceito
Esse é o seu comprovante. Toda correção de auditoria, transformação e criação via Apply to DB aparece aqui com o comando mongosh exato que rodou.
Limpeza (quando terminar)
Seja honesto sobre o que tocou no banco. Editar, auditar, gerar DDL e import/export são todos offline e seguros — nunca escrevem. As únicas escritas no banco são as correções da auditoria, transformações e criações via Apply to DB que você rodou explicitamente.
Abra File ▸ Changes para ver a lista completa de escritas feitas nesta sessão.
Toda escrita registrada corresponde a uma correção, transformação ou apply de DDL que você disparou de propósito.
Atenção
Se você aplicou uma transformação em dados de teste, apague ou restaure as coleções afetadas conforme necessário — os backups feitos na Etapa 4 são cópias com timestamp das quais você pode restaurar.
Resumo do que você validou
| Etapa | Recurso |
|---|---|
| 1 | Gerar o modelo ER de um banco ao vivo e congelar a baseline Observado |
| 2 | Editar o canvas — organizar, campos, badges de validação, coleções e relações |
| 3 | Auditar com um health score e aplicar correções de 1 clique não destrutivas |
| 4 | Transformar dados pela escada de segurança Preview → Dry-run → Backup → Apply |
| 5 | Diff Observado × Alvo e gerar uma transformação a partir de um delta |
| 6 | Gerar DDL (mongosh) e Apply to DB sem sobrescrever coleções existentes |
| 7 | Importar/Exportar o modelo e revisar o histórico completo de mudanças |