Modificar documentos

Atualizar padrão do documento

No MongoDB, todos os métodos para alterar documentos seguem o mesmo padrão:

Esses métodos usam os seguintes parâmetros:

• Um filtro de query para corresponder a um ou mais documentos a serem alterados

• Um documento de atualização que especifica as alterações de campo e valor

• (Opcional) Um tipo de opções para modificar o comportamento padrão do método

O driver Rust oferece os seguintes métodos para alterar documentos:

• update_one()

• update_many()

• replace_one()

Você pode recuperar e modificar dados em uma ação usando operações compostas. Para saber mais, consulte o guia sobre operações compostas.

O campo _id

Cada documento em uma MongoDB collection tem um campo _id exclusivo e imutável. Se você tentar alterar o campo _id por meio de uma operação de atualização ou substituição, o driver gerará um WriteError e não executará atualizações.

Parâmetros

Cada método utiliza um filtro de query e um documento de atualização que inclui pelo menos um operador de atualização. O operador de atualização especifica o tipo de atualização a ser executada e inclui os campos e valores que descrevem a alteração. Atualize os documentos usando o seguinte formato:

doc! { "<update operator>": doc! { "<field>": <value> } }

Para especificar várias atualizações em um documento de atualização, use o seguinte formato:

doc! {
    "<update operator>": doc!{"<field>": <value>},
    "<update operator>": doc!{"<field>": <value>},
    ...
}

Consulte o manual do servidor MongoDB para obter uma lista completa de operadores de atualização e descrições.

As operações de atualização também usam um parâmetro UpdateOptions . Para saber mais sobre como modificar o comportamento dos métodos de atualização, consulte a seção Modificar comportamento de atualização e substituição deste guia.

Valor de retorno

Os métodos update_one() e update_many() retornam um tipo UpdateResult se a operação for bem-sucedida. O tipo UpdateResult contém as seguintes propriedades que descrevem a operação:

Se vários documentos corresponderem ao filtro de query que você passa para UpdateOne(), o método selecionará e atualizará o primeiro documento correspondente. Se nenhum documento corresponder ao filtro de query, a operação de atualização não fará alterações.

Exemplo de atualização

Os seguintes documentos descrevem os funcionários de uma empresa:

{
  "_id": ObjectId('4337'),
  "name": "Shelley Olson",
  "department": "Marketing",
  "role": "Director",
  "bonus": 3000
},
{
  "_id": ObjectId('4902'),
  "name": "Remi Ibrahim",
  "department": "Marketing",
  "role": "Consultant",
  "bonus": 1800
}

Este exemplo executa uma operação de atualização com o método update_many() . O método update_many() utiliza os seguintes parâmetros:

• Um filtro de query para corresponder a documentos onde o valor do campo department é "Marketing"

• Um documento de atualização que contém as seguintes atualizações:

  • Um operador $set para alterar o valor de department para "Business Operations" e role para "Analytics Specialist"

  • Um operador $inc para aumentar o valor de bonus em 500

let update_doc = doc! {
        "$set": doc! { "department": "Business Operations",
                      "role": "Analytics Specialist" },
        "$inc": doc! { "bonus": 500 }
};
let res = my_coll
    .update_many(doc! { "department": "Marketing" }, update_doc, None)
    .await?;
println!("Modified documents: {}", res.modified_count);

Modified documents: 2

Os seguintes documentos refletem as alterações resultantes da operação de atualização anterior:

{
  "_id": ObjectId('4337'),
  "name": "Shelley Olson",
  "department": "Business Operations",
  "role": "Analytics Specialist",
  "bonus": 3500
},
{
  "_id": ObjectId('4902'),
  "name": "Remi Ibrahim",
  "department": "Business Operations",
  "role": "Analytics Specialist",
  "bonus": 2300
}

Atualizar por exemplo do ObjectId

O seguinte documento descreve um funcionário de uma empresa:

{
  "_id": ObjectId('4274'),
  "name": "Jill Millerton",
  "department": "Marketing",
  "role": "Consultant"
}

Este exemplo query o documento anterior especificando um filtro de query para corresponder ao valor _id exclusivo do documento. Em seguida, o código executa uma operação de atualização com o método update_one() . O método update_one() utiliza os seguintes parâmetros:

• Filtro de query que corresponde a um documento no qual o valor do campo _id é ObjectId('4274')

• Atualizar documento que cria instruções para definir o valor de name para "Jill Gillison"

let id = ObjectId::from_str("4274").expect("Could not convert to ObjectId");
let filter_doc = doc! { "_id": id };
let update_doc = doc! {
        "$set": doc! { "name": "Jill Gillison" }
};
let res = my_coll
    .update_one(filter_doc, update_doc, None)
    .await?;
println!("Modified documents: {}", res.modified_count);

Modified documents: 1

O documento a seguir reflete as alterações resultantes da operação de atualização anterior:

{
  "_id": ObjectId('4274'),
  "name": "Jill Gillison",
  "department": "Marketing",
  "role": "Consultant"
}

Parâmetros

O método replace_one() usa um filtro de query e um documento de substituição, que contém os campos e valores que substituirão um documento existente. Os documentos de substituição usam o seguinte formato:

doc! { "<field>": <value>, "<field>": <value>, ... }

As operações de substituição também usam um parâmetro UpdateOptions . Para saber mais sobre como modificar o comportamento do método replace_one() , consulte a seção Modificar comportamento de atualização e substituição deste guia.

Return Values

O método replace_one retorna um tipo UpdateResult se a operação for bem-sucedida. O tipo UpdateResult contém as seguintes propriedades que descrevem a operação:

Se vários documentos corresponderem ao filtro de query que você passa para replace_one(), o método selecionará e substituirá o primeiro documento correspondente. Se nenhum documento corresponder ao filtro de query, a operação de substituição não fará alterações.

Exemplo de substituição

O seguinte documento descreve um funcionário de uma empresa:

{
  "_id": ObjectId('4501'),
  "name": "Matt DeGuy",
  "role": "Consultant",
  "team_members": [ "Jill Gillison", "Susan Lee" ]
}

Este exemplo utiliza o método replace_one() para substituir o documento anterior por um que tenha os seguintes campos:

• Um valor name de "Susan Lee"

• Um valor role de "Lead Consultant"

• Um valor team_members de [ "Jill Gillison" ]

let replace_doc = doc! {
    "name": "Susan Lee",
    "role": "Lead Consultant",
    "team_members": vec! [ "Jill Gillison" ]
};
let res = my_coll
    .replace_one(doc! { "name": "Matt DeGuy" }, replace_doc, None)
    .await?;
println!(
    "Matched documents: {}\nModified documents: {}",
    res.matched_count, res.modified_count
);

Matched documents: 1
Modified documents: 1

O documento substituído contém o conteúdo do documento de substituição e o campo _id imutável:

{
  "_id": ObjectId('4501'),
  "name": "Susan Lee",
  "role": "Lead Consultant",
  "team_members": [ "Jill Gillison" ]
}

Documentação da API

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

• update_one()

• update_many()

• UpdateResult

• UpdateOptions

• replace_one()

• ReplaceOptions

• WriteError