Options nos métodos CRUD do MongoDB Driver C# | MongoDB | Ambiente .NET

Options nos métodos CRUD do MongoDB Driver C# | MongoDB | Ambiente .NET

Abaixo está uma doc direta com os principais Options usados nos métodos CRUD do MongoDB Driver C#/.NET. Estou considerando a API atual do driver, onde os métodos CRUD aceitam objetos como InsertOneOptions, FindOptions, UpdateOptions, DeleteOptions, etc. A documentação oficial confirma, por exemplo, que InsertOne() pode receber InsertOneOptions e que Find() pode receber FindOptions para alterar o comportamento da busca. (MongoDB)

Inserir documentos

`InsertOneOptions`

Usado em:

await collection.InsertOneAsync(documento, options);

Propriedade	Tipo	Para que serve
`BypassDocumentValidation`	`bool?`	Ignora as validações configuradas na collection, como JSON Schema validator.
`Comment`	`BsonValue`	Adiciona um comentário à operação, útil para profiler, logs e auditoria.

Exemplo:

var options = new InsertOneOptions
{
    BypassDocumentValidation = true,
    Comment = "Inserindo produto manualmente"
};

await collection.InsertOneAsync(produto, options);

`InsertManyOptions`

Usado em:

await collection.InsertManyAsync(documentos, options);

Propriedade	Tipo	Para que serve
`BypassDocumentValidation`	`bool?`	Ignora validações da collection.
`Comment`	`BsonValue`	Adiciona comentário à operação.
`IsOrdered`	`bool`	Define se os inserts devem ser executados em ordem. Padrão: `true`.

Exemplo:

var options = new InsertManyOptions
{
    IsOrdered = false,
    BypassDocumentValidation = true,
    Comment = "Carga em lote de produtos"
};

await collection.InsertManyAsync(produtos, options);

A documentação oficial lista BypassDocumentValidation e Comment em InsertOneOptions, e adiciona IsOrdered em InsertManyOptions. (MongoDB)

Buscar documentos

`FindOptions<TDocument, TProjection>`

Usado em:

await collection.FindAsync(filter, options);

Propriedade	Tipo	Para que serve
`AllowDiskUse`	`bool?`	Permite uso de disco em operações de ordenação que excedem memória.
`AllowPartialResults`	`bool?`	Permite retornar resultados parciais em consultas contra sharded cluster se algum shard estiver indisponível.
`BatchSize`	`int?`	Define o tamanho dos lotes retornados pelo cursor.
`Collation`	`Collation`	Define regras de comparação de string, como case-insensitive e acentuação.
`Comment`	`BsonValue`	Comentário para profiler/logs.
`CursorType`	`CursorType`	Define o tipo do cursor, como normal ou tailable cursor.
`Hint`	`BsonValue`	Força o uso de um índice específico.
`Let`	`BsonDocument`	Define variáveis para uso em expressões da query.
`Limit`	`int?`	Limita a quantidade de documentos retornados.
`Max`	`BsonDocument`	Define limite superior para uso com índice.
`MaxAwaitTime`	`TimeSpan?`	Tempo máximo de espera para cursor do tipo tailable await.
`MaxTime`	`TimeSpan?`	Tempo máximo de execução da query no servidor.
`Min`	`BsonDocument`	Define limite inferior para uso com índice.
`NoCursorTimeout`	`bool?`	Impede que o cursor expire automaticamente por inatividade.
`Projection`	`ProjectionDefinition<TDocument, TProjection>`	Define quais campos retornar.
`ReturnKey`	`bool?`	Retorna apenas os campos do índice utilizado.
`ShowRecordId`	`bool?`	Retorna o identificador interno do storage engine.
`Skip`	`int?`	Ignora uma quantidade de documentos.
`Sort`	`SortDefinition<TDocument>`	Define ordenação.
`TranslationOptions`	`ExpressionTranslationOptions`	Configura tradução de expressões LINQ/projeções.

Exemplo:

