ANNOUNCEMENT: Voyage AI joins MongoDB to power more accurate and trustworthy AI applications on Atlas.
Learn more
Menu Docs

MongoDB\Collection::insertOne()

MongoDB\Collection::insertOne()

Insere um documento.

function insertOne(
array|object $document,
array $options = []
): MongoDB\InsertOneResult
$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

Sessão do cliente a ser associada à operação.

Novidade na versão 1.3.

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.

Um objeto ,MongoDB\InsertOneResult que encapsula um MongoDB\Driver\WriteResult evento.

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

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

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"
}