Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs

Inserir operações

Neste guia, você pode aprender como inserir documentos com o driver MongoDB Java.

Você pode usar o MongoDB para recuperar, atualizar e excluir informações. Para uma dessas operações, tais informações, como perfis de usuário e pedidos, precisam existir no MongoDB. Para que elas existam, primeiro realize uma operação de inserção.

Uma operação de inserção insere um único ou vários documentos no MongoDB usando os métodos insertOne(), insertMany() e bulkWrite().

As seções a seguir focam em insertOne() e insertMany(). Para obter informações sobre como usar o método bulkWrite() , veja nosso guia de operações em massa.

Observação

O campo id_ em operações de inserção

Ao inserir um documento, o MongoDB impõe uma restrição em seus documentos por padrão: cada documento deve conter um valor _id exclusivo. Os valores _id duplicados violam restrições de índice único , resultando em um WriteError.

Há duas maneiras de gerenciar este campo:

  • Você mesmo pode gerenciar esse campo, garantindo que cada valor usado seja exclusivo.

  • Você pode permitir que o acionador gere automaticamente valores de ObjectId únicos.

A menos que você tenha fornecido garantias sólidas de exclusividade, recomendamos que deixe o driver gerar automaticamente os valores de _id.

Para obter mais informações sobre índices únicos, consulte a entrada manual sobre Índices únicos.

Use o método insertOne() quando quiser inserir um único documento.

Em uma inserção bem-sucedida, o método retorna uma instância do InsertOneResult representando o _id do novo documento.

O exemplo a seguir cria e insere um documento usando o método insertOne() :

Document doc1 = new Document("color", "red").append("qty", 5);
InsertOneResult result = collection.insertOne(doc1);
System.out.println("Inserted a document with the following id: "
+ result.getInsertedId().asObjectId().getValue());

A saída do código anterior se assemelha ao seguinte:

Inserted a document with the following id: 60930c39a982931c20ef6cd6

Para obter mais informações sobre os métodos e classes descritas nesta seção, consulte os seguintes recursos:

Use o método insertMany() quando quiser inserir vários documentos. Este método insere documentos na ordem especificada até ocorrer uma exceção, se houver.

Por exemplo, suponha que você queira inserir os seguintes documentos:

{ "_id": 3, "color": "red", "qty": 5 }
{ "_id": 4, "color": "purple", "qty": 10 }
{ "_id": 3, "color": "yellow", "qty": 3 }
{ "_id": 6, "color": "blue", "qty": 8 }

Se você tentar inserir esses documentos, um WriteError ocorrerá no terceiro documento, e os documentos anteriores ao erro serão inseridos na sua collection.

Dica

Use um bloco try-catch para obter uma confirmação de documentos processados com êxito antes que o erro ocorra:

List<Integer> insertedIds = new ArrayList<>();
// Inserts sample documents and prints their "_id" values
try {
InsertManyResult result = collection.insertMany(documents);
result.getInsertedIds().values()
.forEach(doc -> insertedIds.add(doc.asInt32().getValue()));
System.out.println("Inserted documents with the following ids: " + insertedIds);
// Prints a message if any exceptions occur during the operation and the "_id" values of inserted documents
} catch(MongoBulkWriteException exception) {
exception.getWriteResult().getInserts()
.forEach(doc -> insertedIds.add(doc.getId().asInt32().getValue()));
System.out.println("A MongoBulkWriteException occurred, but there are " +
"successfully processed documents with the following ids: " + insertedIds);
}

O resultado consiste em documentos que MongoDB pode processar e deve parecer algo assim:

A MongoBulkWriteException occurred, but there are successfully processed
documents with the following ids: [3, 4, 6]

Se você examinar sua coleção, deverá ver os seguintes documentos:

{ "_id": 3, "color": "red", "qty": 5 }
{ "_id": 4, "color": "purple", "qty": 10 }

Em uma inserção bem-sucedida, o método retorna uma instância do InsertManyResult representando o _id de cada novo documento.

O exemplo seguinte cria e adiciona dois documentos a um List e insere o List utilizando o método insertMany() :