var options = new FindOptions<Produto, Produto>
{
    BatchSize = 100,
    Limit = 20,
    Sort = Builders<Produto>.Sort.Descending(x => x.Preco),
    Collation = new Collation("pt", strength: CollationStrength.Secondary),
    Comment = "Busca paginada de produtos ativos"
};

var cursor = await collection.FindAsync(
    x => x.Ativo,
    options
);

var produtos = await cursor.ToListAsync();

A documentação do driver mostra que Find() recupera documentos por filtro e que seu comportamento pode ser modificado por FindOptions; também lista opções comuns como BatchSize, Collation, Comment, Hint e MaxTime. (MongoDB) A referência da API também lista propriedades herdadas de FindOptionsBase, como AllowDiskUse, BatchSize, Collation, CursorType, Hint, Let, MaxTime, NoCursorTimeout, ReturnKey, ShowRecordId e TranslationOptions. (mongodb.github.io)

Atualizar documentos

`UpdateOptions`

Usado em:

await collection.UpdateOneAsync(filter, update, options);
await collection.UpdateManyAsync(filter, update, options);

Propriedade	Tipo	Para que serve
`ArrayFilters`	`IEnumerable<ArrayFilterDefinition>`	Define filtros para atualizar elementos específicos dentro de arrays.
`BypassDocumentValidation`	`bool?`	Ignora validações da collection.
`Collation`	`Collation`	Define comparação de string para o filtro.
`Comment`	`BsonValue`	Comentário para profiler/logs.
`Hint`	`BsonValue`	Força o uso de um índice.
`IsUpsert`	`bool`	Se `true`, insere um documento caso nenhum seja encontrado.
`Let`	`BsonDocument`	Define variáveis para expressões no update.
`Sort`	`SortDefinition<TDocument>`	Em update de um único documento, define qual documento atualizar quando vários batem no filtro.

Exemplo com upsert:

var filter = Builders<Produto>.Filter.Eq(x => x.Codigo, "P001");

var update = Builders<Produto>.Update
    .Set(x => x.Nome, "Notebook")
    .Set(x => x.Ativo, true);

var options = new UpdateOptions
{
    IsUpsert = true,
    Comment = "Atualização com upsert"
};

await collection.UpdateOneAsync(filter, update, options);

Exemplo com ArrayFilters:

var filter = Builders<Pedido>.Filter.Eq(x => x.Id, pedidoId);

var update = Builders<Pedido>.Update
    .Set("Itens.$[item].Quantidade", 10);

var options = new UpdateOptions
{
    ArrayFilters = new[]
    {
        new BsonDocumentArrayFilterDefinition<BsonDocument>(
            new BsonDocument("item.Sku", "ABC123")
        )
    }
};

await collection.UpdateOneAsync(filter, update, options);

A referência da API define UpdateOptions como opções para atualizar um único documento. (mongodb.github.io) As release notes atuais também registram suporte ao uso de sort em operações de update/replace, útil quando vários documentos correspondem ao filtro e você quer controlar qual será afetado. (MongoDB)

Substituir documentos

`ReplaceOptions`

Usado em:

await collection.ReplaceOneAsync(filter, novoDocumento, options);

Propriedade	Tipo	Para que serve
`BypassDocumentValidation`	`bool?`	Ignora validações da collection.
`Collation`	`Collation`	Define regra de comparação para o filtro.
`Comment`	`BsonValue`	Comentário para profiler/logs.
`Hint`	`BsonValue`	Força uso de índice.
`IsUpsert`	`bool`	Insere o documento se nenhum for encontrado.
`Let`	`BsonDocument`	Define variáveis para a operação.
`Sort`	`SortDefinition<TDocument>`	Define qual documento substituir quando mais de um corresponder ao filtro, se suportado pela versão do driver/servidor.

Exemplo:

var options = new ReplaceOptions
{
    IsUpsert = true,
    Comment = "Replace de produto por código"
};

