/ /

Atualize documentos

Visão geral

Neste guia, você pode aprender como usar a Biblioteca PHP do MongoDB para atualizar documentos em uma coleção MongoDB . Você pode chamar o método MongoDB\Collection::updateOne() para atualizar um único documento ou o método MongoDB\Collection::updateMany() para atualizar vários documentos.

Dados de amostra

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To access this collection from your PHP application, instantiate a MongoDB\Client that connects to an Atlas cluster and assign the following value to your $collection variable:

$collection = $client->sample_restaurants->restaurants;

Para aprender a criar uma implantação gratuita do MongoDB e carregar os conjuntos de dados de amostra, consulte o guia Começar do MongoDB.

Atualizar operações

Você pode executar operações de atualização no MongoDB com os seguintes métodos:

MongoDB\Collection::updateOne(), que atualiza o primeiro documento que corresponde aos critérios de pesquisa
MongoDB\Collection::updateMany(), que atualiza todos os documentos que correspondem aos critérios de pesquisa

Cada método de atualização exige os seguintes parâmetros:

documento de filtro de query : especifica quais documentos atualizar. Para obter mais informações sobre filtros de query, consulte a seção Documentos de filtro de query no manual do MongoDB Server .
Atualizar documento: especifica o operador de atualização ou o tipo de atualização a ser executada, e os campos e valores a serem alterados. Para obter uma lista de operadores de atualização e seu uso, consulte o guia Operadores de atualização de campo no manual do MongoDB Server .

Atualizar um documento

O exemplo seguinte utiliza o método updateOne() para atualizar o valor name de um documento na coleção restaurants de 'Bagels N Buns' para '2 Bagels 2 Buns':

$result = $collection->updateOne(
    ['name' => 'Bagels N Buns'],
    ['$set' => ['name' => '2 Bagels 2 Buns']],
);

Atualizar muitos documentos

O exemplo seguinte utiliza o método updateMany() para atualizar todos os documentos que têm um valor cuisine de 'Pizza'. Após a atualização, os documentos têm um valor cuisine de 'Pasta'.

$result = $collection->updateMany(
    ['cuisine' => 'Pizza'],
    ['$set' => ['cuisine' => 'Pasta']],
);

Personalizar a operação de atualização

Você pode modificar o comportamento dos métodos updateOne() e updateMany() passando uma array que especifique valores de opção como um parâmetro. A tabela a seguir descreve algumas opções que você pode definir na array:

Opção	Descrição
`upsert`	Specifies whether the update operation performs an upsert operation if no documents match the query filter. For more information, see the upsert statement in the MongoDB Server manual. Defaults to `false`.
`bypassDocumentValidation`	Specifies whether the update operation bypasses document validation. This lets you update documents that don't meet the schema validation requirements, if any exist. For more information about schema validation, see Schema Validation in the MongoDB Server manual. Defaults to `false`.
`sort`	Aplica-se apenas a `updateOne()`. Especifica a ordem de classificação a ser aplicada aos documento antes de executar a operação de atualizar.
`collation`	Especifica o tipo de agrupamento de idiomas a ser usado ao classificar os resultados. Para saber mais, consulte a seção Agrupamento desta página.
`arrayFilters`	Especifica a quais elementos da array uma atualização se aplica se a operação modificar os campos da array.
`hint`	Define o índice para digitalizar documentos. Para obter mais informações,consulte a declaração de dica no manual do MongoDB Server .
`writeConcern`	Define a preocupação de gravação para a operação. Para obter mais informações, consulte Write Concern no manual do MongoDB Server .
`let`	Especifica um documento com uma lista de valores para melhorar a legibilidade da operação. Os valores devem ser expressões constantes ou fechadas que não façam referência aos campos do documento . Para obter mais informações, consulte a declaração let no manual do MongoDB Server .
`comment`	A comment to attach to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.

O exemplo a seguir usa o método updateMany() para localizar todos os documentos que têm borough valor de 'Manhattan'. Em seguida, ele atualiza o valor borough nesses documentos para 'Manhattan (north)'. Como a opção upsert está definida como true, a Biblioteca PHP do MongoDB insere um novo documento se o filtro de query não corresponder a nenhum documento existente.

$result = $collection->updateMany(
    ['borough' => 'Manhattan'],
    ['$set' => ['borough' => 'Manhattan (north)']],
    ['upsert' => true],
);

