Insira documentos

Visão geral

Neste guia, você pode aprender como inserir documentos em uma coleção MongoDB.

Antes de encontrar, atualizar e excluir quaisquer documentos no MongoDB, você precisa inseri-los. Você pode inserir documentos usando os seguintes métodos:

insert_one() para inserir um documento
insert_many() para inserir um ou mais documentos

Este guia inclui as seguintes seções:

O campo _id descreve o campo _id que cada documento contém
Inserir um Documento descreve como usar o driver para inserir um único documento em uma coleção
Inserir Vários Documentos descreve como usar o driver para inserir vários documentos em uma coleção
Informações adicionais fornecem links para recursos e documentação da API para os tipos e métodos mencionados neste guia

O campo _id

No MongoDB, cada documento deve conter um campo _id exclusivo. O MongoDB permite gerenciar este campo das seguintes maneiras:

Gerencie você mesmo este campo, garantindo que cada valor de _id que você definir seja único.
Permita que o acionador gere automaticamente valores únicos de ObjectId . O driver gera um valor ObjectId exclusivo para cada documento se você não especificar um valor para o campo _id ao executar uma inserção.

A menos que você ofereça garantias rubustas de exclusividade, recomendamos que deixe o driver gerar automaticamente os valores de _id para seus documentos.

Importante

Valores de _id duplicados

Se você tentar executar uma operação de gravação que inclua valores _id duplicados, os valores duplicados violarão restrições de índice únicas e farão com que a operação de gravação falhe.

Para saber mais sobre o campo _id , consulte Índices únicos no manual do servidor MongoDB.

Para saber mais sobre estrutura e regras de documentos, consulte Documentos no manual do servidor MongoDB.

Insira um documento

Use o método insert_one() para inserir um único documento em uma coleção.

Após a inserção bem-sucedida, o método retorna uma instância InsertOneResult que contém o _id do documento inserido.

Exemplo

O exemplo a seguir usa o método insert_one() para inserir um documento na collection books :

let my_coll: Collection<Book> = client.database("db").collection("books");
let doc = Book { _id: 8, title: "Atonement".to_string(), author: "Ian McEwan".to_string() };
let insert_one_result = my_coll.insert_one(doc, None).await?;
println!("Inserted document with _id: {}", insert_one_result.inserted_id);

Inserted document with _id: 8

Dica

Bancos de Dados e Coleções Inexistentes

Se um reconhecimento de data center e uma collection não existirem quando você executar uma operação de gravação neles, o servidor os criará automaticamente.

Modificar comportamento do insert_one

Você pode modificar o comportamento do método insert_one() criando e passando uma estrutura InsertOneOptions .

Observação

Opções de Instanciação

O driver Rust implementa o padrão de design Builder para a criação de muitos tipos diferentes, incluindo InsertOneOptions. Você pode usar o método builder() de cada tipo para construir uma instância de opções encadeando as funções do construtor de opções, uma de cada vez.

A tabela a seguir descreve as opções disponíveis em InsertOneOptions:

Opção	Descrição
`bypass_document_validation`	If `true`, allows the driver to perform a write that violates document-level validation. To learn more about validation, see the guide on Schema Validation. Type: `bool` Default: `false`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`comment`	An arbitrary `Bson` value tied to the operation to trace it through the database profiler, `currentOp`, and logs. This option is available only when connecting to MongoDB Server versions 4.4 and later. Type: `Bson` Default: `None`

O seguinte código mostra como construir uma instância do InsertOneOptions :

let _opts = InsertOneOptions::builder()
    .bypass_document_validation(true)
    .build();

Insira vários documentos

Use o método insert_many() para inserir vários documentos em uma coleção.

Após a inserção bem-sucedida, o método retorna uma instância InsertManyResult que contém os valores _id dos documentos inseridos.

Exemplo

O exemplo a seguir usa o método insert_many() para inserir vários documentos na collection books :

