MongoDB\Collection::updateOne()

Definição

MongoDB\Collection::updateOne()

Atualize no máximo um documento que corresponda aos critérios de filtro. Se vários documentos corresponderem aos critérios de filtro, somente o primeiro documento correspondente será atualizado.

function updateOne(
    array|object $filter,
    array|object $update,
    array $options = []
): MongoDB\UpdateResult

Parâmetros

$filter : array|object

Os critérios de filtro que especificam os documentos a serem atualizados.

$update : array|object

Especifica as combinações de campo e valor a serem atualizadas e quaisquer operadores de atualização relevantes. $update usa os operadores de atualização do MongoDB. A partir do MongoDB 4.2, um aggregation pipeline pode ser passado como esse parâmetro.

$options : array

Uma array especificando as opções desejadas.

Nome	Tipo	Descrição
arrayFilters	array	Uma array de documentos de filtro que determina quais elementos da array modificar para uma operação de atualização em um campo da array. Novidade na versão 1.3.
bypassDocumentValidation	booleano	Se true, permite que a operação de gravação contorne a validação do nível do documento. O padrão é false.
agrupamento	array|object	A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de string , como regras para letras maiúsculas e marcas de acento. Ao especificar agrupamento, o campo locale é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento. Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão, a operação usará o agrupamento especificado para a coleção. Se nenhum agrupamento for especificado para a coleção nem para a operação, o MongoDB usará a comparação binária simples usada nas versões anteriores para comparações de strings.
comment	misto	Permite ao usuário especificar um comentário arbitrário para ajudar a rastrear a operação por meio do profiler de banco de dados, da saída currentOp e dos registros. Esta opção está disponível desde o MongoDB 4.4 e resultará em uma exceção no momento da execução se for especificada para uma versão mais antiga do servidor. Novidade na versão 1.13.
dica	string|array|objeto	O índice a ser utilizado. Especifique o nome do índice como uma string ou o padrão da chave do índice como um documento. Se especificado, o sistema de query considerará apenas os planos usando o índice sugerido. Esta opção está disponível desde o MongoDB 4.2 e resultará em uma exceção no tempo de execução, se especificado para uma versão mais antiga do servidor. Novidade na versão 1.6.
let	array|object	Mapa de nomes e valores de parâmetros. Os valores devem ser expressões constantes ou fechadas que não façam referência aos campos do documento. Os parâmetros podem ser acessados como variáveis em um contexto de expressão agregada (como $$var). Isto não é suportado para versões de servidor anteriores à 5.0 e resultará em uma exceção no tempo de execução se utilizado. Novidade na versão 1.13.
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação. Novidade na versão 1.3.
upsert	booleano	Se definido como true, é criado um novo documento quando nenhum documento corresponde aos critérios da consulta. O valor padrão é false, que não insere um novo documento quando nenhuma correspondência é encontrada.
writeConcern	MongoDB\Driver\WriteConcern	Preocupação de gravação a ser usada na operação. O padrão é a preocupação de gravação da coleção. Não é possível especificar uma preocupação de gravação para operações individuais como parte de uma transação. Em vez disso, defina a opção writeConcern ao iniciar a transação.

Return Values

Um MongoDB\UpdateResult objeto , que encapsula um MongoDB\Driver\WriteResult objeto.

Erros/exceções

MongoDB\Exception\UnsupportedException se as opções forem usadas e não aceitas pelo servidor selecionado (p. ex., collation, readConcern, writeConcern).

MongoDB\Exception\InvalidArgumentException para erros relacionados à análise de parâmetros ou opções.

MongoDB\Driver\Exception\BulkWriteException para erros relacionados à operação de gravação. Os usuários devem inspecionar o valor retornado por getWriteResult() para determinar a natureza do erro.

MongoDB\Driver\Exception\RuntimeException para outros erros no nível da extensão (por exemplo erros de conexão).

Comportamento

Ao avaliar critérios de query, oMongoDB compara tipos e valores de acordo com suas próprias regras de comparação para BSON types, o que difere da comparação do e digite PHP malabarismo regras. Ao corresponder a um tipo BSON especial, os critérios de query devem usar a respectiva classe BSON na extensão (por exemplo use MongoDB\BSON\ObjectId para corresponder a um ObjectId).

Se for MongoDB\Driver\Exception\BulkWriteException é lançado, os usuários devem ligar para getWriteResult() e inspecione o MongoDB\Driver\WriteResult retornado objeto para determinar a natureza do erro.

Por exemplo, uma operação de gravação pode ter sido aplicada com êxito ao servidor primário, mas não conseguiu atender a preocupação de gravação (p. ex., a replicação demorou muito tempo). Como alternativa, uma operação de gravação pode ter falhado completamente (p. ex., violação de chave única).

Exemplos

O exemplo a seguir atualiza um documento com o restaurant_id de "40356151" ao definir o campo name como "Brunos on Astoria":

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$updateResult = $collection->updateOne(
    [ 'restaurant_id' => '40356151' ],
    [ '$set' => [ 'name' => 'Brunos on Astoria' ]]
);
printf("Matched %d document(s)\n", $updateResult->getMatchedCount());
printf("Modified %d document(s)\n", $updateResult->getModifiedCount());

A saída seria então semelhante a:

Matched 1 document(s)
Modified 1 document(s)

Veja também

• MongoDB\Collection::replaceOne()

• MongoDB\Collection::updateMany()

• MongoDB\Collection::bulkWrite()

• Atualize documentos

• referência do comando de atualização no manual do MongoDB