List<Document> documents = new ArrayList<>();
Document doc1 = new Document("color", "red").append("qty", 5);
Document doc2 = new Document("color", "purple").append("qty", 10);
documents.add(doc1);
documents.add(doc2);
InsertManyResult result = collection.insertMany(documents);
// Retrieves and prints the ID values of each inserted document
List<ObjectId> insertedIds = new ArrayList<>();
result.getInsertedIds().values()
.forEach(doc -> insertedIds.add(doc.asObjectId().getValue()));
System.out.println("Inserted documents with the following ids: " + insertedIds);

A saída do código anterior se assemelha ao seguinte:

Inserted documents with the following ids: [60930c3aa982931c20ef6cd7,
60930c3aa982931c20ef6cd8]

Observação

Exemplo de configuração

Esse exemplo se conecta a uma instância do MongoDB usando um URI de conexão. Para saber mais sobre como se conectar à sua instância do MongoDB, consulte o guia Create a MongoClient. Este exemplo também utiliza a coleção do movies no banco de dados do sample_mflix incluído nos conjuntos de dados de amostra do Atlas. Você pode carregá-los em seu banco de dados na camada grátis do MongoDB Atlas seguindo a Introdução ao MongoDB.

O código a seguir é um arquivo completo e autônomo que executa uma operação de inserção e uma operação de inserção muitos:

// Inserts a sample document describing a movie by using the Java driver
package org.example;
import java.util.Arrays;
import org.bson.Document;
import org.bson.types.ObjectId;
import com.mongodb.MongoException;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.result.InsertOneResult;
import com.mongodb.client.result.InsertManyResult;
import java.util.List;
public class Insert {
public static void main(String[] args) {
// Replace the uri string with your MongoDB deployment's connection string
String uri = "<connection string uri>";
try (MongoClient mongoClient = MongoClients.create(uri)) {
MongoDatabase database = mongoClient.getDatabase("sample_mflix");
MongoCollection<Document> collection = database.getCollection("movies");
// Inserts a sample document describing a movie into the collection
InsertOneResult result = collection.insertOne(new Document()
.append("_id", new ObjectId())
.append("title", "Ski Bloopers")
.append("genres", Arrays.asList("Documentary", "Comedy")));
// Prints the ID of the inserted document
System.out.println("Inserted document id - insert one: " + result.getInsertedId());
// Creates two sample documents containing a "title" field
List<Document> movieList = Arrays.asList(
new Document().append("title", "Short Circuit 3"),
new Document().append("title", "The Lego Frozen Movie"));
// Inserts sample documents describing movies into the collection
InsertManyResult result = collection.insertMany(movieList);
// Prints the IDs of the inserted documents
System.out.println("Inserted document id - insert many: " + result.getInsertedIds());
}
}
}
insertOne() document id: BsonObjectId{value=...}
insertMany() document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}}

O driver lança uma MongoWriteException para qualquer erro de gravação que ocorra ao executar operações de gravação únicas. Um objeto MongoWriteException tem um campo error contendo o objeto WriteError que o causou.

Considere uma coleção que tenha uma regra de validação de esquema onde o valor do campo quantity deve ser um tipo int. No exemplo a seguir , o driver lançará um MongoWriteException se você tentar inserir um documento onde o valor de quantity é "three".

Exception in thread "main" com.mongodb.MongoWriteException: Document failed validation at
com.mongodb.internal.connection.ProtocolHelper.getWriteException(ProtocolHelper.java:228)
...
Caused by: com.mongodb.MongoWriteException: WriteError{code=121,
message='Document failed validation', details={ operator: "$jsonSchema",
schemaRules: { bsonType: "int", description: "must be an integer" },
offendingDocument: {"name":"Apple","quantity":"three"} } } at
com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50)

Para saber mais sobre validação de esquema, consulte Validação de esquema na seção Entradas manuais do servidor.

Para obter mais informações sobre os métodos e classes usados para inserir documentos, consulte a seguinte documentação da API:

Para obter mais informações sobre os tipos de erro discutidos na seção Solução de problemas, consulte a seguinte documentação da API: