Menu Docs
Página inicial do Docs
/
Línguas
/
Go
/
Go
/
Fundamentos
/
Operações CRUD
/
Operações de Escrita

Modificar documentos

Nesta página

  • Visão geral
  • Uma observação sobre _id
  • Update
  • Parâmetros
  • Valores de retorno
  • Substituir
  • Parâmetros
  • Valores de retorno
  • Informações adicionais
  • Documentação da API

Visão geral

Neste guia, você pode aprender a modificar documentos no MongoDB usando operações de atualização e substituição.

As operações de atualização alteram os campos que você especifica, deixando outros campos e valores inalterados. A substituição de operações remove todos os campos existentes, exceto _id em um documento e substitui os campos excluídos pelos novos campos e valores especificados.

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

Alterar assinatura do método

Observação

Espaço reservado

changeX é um espaço reservado e não um método real.

O padrão espera que você:

  • Especifique um filtro de consulta para corresponder a um ou mais documentos para modificar.

  • Especifique as alterações de campo e valor.

  • Especifique as opções para modificar o comportamento, se necessário.

O driver fornece os seguintes métodos para modificar documentos:

  • UpdateByID()

  • UpdateOne()

  • UpdateMany()

  • ReplaceOne()

  • BulkWrite() (não discutido neste guia)

  • FindOneAndUpdate() (não discutido neste guia)

  • FindOneAndReplace() (não discutido neste guia)

Uma observação sobre _id

Cada documento em uma coleção do MongoDB tem um campo _id exclusivo e imutável. Você não pode usar as operações de atualização e substituição para alterar o campo _id. Se você tentar alterar esse campo, os métodos de atualização e substituição retornarão um WriteError.

Update

Use o método UpdateOne() ou UpdateByID() para atualizar um único documento.

Use o método UpdateMany() para atualizar vários documentos.

Parâmetros

Cada método utiliza 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. O documento de atualização também inclui os campos e valores que descrevem a alteração. Atualize os documentos usando o seguinte formato:

bson.D{{"<update operator>", bson.D{{"<field>", <value>},
                                    {"<field>", <value>}, ... }},
       {"<update operator>", ... }, ... }

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

Observação

Pipelines de agregação em operações de atualização

Se você estiver usando a versão 4 do servidor MongoDB .2 ou posterior, você pode usar aggregation pipelines compostos por um subconjunto de aggregation stages em operações de atualização. Para saber mais sobre os estágios de aggregation que têm suporte do MongoDB em aggregation pipelines, consulte nosso tutorial sobre como executar atualizações com aggregation pipelines.

Valores de retorno

UpdateOne(), UpdateByID() e UpdateMany() retornam um tipo UpdateResult que contém informações sobre a operação de atualização, se a operação for bem-sucedida. O tipo UpdateResult contém as seguintes propriedades:

Propriedade
Descrição
MatchedCount
O número de documentos correspondidos pelo filtro
ModifiedCount
O número de documentos modificados pela operação
UpsertedCount
O número de documentos atualizados pela operação
UpsertedID
O _id do documento atualizado ou nil, se não houver nenhum

Se vários documentos corresponderem ao filtro de query passado 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.

Consulte nossoguia de upsert para saber como inserir um novo documento se nenhum documento corresponder ao filtro de query.

Exemplo

O documento a seguir descreve um funcionário:

{
   "_id" : 2158,
   "name" : "Mary Shelley",
   "department" : "Marketing",
   "role" : "Marketing Analyst",
   "bonus" : 2500,
   ...
}

O exemplo a seguir utiliza o método UpdateByID() para:

  • Corresponde ao documento no qual o valor de _id é 2158.

  • Defina o campo name como "Mary Wollstonecraft Shelley" e o campo role como "Marketing Director".

  • Aumente o valor do campo bonus em 2000.

filter := bson.D{{"_id", 2158}}
update := bson.D{{"$set", bson.D{{"name", "Mary Wollstonecraft Shelley"},
   {"role", "Marketing Director"}}}, {"$inc", bson.D{{"bonus", 2000}}}}
result, err := collection.UpdateOne(context.TODO(), filter, update)
fmt.Printf("Documents matched: %v\n", result.MatchedCount)
fmt.Printf("Documents updated: %v\n", result.ModifiedCount)

O seguinte mostra o documento atualizado resultante da operação de atualização anterior:

{
   "_id" : 2158,
   "name" : "Mary Wollstonecraft Shelley",
   "department" : "Marketing",
   "role" : "Marketing Director",
   "bonus" : 4500,
   ...
}

Substituir

Use o método ReplaceOne() para substituir um único documento.

Parâmetros

ReplaceOne() espera um documento de substituição, que é o documento que você deseja substituir um documento existente. Os documentos de substituição usam o seguinte formato:

bson.D{{"<field>", "<value>"}, {"<field>", "<value>"}, ... }

Valores de retorno

ReplaceOne() retorna um tipo de UpdateResult que contém informações sobre a operação de substituição se a operação for bem-sucedida. O tipo UpdateResult contém as seguintes propriedades:

Propriedade
Descrição
MatchedCount
O número de documentos correspondidos pelo filtro
ModifiedCount
O número de documentos modificados pela operação
UpsertedCount
O número de documentos atualizados pela operação
UpsertedID
O _id do documento atualizado ou nil, se não houver nenhum

Se vários documentos corresponderem ao filtro de query passado para ReplaceOne(), o método selecionará e substituirá o primeiro documento correspondente. Se nenhum documento corresponder ao filtro de query, a operação de substituição falhará.

Exemplo

O documento a seguir descreve um item de cozinha:

{
   "_id" : 2056,
   "item" : "Mug",
   "brand" : "Simply Ceramics",
   "price" : 2.99,
   "material" : "Glass"
}

O exemplo a seguir usa o método ReplaceOne() para substituir este documento por um que contenha um campo item com o valor de "Cup" e um campo quantity com um valor de 107:

filter := bson.D{{"_id", 2056}}
replacement := bson.D{{"item", "Cup"}, {"quantity", 107}}
result, err := collection.ReplaceOne(context.TODO(), filter, replacement)
fmt.Printf("Documents matched: %v\n", result.MatchedCount)
fmt.Printf("Documents replaced: %v\n", result.ModifiedCount)

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

{
   "_id" : 2056,
   "item" : "Cup",
   "quantity" : 107
}

Informações adicionais

Para exemplos executáveis da atualização e substituição de operações, consulte os seguintes exemplos de uso:

Para saber mais sobre as operações mencionadas, consulte os seguintes guias:

Para saber mais sobre como atualizar elementos de array, consulte Atualizar arrays em um documento.

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Exclua documentos