Insira documentos

Nesta página

Visão geral

O campo _id
Insira um documento
Exemplo
Modificar comportamento do insert_one
Insira vários documentos
Exemplo
Modificar comportamento insert_many
Exemplo de comportamento ordenado
Informações adicionais
Documentação da API

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

In a MongoDB collection, each document must contain a unique _id field value. O driver gera automaticamente um valor único para cada documento como um tipo ObjectId quando você insere dados em uma coleção.

Se preferir definir valores personalizados, você poderá atribuir os valores nos campos _id dos documentos passados para sua operação de inserção.

Importante

Valores de _id duplicados

Se você tentar inserir documentos que incluem valores _id duplicados, esses valores violarão restrições de índice únicos e causarão falha na operação de gravação.

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).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() encadeando os métodos do construtor de opções com o insert_one(). Esses métodos de construtor de opções definem InsertOneOptions campos de estrutura.

Observação

Opções de configuração

Você pode definir InsertOneOptions campos encadeando métodos de construtor de opções diretamente à chamada de método insert_one() . Se você estiver utilizando uma versão anterior do driver, você deverá construir uma instância do InsertOneOptions encadeando métodos de construtor de opção ao método builder() . Em seguida, passe a instância de opções como parâmetro para insert_one().

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 código a seguir mostra como definir o campo bypass_document_validation encadeando o método bypass_document_validation() ao método insert_one() :

let _result = my_coll.insert_one(doc)
    .bypass_document_validation(true)
    .await?;

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).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() encadeando os métodos do construtor de opções com o insert_many(). Esses métodos de construtor de opções definem InsertManyOptions campos de estrutura.

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 código a seguir mostra como definir o campo comment encadeando o método comment() ao método insert_many() :

let _result = my_coll.insert_many(docs)
    .comment(Some("hello world".into()))
    .await?;

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 passado para o método construtor de opção ordered() :

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

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: 1, title: "Blueberries for Sal".to_string(), author: "".to_string() },
    Book { _id: 3, title: "Goodnight Moon".to_string(), author: "".to_string() }
];
my_coll.insert_many(docs).ordered(false).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

Escrever

Modify