let docs = vec![
    Book {
        _id: 5,
        title: "Cat's Cradle".to_string(),
        author: "Kurt Vonnegut Jr.".to_string()
    },
    Book {
        _id: 6,
        title: "In Memory of Memory".to_string(),
        author: "Maria Stepanova".to_string()
    },
    Book {
        _id: 7,
        title: "Pride and Prejudice".to_string(),
        author: "Jane Austen".to_string()
    }
];
let insert_many_result = my_coll.insert_many(docs, None).await?;
println!("Inserted documents with _ids:");
for (_key, value) in &insert_many_result.inserted_ids {
    println!("{:?}", value);
}

Inserted documents with _ids:
Int32(5)
Int32(6)
Int32(7)

Dica

Bancos de Dados e Coleções Inexistentes

Se um reconhecimento de data center e uma collection não existirem quando você executar uma operação de gravação neles, o servidor os criará automaticamente.

Modificar comportamento insert_many

Você pode modificar o comportamento do método insert_many() construindo e passando uma estrutura InsertManyOptions . A tabela a seguir descreve as opções disponíveis em InsertManyOptions:

Opção	Descrição
`bypass_document_validation`	If `true`, allows the driver to perform a write that violates document-level validation. To learn more about validation, see the guide on Schema Validation. Type: `bool` Default: `false`
`ordered`	If `true`, when any insert fails, the operation returns without inserting the remaining documents. If `false`, even if an insert fails, the operation continues with the remaining writes. To learn more about ordered inserts, see the Ordered Behavior Example section of this guide. Type: `bool` Default: `true`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`comment`	An arbitrary `Bson` value tied to the operation to trace it through the database profiler, `currentOp`, and logs. This option is available only when connecting to MongoDB Server versions 4.4 and later. Type: `Bson` Default: `None`

O seguinte código mostra como construir uma instância do InsertManyOptions :

let _opts = InsertManyOptions::builder()
    .comment(Some("hello world".into()))
    .build();

Exemplo de comportamento ordenado

Suponha que você queira inserir os seguintes documentos na collection books :

{ "_id": 1, "title": "Where the Wild Things Are" }
{ "_id": 2, "title": "The Very Hungry Caterpillar" }
{ "_id": 1, "title": "Blueberries for Sal" }
{ "_id": 3, "title": "Goodnight Moon" }

Quando você tenta inserir estes documentos, o resultado depende do valor da opção ordered em seu InsertManyOptions:

Se ordered for true (o valor padrão), o driver lançará um BulkWriteError ao tentar inserir o documento com o valor _id duplicado. No entanto, o driver ainda insere os documentos antes que o erro ocorra.
Se você definir ordered como false, o driver ainda lançará uma BulkWriteError ao tentar inserir o documento com o valor _id duplicado, mas inserirá todos os outros documentos.

O código a seguir mostra como realizar uma operação de gravação não ordenada para inserir os documentos anteriores:

let docs = vec![
    Book { _id: 1, title: "Where the Wild Things Are".to_string(), author: "".to_string() },
    Book { _id: 2, title: "The Very Hungry Caterpillar".to_string(), author: "".to_string() },
    Book { _id: 4, title: "Blueberries for Sal".to_string(), author: "".to_string() },
    Book { _id: 3, title: "Goodnight Moon".to_string(), author: "".to_string() }
];
let opts = InsertManyOptions::builder().ordered(false).build();
my_coll.insert_many(docs, opts).await?;

Embora essa operação resulte em um BulkWriteError , você ainda poderá encontrar os documentos que não produzem erros na sua coleção:

{ "_id": 1, "title": "Where the Wild Things Are" }
{ "_id": 2, "title": "The Very Hungry Caterpillar" }
{ "_id": 3, "title": "Goodnight Moon" }

Informações adicionais

Para exemplos executáveis das operações de inserção, consulte os seguintes exemplos de uso:

Documentação da API

Para saber mais sobre os métodos e tipos mencionados neste guia, consulte a documentação da API abaixo:

Voltar

Limitar resultados

Modify