Agrupamentos

Para especificar um agrupamento para sua operação, passe um parâmetro de array $options que defina a opção collation para o método de operação. Atribua a opção collation a uma array que configure as regras de agrupamento.

A tabela a seguir descreve os campos que você pode definir para configurar o agrupamento:

Campo	Descrição
`locale`	(Obrigatório) Especifica a locale { components internacionais para Unicode} (ICU). Para obter uma lista de localidades suportadas, consulte Localidades de Agrupamento e Parâmetros Padrão no manual do MongoDB Server . Tipo de dados: `string`
`caseLevel`	(Opcional) Especifica se a comparação de caso deve ser incluída. Quando definido `true` como, o comportamento de comparação depende do valor do `strength` campo: - Se `strength` `1`for, a biblioteca PHP compara caracteres base e caso. - `strength` Se `2` for, a biblioteca PHP compara caracteres base, diacríticos, outras diferenças secundárias e caso. - Se `strength` for qualquer outro valor, este campo será ignorado. Quando definido como `false`, a biblioteca PHP não inclui comparação de caso no nível de força `1` ou `2`. Tipo de dados: `bool` Padrão: `false`
`caseFirst`	(Opcional) Especifica a ordem de classificação das diferenças de caso durante comparações de nível terciário. Tipo de dados: `string` Padrão: `"off"`
`strength`	(Opcional) Especifica o nível de comparação a ser executado, conforme definido na documentação da ICU. Tipo de dados: `int` Padrão: `3`
`numericOrdering`	(Opcional) Especifica se o driver compara strings numéricas como números. Se definido `true` como, a biblioteca PHP compara strings numéricas como números. Por exemplo, ao comparar as strings "10" e "2", a biblioteca usa os valores numéricos das strings e trata "10" como maior que2 "". Se configurado `false` para, a biblioteca PHP compara strings numéricas como strings. Por exemplo, ao comparar as strings "10" e "2", a biblioteca compara um caractere de cada vez e trata "10" como menor que2 "". Para obter mais informações, consulte Restrições de agrupamento no manual do MongoDB Server . Tipo de dados: `bool` Padrão: `false`
`alternate`	(Opcional) Especifica se a biblioteca considera espaços em branco e pontuação como caracteres base para fins de comparação. Tipo de dados: `string` Padrão: `"non-ignorable"`
`maxVariable`	(Opcional) Especifica quais caracteres a biblioteca considera ignoráveis quando o campo `alternate` é definido como `"shifted"`. Tipo de dados: `string` Padrão: `"punct"`
`backwards`	(Opcional) Especifica se as strings que contêm diacríticos são ordenadas da parte de trás da string para a frente. Tipo de dados: `bool` Padrão: `false`

Para saber mais sobre agrupamento e os possíveis valores para cada campo, consulte a entrada de Agrupamento no manual do MongoDB Server.

Valor de retorno

Os métodos updateOne() e updateMany() retornam uma instância da classe MongoDB\UpdateResult . Esta classe contém as seguintes funções de membro:

Função	Descrição
`getMatchedCount()`	Retorna o número de documentos que corresponderam ao filtro de query, independentemente de quantos foram atualizados.
`getModifiedCount()`	Retorna o número de documentos modificados pela operação de atualização. Se um documento atualizado for idêntico ao original, ele não será incluído nesta contagem.
`isAcknowledged()`	Retorna um booleano indicando se a operação de gravação foi reconhecida.
`getUpsertedCount()`	Retorna o número do documento que foi atualizado no banco de dados.
`getUpsertedId()`	Retorna a ID do documento que foi atualizado no banco de dados, se o driver tiver realizado um upsert.

O exemplo a seguir usa o método updateMany() para atualizar o campo name dos documentos correspondentes de 'Dunkin' Donuts' para 'Dunkin''. Ele chama a função de membro getModifiedCount() para imprimir o número de documentos modificados:

$result = $collection->updateMany(
    ['name' => 'Dunkin\' Donuts'],
    ['$set' => ['name' => 'Dunkin\'']],
);
echo 'Modified documents: ', $result->getModifiedCount();

Informações adicionais

Para saber mais sobre como criar filtros de queries, consulte o guia Especifique uma consulta.

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

Acessar dados de um cursor

Substituir documentos