/ /

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

Os exemplos neste guia usam a collection restaurants no banco de dados sample_restaurants dos conjuntos de banco de dados de amostra do Atlas. Para acessar essa coleção a partir do seu aplicação PHP , instancie um MongoDB\Client que se conecte a um Atlas cluster e atribua o seguinte valor à sua variável $collection :

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

Para aprender como criar uma implantação gratuita do MongoDB e carregar os conjuntos de dados de amostra, consulte o Guia de introdução 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`	Especifica se a operação de atualização executará uma operação de upsert se nenhum documento corresponder ao filtro de consulta. Para obter mais informações, consulte a declaração upsert no manual do MongoDB Server . O padrão `false`é.
`bypassDocumentValidation`	Especifica se a operação de atualização ignora a validação do documento . Isso permite atualizar documentos que não atendam aos requisitos de validação de esquema , se houver. Para obter mais informações sobre validação de esquema, consulte Validação de esquema no manual do MongoDB Server . O padrão `false` é.
`sort`	Aplica-se apenas a `updateOne()`. Especifica a ordem de classificação a ser aplicada aos documentos antes de executar a operação de atualização.
`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`	Um comentário a ser anexado à operação. Para obter mais informações, consulte o guia de campos de comando de inserção no manual do MongoDB Server .

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 incluir comparação de caso. Quando definido `true` como, o comportamento de comparação depende do valor do `strength` campo : - Se `strength` `1`for, a biblioteca PHP compara caracteres básicos e maiúsculas e minúsculas. - `strength` Se `2` for, a biblioteca PHP compara caracteres básicos, diacríticos, outras diferenças secundárias e maiúsculas e minúsculas. - Se `strength` for qualquer outro valor, este campo será ignorado. Quando definida `false` como, a biblioteca PHP não inclui a comparação de caso no nível `1` de força `2` ou. Tipo de Dados: `bool` Padrão: `false`
`caseFirst`	(Opcional) Especifica a ordem de classificação das diferenças de caso durante as 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 que "2". 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 que "2". 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 o espaço em branco e a pontuação como caracteres básicos 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 `alternate` campo é definido `"shifted"` como. Tipo de dados: `string` Padrão: `"punct"`
`backwards`	(Opcional) Especifica se as strings contendo diacríticos são classificadas 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 o servidor reconheceu a operação de gravação.
`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();

Modified documents: 206

Construtor de atualizações

Você pode usar a classe MongoDB\Builder\Update para construir documentos de atualização com o suporte da conclusão de código IDE e da verificação de tipo PHP. A classe Update fornece métodos de fábrica que correspondem aos operadores de atualização do MongoDB , como $set, $inc e $unset.

Para usar o construtor de atualização, importe as seguintes classes para seu aplicativo:

use MongoDB\Builder\Query;
use MongoDB\Builder\Update;

O exemplo a seguir usa o método de fábrica Update::set() para atualizar o campo name para '2 Bagels 2 Buns' no primeiro documento correspondente com um valor name de 'Bagels N Buns' na coleção restaurants:

$result = $collection->updateOne(
    Query::query(name: Query::eq('Bagels N Buns')),
    Update::set(name: '2 Bagels 2 Buns'),
);

Para aplicar vários operadores de atualização em uma única operação, passe os operadores para o construtor MongoDB\Builder\Update. O exemplo a seguir combina Update::set() e Update::unset() para definir o campo cuisine como Pasta e remover o campo grades de todos os documentos com um valor cuisine de 'Pizza':

$result = $collection->updateMany(
    Query::query(cuisine: Query::eq('Pizza')),
    new Update(
        Update::set(cuisine: 'Pasta'),
        Update::unset('grades'),
    ),
);

Para saber mais sobre as classes de construtores e ver mais exemplos, consulte o guia Operações com construtores.

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