MongoDB\Collection::insertOne()

Definição

MongoDB\Collection::insertOne()

Insere um documento.

function insertOne(
    array|object $document,
    array $options = []
): MongoDB\InsertOneResult

Parâmetros

$document : array|object

O documento para inserir na coleção.

$options : array

Uma array especificando as opções desejadas.

Nome	Tipo	Descrição
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.
Codec	MongoDB\Codec\DocumentCodec	O codec a ser usado para codificação ou decodificação de documentos. Esta opção é mutuamente exclusiva com a opção typeMap. O padrão é o codec da coleção. A herança de uma opção codec padrão tem precedência sobre a da opção typeMap. Novidade na versão 1.17.
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.
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação. Novidade na versão 1.3.
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 objeto ,MongoDB\InsertOneResult que encapsula um MongoDB\Driver\WriteResult evento.

Erros/exceções

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

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).

Exemplo

A seguinte operação insere um documento na coleção do users no banco de dados do test:

<?php
$collection = (new MongoDB\Client)->test->users;
$insertOneResult = $collection->insertOne([
    'username' => 'admin',
    'email' => 'admin@example.com',
    'name' => 'Admin User',
]);
printf("Inserted %d document(s)\n", $insertOneResult->getInsertedCount());
var_dump($insertOneResult->getInsertedId());

A saída seria então semelhante a:

Inserted 1 document(s)
object(MongoDB\BSON\ObjectId)#11 (1) {
  ["oid"]=>
  string(24) "579a25921f417dd1e5518141"
}

Veja também

• MongoDB\Collection::insertMany()

• MongoDB\Collection::bulkWrite()

• Insira documentos

• inserir referência de comando no manual MongoDB