Documentos, coleções e BSON
Um documento do MongoDB é um conjunto de pares de campo e valor gravado em BSON, a codificação binária que o servidor usa no disco e na rede. O BSON acrescenta aos tipos do JSON outros como ObjectId, Date, Decimal128 e inteiros de 32 e de 64 bits, por isso o valor 100 digitado no mongosh chega ao banco como inteiro de 32 bits e o valor 8.5 como double, embora o JSON escreva os dois como número.
Ficha e sumário da página
- Referência técnica
- MongoDB Community 9.0.8
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
Campos, subdocumentos e arrays
O valor de um campo pode ser um texto, um número, uma data, outro documento, um array ou um array de documentos. Essa combinação permite guardar num registro só o que um banco relacional espalharia por várias tabelas. O documento do item paper, da coleção inventory usada nos exemplos oficiais, mostra texto, número e subdocumento lado a lado, com o tipo BSON que o mongosh grava em cada campo:
_idObjectId gerado pelo driver na inserção, chave primária do documento.item: "paper"String, o nome do item.qty: 10032-bit integer, porque 100 é inteiro e cabe em 32 bits.sizeObject, um subdocumento dentro do documento.h: 8.5Double, porque o número tem casa decimal.w: 1132-bit integer, como a quantidade.uom: "in"String, a unidade de medida, em polegadas.status: "D"String, o estado do item no estoque do exemplo.
Para chegar a um campo dentro de um subdocumento, você usa a notação de ponto. O filtro { "size.uom": "in" } encontra os itens medidos em polegadas. O mesmo ponto alcança a posição de um array, numerada a partir de zero: no documento de Alan Turing, outro exemplo da documentação, "contribs.2" aponta o terceiro elemento do array contribs. Essa notação vale em consultas, em atualizações e na definição de índices, por isso um campo aninhado recebe índice como qualquer campo da raiz.
Os nomes de campo são textos, não aceitam o caractere nulo e não se repetem dentro do mesmo documento. O servidor aceita pontos e cifrões nos nomes, com suporte ampliado desde a versão 5.0 e algumas restrições, embora esses nomes compliquem as consultas que usam a notação de ponto. O MongoDB preserva a ordem dos campos na gravação, com duas exceções: o _id ocupa o primeiro lugar em todo documento, enquanto uma atualização que renomeia campos pode mudar a ordem dos demais.
O campo _id e o ObjectId
Todo documento de uma coleção comum tem um campo _id com valor único, que funciona como chave primária. Quando o app insere um documento sem _id, o driver gera um ObjectId para o campo. O índice único em _id já existe, porque o MongoDB o cria junto com a coleção. Esse índice recusa a inserção de um segundo documento com o mesmo _id e não pode ser removido. O valor do campo também é imutável, por isso uma atualização não consegue trocar o _id de um documento já gravado.
O _id aceita qualquer tipo BSON, menos array, expressão regular e undefined. Um e-mail, um número sequencial ou um código vindo de outro sistema servem, contanto que sejam únicos na coleção. O ObjectId, usado quando o app não escolhe nada, tem 12 bytes: os quatro primeiros guardam o segundo da criação, medido desde a época Unix. Os cinco seguintes são um valor aleatório gerado uma vez por processo do cliente. Os três últimos formam um contador que começa num valor aleatório. Como o horário vem primeiro, o ObjectId carrega o momento de criação do documento, que o método getTimestamp() do mongosh devolve.
As coleções de séries temporais funcionam de outro jeito: nelas os documentos dispensam um _id único, porque o MongoDB não cria índice nesse campo.
Os tipos BSON que aparecem no dia a dia
A tabela oficial de tipos BSON tem mais de quinze tipos, cada um com um número e um apelido usado pelo operador $type. A consulta { qty: { $type: "string" } } encontra os documentos cuja quantidade foi gravada como texto, o caso de um registro que chegou de outro app com o número entre aspas. Seis tipos cobrem os campos do exemplo e os de um cadastro comum:
- StringTexto em UTF-8, como nomes, e-mails e códigos.
- 32-bit integerInteiro de 32 bits, apelido int, para contadores e quantidades.
- DoubleNúmero de ponto flutuante de 64 bits, para medidas com casas decimais.
- Decimal128Decimal de 128 bits, para valores monetários sem erro de arredondamento.
- DateInteiro de 64 bits com os milissegundos desde 1º de janeiro de 1970.
- ObjectIdIdentificador de 12 bytes, o tipo padrão do campo _id.
A diferença entre Double e Decimal128 pesa quando o documento guarda dinheiro. Um Double representa 0,1 de forma aproximada. Somados muitos valores, essa diferença se acumula até aparecer nos centavos. O Decimal128 guarda o número decimal exato, por isso entra nos documentos que registram preço, saldo ou fatura. O tipo Date também tem a precisão definida pelo formato: ele guarda milissegundos num inteiro de 64 bits, o que cobre cerca de 290 milhões de anos para trás e para a frente.
Na versão 9.0, o servidor confere por padrão todo BSON que recebe, por isso um documento malformado enviado ao mongod recebe erro em vez de ser gravado. A opção net.wireObjectCheck, que ligava essa conferência nas versões anteriores, ficou defasada.
O limite de 16 MiB por documento
Um documento BSON tem no máximo 16 mebibytes. O limite afeta pouco um cadastro de cliente, que ocupa alguns kilobytes, mas aparece quando o documento cresce sem parar: um array de comentários que recebe itens a cada visita ou um histórico de eventos gravado dentro do próprio registro chega ao teto. A partir dali, a atualização que acrescenta um item recebe erro. Nesses casos, cada comentário ou evento vira um documento próprio numa coleção separada, com o _id do registro principal num campo de referência.
Arquivos maiores que o limite, como vídeos e PDFs grandes, vão para o GridFS. A especificação divide o arquivo em partes, grava cada parte como um documento numa coleção de pedaços e guarda os metadados do arquivo em outra coleção. A ferramenta mongofiles e os drivers oficiais leem e gravam arquivos nesse formato.
Validação de esquema na coleção
Por padrão, os documentos de uma coleção não compartilham um esquema. A flexibilidade facilita a vida enquanto o app muda de formato, mas abre espaço para um campo qty gravado como texto num documento e como número em outro. A validação de esquema fecha essa porta: a coleção recebe um validador, em geral escrito com $jsonSchema. O servidor confere o validador a cada inserção e a cada atualização e recusa o documento que não passa.
Com o nível de validação constraint, acrescentado na versão 9.0, o validador vale para inserções e atualizações. A coleção nesse nível não pode conter nenhum documento fora do formato, nem os gravados antes da troca de nível. No nível strict, o validador confere cada inserção e cada atualização, mas um documento antigo que não recebe atualização pode continuar fora do formato. O moderate ainda dispensa a conferência na atualização dos documentos que já estavam fora do formato.
A forma como o servidor encontra um documento já gravado numa coleção grande é o assunto da página Consultas e índices.