/ /

Substituir documentos

Visão geral

Neste guia, você pode aprender como usar a biblioteca PHP do MongoDB para executar uma operação de substituição em uma coleção do MongoDB . Uma operação de substituição tem desempenho diferente de uma operação de atualização. Uma operação de atualização modifica somente os campos especificados em um documento de destino. Uma operação de substituição remove todos os campos do documento de destino e os substitui por novos.

Para substituir um documento, use o método MongoDB\Collection::replaceOne() .

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.

Operação de substituição

Você pode executar uma operação de substituição usando MongoDB\Collection::replaceOne(). Esse método remove todos os campos, exceto o campo _id do primeiro documento que corresponde aos critérios de pesquisa. Em seguida, ele insere os campos e valores especificados no documento.

Parâmetros necessários

O método replaceOne() exige os seguintes parâmetros:

documento de filtro de query , que determina os documentos a serem substituídos. Para obter mais informações sobre filtros de query, consulte a seção Documentos de filtro de query no manual do MongoDB Server .
Substituir documento, que especifica os campos e valores a serem inseridos no novo documento.

Valor de retorno

O método replaceOne() retorna um objeto MongoDB\UpdateResult . O tipo MongoDB\UpdateResult contém os seguintes métodos:

Método	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.
`getUpsertedCount()`	Retorna o número de documentos atualizados no banco de dados, se houver.
`getUpsertedId()`	Retorna a ID do documento que foi atualizado no banco de dados, se o driver tiver realizado um upsert.
`isAcknowledged()`	Retorna um booleano indicando se o servidor reconheceu a operação de gravação.

Exemplo

O exemplo a seguir usa o método replaceOne() para substituir os campos e valores de um documento no qual o valor do campo name é 'Pizza Town'. Em seguida, imprime o número de documentos modificados:

$replaceDocument = [
    'name' => 'Mongo\'s Pizza',
    'cuisine' => 'Pizza',
    'address' => [
        'street' => '123 Pizza St',
        'zipCode' => '10003',
    ],
    'borough' => 'Manhattan',
];
$result = $collection->replaceOne(['name' => 'Pizza Town'], $replaceDocument);
echo 'Modified documents: ', $result->getModifiedCount();

Modified documents: 1

Importante

Os valores dos campos _id são imutáveis. Se o documento de substituição especificar um valor para o campo _id, ele deverá corresponder ao valor _id do documento existente.

Modificar a operação de substituição

Você pode modificar o comportamento do método MongoDB\Collection::replaceOne() 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 substituiçã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 substituição ignora a validação do documento . Isso permite substituir documentos que não atendem 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`	Especifica a ordem de classificação a ser aplicada aos documentos antes de executar a operação de substituiçã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.
`hint`	Obtém ou define o índice para procurar documentos. Para obter mais informações, consulte a declaração de dica no manual do MongoDB Server .
`session`	Especifica a sessão do cliente a ser associada à operação.
`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`	Anexa um comentário à operação. Para obter mais informações, consulte o guia de campos de comando de inserção no manual do MongoDB Server .

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.

Exemplo

O código a seguir usa o método replaceOne() para localizar o primeiro documento no qual o campo name tem o valor 'Food Town' e, em seguida, substitui esse documento por um novo documento no qual o valor name é 'Food World'. Como a opção upsert está definida como true, a biblioteca insere um novo documento se o filtro de query não corresponder a nenhum documento existente:

$replaceDocument = [
    'name' => 'Food World',
    'cuisine' => 'Mixed',
    'address' => [
        'street' => '123 Food St',
        'zipCode' => '10003',
    ],
    'borough' => 'Manhattan',
];
$result = $collection->replaceOne(
    ['name' => 'Food Town'],
    $replaceDocument,
    ['upsert' => true],
);

Informações adicionais

Para saber mais sobre as operações de atualização, consulte o guia Atualizar documentos .

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

Atualize documentos

Exclua documentos