await collection.ReplaceOneAsync(
    x => x.Codigo == "P001",
    novoProduto,
    options
);

A referência da API lista ReplaceOptions com propriedades como BypassDocumentValidation, Collation, Comment, Hint, IsUpsert e Let. (mongodb.github.io)

Deletar documentos

`DeleteOptions`

Usado em:

await collection.DeleteOneAsync(filter, options);
await collection.DeleteManyAsync(filter, options);

Propriedade	Tipo	Para que serve
`Collation`	`Collation`	Define regra de comparação para o filtro.
`Comment`	`BsonValue`	Comentário para profiler/logs.
`Hint`	`BsonValue`	Força uso de índice.
`Let`	`BsonDocument`	Define variáveis para uso na operação.

Exemplo:

var options = new DeleteOptions
{
    Collation = new Collation("pt", strength: CollationStrength.Secondary),
    Comment = "Removendo produto por nome com collation"
};

await collection.DeleteOneAsync(
    x => x.Nome == "notebook",
    options
);

A referência da API lista DeleteOptions como opções dos métodos delete e mostra as propriedades Collation, Comment, Hint e Let. (mongodb.github.io)

FindOneAndUpdate, FindOneAndReplace e FindOneAndDelete

Esses métodos fazem uma operação atômica de busca + alteração/remoção e podem retornar o documento antes ou depois da alteração.

`FindOneAndUpdateOptions<TDocument, TProjection>`

Usado em:

await collection.FindOneAndUpdateAsync(filter, update, options);

Propriedade	Tipo	Para que serve
`ArrayFilters`	`IEnumerable<ArrayFilterDefinition>`	Filtros para atualizar elementos específicos de arrays.
`BypassDocumentValidation`	`bool?`	Ignora validações da collection.
`Collation`	`Collation`	Define regra de comparação.
`Comment`	`BsonValue`	Comentário para profiler/logs.
`Hint`	`BsonValue`	Força uso de índice.
`IsUpsert`	`bool`	Cria o documento se não encontrar nenhum.
`Let`	`BsonDocument`	Define variáveis para expressões.
`MaxTime`	`TimeSpan?`	Tempo máximo de execução.
`Projection`	`ProjectionDefinition<TDocument, TProjection>`	Define quais campos retornar.
`ReturnDocument`	`ReturnDocument`	Define se retorna o documento antes ou depois da alteração.
`Sort`	`SortDefinition<TDocument>`	Define qual documento afetar quando vários corresponderem ao filtro.

Exemplo:

var options = new FindOneAndUpdateOptions<Produto>
{
    ReturnDocument = ReturnDocument.After,
    IsUpsert = false,
    Sort = Builders<Produto>.Sort.Descending(x => x.CriadoEm),
    Comment = "Atualiza e retorna produto alterado"
};

var produtoAtualizado = await collection.FindOneAndUpdateAsync(
    x => x.Categoria == "Eletrônicos",
    Builders<Produto>.Update.Inc(x => x.Estoque, -1),
    options
);

`FindOneAndReplaceOptions<TDocument, TProjection>`

Usado em:

await collection.FindOneAndReplaceAsync(filter, replacement, options);

Propriedade	Tipo	Para que serve
`BypassDocumentValidation`	`bool?`	Ignora validações da collection.
`Collation`	`Collation`	Define regra de comparação.
`Comment`	`BsonValue`	Comentário para profiler/logs.
`Hint`	`BsonValue`	Força uso de índice.
`IsUpsert`	`bool`	Insere se não encontrar documento.
`Let`	`BsonDocument`	Define variáveis para expressões.
`MaxTime`	`TimeSpan?`	Tempo máximo de execução.
`Projection`	`ProjectionDefinition<TDocument, TProjection>`	Define os campos retornados.
`ReturnDocument`	`ReturnDocument`	Retorna documento antes ou depois do replace.
`Sort`	`SortDefinition<TDocument>`	Define qual documento substituir quando vários corresponderem.

Exemplo:

var options = new FindOneAndReplaceOptions<Produto>
{
    ReturnDocument = ReturnDocument.After,
    IsUpsert = true,
    Comment = "Replace atômico de produto"
};

var produto = await collection.FindOneAndReplaceAsync(
    x => x.Codigo == "P001",
    novoProduto,
    options
);

`FindOneAndDeleteOptions<TDocument, TProjection>`

Usado em:

await collection.FindOneAndDeleteAsync(filter, options);

Propriedade	Tipo	Para que serve
`Collation`	`Collation`	Define regra de comparação.
`Comment`	`BsonValue`	Comentário para profiler/logs.
`Hint`	`BsonValue`	Força uso de índice.
`Let`	`BsonDocument`	Define variáveis para expressões.
`MaxTime`	`TimeSpan?`	Tempo máximo de execução.
`Projection`	`ProjectionDefinition<TDocument, TProjection>`	Define os campos retornados do documento removido.
`Sort`	`SortDefinition<TDocument>`	Define qual documento remover quando vários corresponderem.

Exemplo:

var options = new FindOneAndDeleteOptions<Produto>
{
    Sort = Builders<Produto>.Sort.Ascending(x => x.CriadoEm),
    Projection = Builders<Produto>.Projection
        .Include(x => x.Nome)
        .Include(x => x.Preco),
    Comment = "Remove produto mais antigo da categoria"
};

var produtoRemovido = await collection.FindOneAndDeleteAsync(
    x => x.Categoria == "Promoção",
    options
);

Resumo rápido

Método	Classe de options
`InsertOne` / `InsertOneAsync`	`InsertOneOptions`
`InsertMany` / `InsertManyAsync`	`InsertManyOptions`
`Find` / `FindAsync`	`FindOptions<TDocument, TProjection>`
`UpdateOne` / `UpdateMany`	`UpdateOptions`
`ReplaceOne`	`ReplaceOptions`
`DeleteOne` / `DeleteMany`	`DeleteOptions`
`FindOneAndUpdate`	`FindOneAndUpdateOptions<TDocument, TProjection>`
`FindOneAndReplace`	`FindOneAndReplaceOptions<TDocument, TProjection>`
`FindOneAndDelete`	`FindOneAndDeleteOptions<TDocument, TProjection>`

Exemplo geral

var filter = Builders<Produto>.Filter.Eq(x => x.Codigo, "P001");

var update = Builders<Produto>.Update
    .Set(x => x.Nome, "Notebook Gamer")
    .Inc(x => x.Estoque, 5);

var options = new UpdateOptions
{
    IsUpsert = true,
    BypassDocumentValidation = false,
    Comment = "Atualização de estoque do produto P001"
};

await collection.UpdateOneAsync(filter, update, options);

Inserir documentos​

InsertOneOptions​

InsertManyOptions​

Buscar documentos​

FindOptions<TDocument, TProjection>​

Atualizar documentos​

UpdateOptions​

Substituir documentos​

ReplaceOptions​

Deletar documentos​

DeleteOptions​

FindOneAndUpdate, FindOneAndReplace e FindOneAndDelete​

FindOneAndUpdateOptions<TDocument, TProjection>​

FindOneAndReplaceOptions<TDocument, TProjection>​

FindOneAndDeleteOptions<TDocument, TProjection>​

Resumo rápido​

Exemplo geral​

Inserir documentos

`InsertOneOptions`

`InsertManyOptions`

Buscar documentos

`FindOptions<TDocument, TProjection>`

Atualizar documentos

`UpdateOptions`

Substituir documentos

`ReplaceOptions`

Deletar documentos

`DeleteOptions`

FindOneAndUpdate, FindOneAndReplace e FindOneAndDelete

`FindOneAndUpdateOptions<TDocument, TProjection>`

`FindOneAndReplaceOptions<TDocument, TProjection>`

`FindOneAndDeleteOptions<TDocument, TProjection>`

Resumo rápido

Exemplo geral