Class Collection<T, TId>

Namespace

DataStax.AstraDB.DataApi.Collections

Assembly

DataStax.AstraDB.DataApi.dll

This is the entrypoint for interacting with an existing collection in a Database.

This version handles serialization/deserialization via a custom type T.

Ids are strongly-typed as TId.

public class Collection<T, TId> where T : class

Type Parameters

T

The type of the documents in the collection.

TId

The type of the id field for documents in the collection.

Inheritance

object

Collection<T, TId>

Derived

Collection<T>

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Properties

CollectionName

Access the name of the collection

public string CollectionName { get; }

Property Value

string

Methods

CheckDeserialization(string)

Test method that allows testing how a document will be deserialized from the database.

public T CheckDeserialization(string json)

Parameters

json string

Returns

T

CheckDeserialization(string, CommandOptions)

Test method that allows testing how a document will be deserialized from the database.

public T CheckDeserialization(string json, CommandOptions commandOptions)

Parameters

json string

commandOptions CommandOptions

Returns

T

CheckSerialization(T)

Test method that allows testing how a document will be serialized to the database.

public string CheckSerialization(T document)

Parameters

document T

Returns

string

CheckSerialization(T, CommandOptions)

Test method that allows testing how a document will be serialized to the database.

public string CheckSerialization(T document, CommandOptions commandOptions)

Parameters

document T

commandOptions CommandOptions

Returns

string

CountDocuments(CollectionFilter<T>, int, CollectionCountDocumentsOptions)

Synchronous version of CountDocumentsAsync(CollectionFilter<T>, int, CollectionCountDocumentsOptions)

public int CountDocuments(CollectionFilter<T> filter, int maxDocumentsToCount, CollectionCountDocumentsOptions options = null)

Parameters

filter CollectionFilter<T>

maxDocumentsToCount int

options CollectionCountDocumentsOptions

Returns

int

CountDocumentsAsync(CollectionFilter<T>, int, CollectionCountDocumentsOptions)

Count the documents matching a specified filter, up to a maximum count.

public Task<int> CountDocumentsAsync(CollectionFilter<T> filter, int maxDocumentsToCount, CollectionCountDocumentsOptions options = null)

Parameters

filter CollectionFilter<T>

maxDocumentsToCount int

options CollectionCountDocumentsOptions

Returns

Task<int>

DeleteMany(CollectionFilter<T>, CollectionDeleteManyOptions)

Synchronous version of DeleteManyAsync(CollectionFilter<T>, CollectionDeleteManyOptions)

public DeleteResult DeleteMany(CollectionFilter<T> filter, CollectionDeleteManyOptions options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

options CollectionDeleteManyOptions

Options for the delete operation.

Returns

DeleteResult

The result of the delete operation.

Remarks

Deleting all documents in a collection is not recommended for large collections. However, if needed you can pass null as the filter to delete all documents in the collection.

var deleteResult = await collection.DeleteManyAsync(null);

DeleteManyAsync(CollectionFilter<T>, CollectionDeleteManyOptions)

Delete all documents matching the filter from the collection.

public Task<DeleteResult> DeleteManyAsync(CollectionFilter<T> filter, CollectionDeleteManyOptions options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

options CollectionDeleteManyOptions

Options for the delete operation.

Returns

Task<DeleteResult>

The result of the delete operation.

Remarks

Deleting all documents in a collection is not recommended for large collections. However, if needed you can pass null as the filter to delete all documents in the collection.

var deleteResult = await collection.DeleteManyAsync(null);

DeleteOne(CollectionFilter<T>, CollectionDeleteOneOptions<T>)

Synchronous version of DeleteOneAsync(CollectionFilter<T>, CollectionDeleteOneOptions<T>)

public DeleteResult DeleteOne(CollectionFilter<T> filter, CollectionDeleteOneOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

options CollectionDeleteOneOptions<T>

Options for the delete operation.

Returns

DeleteResult

The result of the delete operation.

DeleteOneAsync(CollectionFilter<T>, CollectionDeleteOneOptions<T>)

Delete a document from the collection. This is similar to FindOneAndDeleteAsync(CollectionFilter<T>, CollectionFindOneAndDeleteOptions<T>) but does not return the deleted document.

public Task<DeleteResult> DeleteOneAsync(CollectionFilter<T> filter, CollectionDeleteOneOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

options CollectionDeleteOneOptions<T>

Options for the delete operation.

Returns

Task<DeleteResult>

The result of the delete operation.

Drop(DropCollectionOptions)

Synchronous version of DropAsync(DropCollectionOptions).

public void Drop(DropCollectionOptions options = null)

Parameters

options DropCollectionOptions

Additional options for the drop operation. Keyspace overriding is not allowed..

DropAsync(DropCollectionOptions)

Drops the collection from the database.

public Task DropAsync(DropCollectionOptions options = null)

Parameters

options DropCollectionOptions

Additional options for the drop operation. Keyspace overriding is not allowed..

Returns

Task

EstimateDocumentCount(CollectionEstimateDocumentCountOptions)

Synchronous version of EstimateDocumentCountAsync(CollectionEstimateDocumentCountOptions)

public int EstimateDocumentCount(CollectionEstimateDocumentCountOptions options = null)

Parameters

options CollectionEstimateDocumentCountOptions

Options for the estimate operation

Returns

int

EstimateDocumentCountAsync(CollectionEstimateDocumentCountOptions)

Estimate the number of documents in the collection.

public Task<int> EstimateDocumentCountAsync(CollectionEstimateDocumentCountOptions options = null)

Parameters

options CollectionEstimateDocumentCountOptions

Options for the estimate operation

Returns

Task<int>

Find(CollectionFilter<T>, CollectionFindOptions<T>)

Find documents in the collection.

The Find() methods return a CollectionFindCursor<T, TResult> object that can be used to further structure the query by adding Sort, Projection, Skip, Limit, etc. to affect the final results.

The CollectionFindCursor<T, TResult> object can be directly enumerated both synchronously and asynchronously.

public CollectionFindCursor<T> Find(CollectionFilter<T> filter, CollectionFindOptions<T> options = null)

Parameters

filter CollectionFilter<T>

options CollectionFindOptions<T>

Returns

CollectionFindCursor<T>

Examples

Synchronous Enumeration:

var cursor = collection.Find();
foreach (var document in cursor)
{
    // Process document
}

Asynchronous Enumeration:

var results = collection.Find();
await foreach (var document in results)
{
    // Process document
}

Remarks

Timeouts passed in the CollectionFindOptions<T> (ConnectionTimeout and RequestTimeout) will be used for each batched request to the API, however BulkOperationCancellationToken settings are ignored due to the nature of Enumeration. If you need to enforce a timeout for the entire operation, you can pass a CancellationToken to GetAsyncEnumerator.

Find(CollectionFindOptions<T>)

Find documents in the collection.

The Find() methods return a CollectionFindCursor<T, TResult> object that can be used to further structure the query by adding Sort, Projection, Skip, Limit, etc. to affect the final results.

The CollectionFindCursor<T, TResult> object can be directly enumerated both synchronously and asynchronously.

public CollectionFindCursor<T> Find(CollectionFindOptions<T> options = null)

Parameters

options CollectionFindOptions<T>

Returns

CollectionFindCursor<T>

Examples

Synchronous Enumeration:

var cursor = collection.Find();
foreach (var document in cursor)
{
    // Process document
}

Asynchronous Enumeration:

var results = collection.Find();
await foreach (var document in results)
{
    // Process document
}

Remarks

Timeouts passed in the CollectionFindOptions<T> (ConnectionTimeout and RequestTimeout) will be used for each batched request to the API, however BulkOperationCancellationToken settings are ignored due to the nature of Enumeration. If you need to enforce a timeout for the entire operation, you can pass a CancellationToken to GetAsyncEnumerator.

FindAndRerank(CollectionFilter<T>, CollectionFindAndRerankOptions<T>)

Run a find-and-rerank query to find documents in the collection.

The FindAndRerank() methods return a CollectionFindAndRerankCursor<T, TResult> object that can be used to further structure the query by specifying detail of the reranking step and adding Sort, Projection, Limit, etc. to affect the final results.

The CollectionFindAndRerankCursor<T, TResult> object can be directly enumerated both synchronously and asynchronously.

public CollectionFindAndRerankCursor<T> FindAndRerank(CollectionFilter<T> filter, CollectionFindAndRerankOptions<T> options = null)

Parameters

filter CollectionFilter<T>

options CollectionFindAndRerankOptions<T>

Returns

CollectionFindAndRerankCursor<T>

Examples

Synchronous Enumeration:

var cursor = collection.FindAndRerank()
    .Sort(
        Builders<MyDocument>.CollectionFindAndRerankSort.Hybrid(
            "a tree on a grassy hillside"
        )
    );

foreach (var item in cursor)
{
    // Process item.Document
}

Asynchronous Enumeration:

var cursor = collection.FindAndRerank()
    .Sort(
        Builders<MyDocument>.CollectionFindAndRerankSort.Hybrid(
            "a tree on a grassy hillside"
        )
    );
await foreach (var item in results)
{
    // Process item.Document
}

Remarks

Timeouts passed in the CommandOptions (ConnectionTimeout and RequestTimeout) will be used for each batched request to the API, however BulkOperationCancellationToken settings are ignored due to the nature of Enumeration. If you need to enforce a timeout for the entire operation, you can pass a CancellationToken to GetAsyncEnumerator.

FindAndRerank(CollectionFindAndRerankOptions<T>)

Run a find-and-rerank query to find documents in the collection.

The FindAndRerank() methods return a CollectionFindAndRerankCursor<T, TResult> object that can be used to further structure the query by specifying detail of the reranking step and adding Sort, Projection, Limit, etc. to affect the final results.

The CollectionFindAndRerankCursor<T, TResult> object can be directly enumerated both synchronously and asynchronously.

public CollectionFindAndRerankCursor<T> FindAndRerank(CollectionFindAndRerankOptions<T> options = null)

Parameters

options CollectionFindAndRerankOptions<T>

Returns

CollectionFindAndRerankCursor<T>

Examples

Synchronous Enumeration:

var cursor = collection.FindAndRerank()
    .Sort(
        Builders<MyDocument>.CollectionFindAndRerankSort.Hybrid(
            "a tree on a grassy hillside"
        )
    );

foreach (var item in cursor)
{
    // Process item.Document
}

Asynchronous Enumeration:

var cursor = collection.FindAndRerank()
    .Sort(
        Builders<MyDocument>.CollectionFindAndRerankSort.Hybrid(
            "a tree on a grassy hillside"
        )
    );
await foreach (var item in results)
{
    // Process item.Document
}

Remarks

Timeouts passed in the CommandOptions (ConnectionTimeout and RequestTimeout) will be used for each batched request to the API, however BulkOperationCancellationToken settings are ignored due to the nature of Enumeration. If you need to enforce a timeout for the entire operation, you can pass a CancellationToken to GetAsyncEnumerator.

FindAndRerank<TResult>(CollectionFilter<T>, CollectionFindAndRerankOptions<T>)

Run a find-and-rerank query to find documents in the collection.

The FindAndRerank() methods return a CollectionFindAndRerankCursor<T, TResult> object that can be used to further structure the query by specifying detail of the reranking step and adding Sort, Projection, Limit, etc. to affect the final results.

The CollectionFindAndRerankCursor<T, TResult> object can be directly enumerated both synchronously and asynchronously.

public CollectionFindAndRerankCursor<T, RerankedResult<TResult>> FindAndRerank<TResult>(CollectionFilter<T> filter, CollectionFindAndRerankOptions<T> options = null) where TResult : class

Parameters

filter CollectionFilter<T>

options CollectionFindAndRerankOptions<T>

Returns

CollectionFindAndRerankCursor<T, RerankedResult<TResult>>

Type Parameters

TResult

Examples

Synchronous Enumeration:

var cursor = collection.FindAndRerank()
    .Sort(
        Builders<MyDocument>.CollectionFindAndRerankSort.Hybrid(
            "a tree on a grassy hillside"
        )
    );

foreach (var item in cursor)
{
    // Process item.Document
}

Asynchronous Enumeration:

var cursor = collection.FindAndRerank()
    .Sort(
        Builders<MyDocument>.CollectionFindAndRerankSort.Hybrid(
            "a tree on a grassy hillside"
        )
    );
await foreach (var item in results)
{
    // Process item.Document
}

Remarks

Timeouts passed in the CommandOptions (ConnectionTimeout and RequestTimeout) will be used for each batched request to the API, however BulkOperationCancellationToken settings are ignored due to the nature of Enumeration. If you need to enforce a timeout for the entire operation, you can pass a CancellationToken to GetAsyncEnumerator.

FindAndRerank<TResult>(CollectionFindAndRerankOptions<T>)

Run a find-and-rerank query to find documents in the collection.

The FindAndRerank() methods return a CollectionFindAndRerankCursor<T, TResult> object that can be used to further structure the query by specifying detail of the reranking step and adding Sort, Projection, Limit, etc. to affect the final results.

The CollectionFindAndRerankCursor<T, TResult> object can be directly enumerated both synchronously and asynchronously.

public CollectionFindAndRerankCursor<T, RerankedResult<TResult>> FindAndRerank<TResult>(CollectionFindAndRerankOptions<T> options = null) where TResult : class

Parameters

options CollectionFindAndRerankOptions<T>

Returns

CollectionFindAndRerankCursor<T, RerankedResult<TResult>>

Type Parameters

TResult

Examples

Synchronous Enumeration:

var cursor = collection.FindAndRerank()
    .Sort(
        Builders<MyDocument>.CollectionFindAndRerankSort.Hybrid(
            "a tree on a grassy hillside"
        )
    );

foreach (var item in cursor)
{
    // Process item.Document
}

Asynchronous Enumeration:

var cursor = collection.FindAndRerank()
    .Sort(
        Builders<MyDocument>.CollectionFindAndRerankSort.Hybrid(
            "a tree on a grassy hillside"
        )
    );
await foreach (var item in results)
{
    // Process item.Document
}

Remarks

Timeouts passed in the CommandOptions (ConnectionTimeout and RequestTimeout) will be used for each batched request to the API, however BulkOperationCancellationToken settings are ignored due to the nature of Enumeration. If you need to enforce a timeout for the entire operation, you can pass a CancellationToken to GetAsyncEnumerator.

FindOne(CollectionFilter<T>, CollectionFindOneOptions<T>)

Returns a single document from the collection based on the provided filter

public T FindOne(CollectionFilter<T> filter, CollectionFindOneOptions<T> options = null)

Parameters

filter CollectionFilter<T>

options CollectionFindOneOptions<T>

Returns

T

Examples

var filter = Builders<DifferentIdsObject>.CollectionFilter.Eq(d => d.TheId, 1);
var result = await collection.FindOneAsync(filter);

FindOne(CollectionFindOneOptions<T>)

Returns a single document from the collection based on the provided CollectionFindOneOptions<T>. This will return the first document found, most often used in conjunction with Sort. See CollectionFindOneOptions<T> for more details on sorting, projecting and the other options for finding a document.

public T FindOne(CollectionFindOneOptions<T> options = null)

Parameters

options CollectionFindOneOptions<T>

Returns

T

FindOneAndDelete(CollectionFilter<T>, CollectionFindOneAndDeleteOptions<T>)

Synchronous version of FindOneAndDeleteAsync(CollectionFilter<T>, CollectionFindOneAndDeleteOptions<T>)

public T FindOneAndDelete(CollectionFilter<T> filter, CollectionFindOneAndDeleteOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

options CollectionFindOneAndDeleteOptions<T>

Options for the find and delete operation.

Returns

T

The deleted document, or null if not found

FindOneAndDeleteAsync(CollectionFilter<T>, CollectionFindOneAndDeleteOptions<T>)

Find a document and delete it from the collection. This is similar to DeleteOneAsync(CollectionFilter<T>, CollectionDeleteOneOptions<T>) but returns the deleted document.

public Task<T> FindOneAndDeleteAsync(CollectionFilter<T> filter, CollectionFindOneAndDeleteOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

options CollectionFindOneAndDeleteOptions<T>

Options for the find and delete operation.

Returns

Task<T>

The deleted document, or null if not found

FindOneAndDeleteAsync<TResult>(CollectionFilter<T>, CollectionFindOneAndDeleteOptions<T>)

Find a document and delete it from the collection. This is similar to DeleteOneAsync(CollectionFilter<T>, CollectionDeleteOneOptions<T>) but returns the deleted document.

public Task<TResult> FindOneAndDeleteAsync<TResult>(CollectionFilter<T> filter, CollectionFindOneAndDeleteOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

options CollectionFindOneAndDeleteOptions<T>

Options for the find and delete operation.

Returns

Task<TResult>

The deleted document, or null if not found

Type Parameters

TResult

Remarks

The FindOneAndDeleteAsync alternatives that accept a TResult type parameter allow for deserializing the resulting document as a different type (most commonly used when using projection to return a subset of fields)

FindOneAndDelete<TResult>(CollectionFilter<T>, CollectionFindOneAndDeleteOptions<T>)

Synchronous version of FindOneAndDeleteAsync<TResult>(CollectionFilter<T>, CollectionFindOneAndDeleteOptions<T>)

public TResult FindOneAndDelete<TResult>(CollectionFilter<T> filter, CollectionFindOneAndDeleteOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

options CollectionFindOneAndDeleteOptions<T>

Options for the find and delete operation.

Returns

TResult

The deleted document, or null if not found

Type Parameters

TResult

Remarks

The FindOneAndDeleteAsync alternatives that accept a TResult type parameter allow for deserializing the resulting document as a different type (most commonly used when using projection to return a subset of fields)

FindOneAndReplace(CollectionFilter<T>, T, CollectionFindOneAndReplaceOptions<T>)

Synchronous version of FindOneAndReplaceAsync(CollectionFilter<T>, T, CollectionFindOneAndReplaceOptions<T>)

public T FindOneAndReplace(CollectionFilter<T> filter, T replacement, CollectionFindOneAndReplaceOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

replacement T

The replacement document.

options CollectionFindOneAndReplaceOptions<T>

Options for the find and replace operation.

Returns

T

The replaced document, or null if not found

FindOneAndReplaceAsync(CollectionFilter<T>, T, CollectionFindOneAndReplaceOptions<T>)

Find a document and replace it with the provided replacement. This is similar to ReplaceOneAsync(CollectionFilter<T>, T, CollectionReplaceOneOptions<T>) but returns the replaced document.

public Task<T> FindOneAndReplaceAsync(CollectionFilter<T> filter, T replacement, CollectionFindOneAndReplaceOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

replacement T

The replacement document.

options CollectionFindOneAndReplaceOptions<T>

Options for the find and replace operation.

Returns

Task<T>

The replaced document, or null if not found

FindOneAndReplaceAsync<TResult>(CollectionFilter<T>, T, CollectionFindOneAndReplaceOptions<T>)

Find a document and replace it with the provided replacement. This is similar to ReplaceOneAsync(CollectionFilter<T>, T, CollectionReplaceOneOptions<T>) but returns the replaced document.

public Task<TResult> FindOneAndReplaceAsync<TResult>(CollectionFilter<T> filter, T replacement, CollectionFindOneAndReplaceOptions<T> options = null) where TResult : class

Parameters

filter CollectionFilter<T>

The filter to match documents.

replacement T

The replacement document.

options CollectionFindOneAndReplaceOptions<T>

Options for the find and replace operation.

Returns

Task<TResult>

The replaced document, or null if not found

Type Parameters

TResult

Remarks

The FindOneAndReplaceAsync alternatives that accept a TResult type parameter allow for deserializing the resulting document as a different type (most commonly used when using projection to return a subset of fields)

FindOneAndReplace<TResult>(CollectionFilter<T>, T, CollectionFindOneAndReplaceOptions<T>)

Synchronous version of FindOneAndReplaceAsync<TResult>(CollectionFilter<T>, T, CollectionFindOneAndReplaceOptions<T>)

public TResult FindOneAndReplace<TResult>(CollectionFilter<T> filter, T replacement, CollectionFindOneAndReplaceOptions<T> options = null) where TResult : class

Parameters

filter CollectionFilter<T>

The filter to match documents.

replacement T

The replacement document.

options CollectionFindOneAndReplaceOptions<T>

Options for the find and replace operation.

Returns

TResult

The replaced document, or null if not found

Type Parameters

TResult

Remarks

The FindOneAndReplaceAsync alternatives that accept a TResult type parameter allow for deserializing the resulting document as a different type (most commonly used when using projection to return a subset of fields)

FindOneAndUpdate(CollectionFilter<T>, UpdateBuilder<T>, CollectionFindOneAndUpdateOptions<T>)

Synchronous version of FindOneAndUpdateAsync(CollectionFilter<T>, UpdateBuilder<T>, CollectionFindOneAndUpdateOptions<T>)

public T FindOneAndUpdate(CollectionFilter<T> filter, UpdateBuilder<T> update, CollectionFindOneAndUpdateOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

update UpdateBuilder<T>

The update operations to apply.

options CollectionFindOneAndUpdateOptions<T>

Options for the find and update operation.

Returns

T

The updated document, or null if not found

Examples

var updater = Builders<SimpleObject>.CollectionUpdate;
var combinedUpdate = updater.Combine(
    updater.Set(so => so.Properties.PropertyOne, "Updated"),
    updater.Unset(so => so.Properties.PropertyTwo)
);
var result = await collection.FindOneAndUpdateAsync(filter, combinedUpdate);

FindOneAndUpdateAsync(CollectionFilter<T>, UpdateBuilder<T>, CollectionFindOneAndUpdateOptions<T>)

Find a document and update it using the provided updates. This is similar to UpdateOneAsync(CollectionFilter<T>, UpdateBuilder<T>, CollectionUpdateOneOptions<T>) but returns the updated document.

public Task<T> FindOneAndUpdateAsync(CollectionFilter<T> filter, UpdateBuilder<T> update, CollectionFindOneAndUpdateOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

update UpdateBuilder<T>

The update operations to apply.

options CollectionFindOneAndUpdateOptions<T>

Options for the find and update operation.

Returns

Task<T>

The updated document, or null if not found

Examples

var updater = Builders<SimpleObject>.CollectionUpdate;
var combinedUpdate = updater.Combine(
    updater.Set(so => so.Properties.PropertyOne, "Updated"),
    updater.Unset(so => so.Properties.PropertyTwo)
);
var result = await collection.FindOneAndUpdateAsync(filter, combinedUpdate);

FindOneAndUpdateAsync<TResult>(CollectionFilter<T>, UpdateBuilder<T>, CollectionFindOneAndUpdateOptions<T>)

Find a document and update it using the provided updates. This is similar to UpdateOneAsync(CollectionFilter<T>, UpdateBuilder<T>, CollectionUpdateOneOptions<T>) but returns the updated document.

public Task<TResult> FindOneAndUpdateAsync<TResult>(CollectionFilter<T> filter, UpdateBuilder<T> update, CollectionFindOneAndUpdateOptions<T> options = null) where TResult : class

Parameters

filter CollectionFilter<T>

The filter to match documents.

update UpdateBuilder<T>

The update operations to apply.

options CollectionFindOneAndUpdateOptions<T>

Options for the find and update operation.

Returns

Task<TResult>

The updated document, or null if not found

Type Parameters

TResult

Examples

var updater = Builders<SimpleObject>.CollectionUpdate;
var combinedUpdate = updater.Combine(
    updater.Set(so => so.Properties.PropertyOne, "Updated"),
    updater.Unset(so => so.Properties.PropertyTwo)
);
var result = await collection.FindOneAndUpdateAsync(filter, combinedUpdate);

Remarks

The FindOneAndUpdateAsync alternatives that accept a TResult type parameter allow for deserializing the resulting document as a different type (most commonly used when using projection to return a subset of fields)

FindOneAndUpdate<TResult>(CollectionFilter<T>, UpdateBuilder<T>, CollectionFindOneAndUpdateOptions<T>)

Synchronous version of FindOneAndUpdateAsync<TResult>(CollectionFilter<T>, UpdateBuilder<T>, CollectionFindOneAndUpdateOptions<T>)

public TResult FindOneAndUpdate<TResult>(CollectionFilter<T> filter, UpdateBuilder<T> update, CollectionFindOneAndUpdateOptions<T> options = null) where TResult : class

Parameters

filter CollectionFilter<T>

The filter to match documents.

update UpdateBuilder<T>

The update operations to apply.

options CollectionFindOneAndUpdateOptions<T>

Options for the find and update operation.

Returns

TResult

The updated document, or null if not found

Type Parameters

TResult

Examples

var updater = Builders<SimpleObject>.CollectionUpdate;
var combinedUpdate = updater.Combine(
    updater.Set(so => so.Properties.PropertyOne, "Updated"),
    updater.Unset(so => so.Properties.PropertyTwo)
);
var result = await collection.FindOneAndUpdateAsync(filter, combinedUpdate);

Remarks

The FindOneAndUpdateAsync alternatives that accept a TResult type parameter allow for deserializing the resulting document as a different type (most commonly used when using projection to return a subset of fields)

FindOneAsync(CollectionFilter<T>, CollectionFindOneOptions<T>)

Returns a single document from the collection based on the provided filter

public Task<T> FindOneAsync(CollectionFilter<T> filter, CollectionFindOneOptions<T> options = null)

Parameters

filter CollectionFilter<T>

options CollectionFindOneOptions<T>

Returns

Task<T>

Examples

var filter = Builders<DifferentIdsObject>.CollectionFilter.Eq(d => d.TheId, 1);
var result = await collection.FindOneAsync(filter);

FindOneAsync(CollectionFindOneOptions<T>)

Returns a single document from the collection based on the provided CollectionFindOneOptions<T>. This will return the first document found, most often used in conjunction with Sort. See CollectionFindOneOptions<T> for more details on sorting, projecting and the other options for finding a document.

public Task<T> FindOneAsync(CollectionFindOneOptions<T> options = null)

Parameters

options CollectionFindOneOptions<T>

Returns

Task<T>

FindOneAsync<TResult>(CollectionFilter<T>, CollectionFindOneOptions<T>)

Returns a single document from the collection.

public Task<TResult> FindOneAsync<TResult>(CollectionFilter<T> filter, CollectionFindOneOptions<T> options = null) where TResult : class

Parameters

filter CollectionFilter<T>

options CollectionFindOneOptions<T>

Returns

Task<TResult>

Type Parameters

TResult

Examples

var exclusiveProjection = Builders<FullObject>.Projection
    .Exclude("PropertyTwo");
var findOptions = new CollectionFindOneOptions<FullObject>()
{
    Projection = exclusiveProjection
};
var result = await collection.FindOneAsync<ObjectWithoutPropertyTwo>(findOptions);

Remarks

The FindOneAsync alternatives that accept a TResult type parameter allow for deserializing the document as a different type (most commonly used when using projection to return a subset of fields)

FindOneAsync<TResult>(CollectionFindOneOptions<T>)

Returns a single document from the collection.

public Task<TResult> FindOneAsync<TResult>(CollectionFindOneOptions<T> options = null) where TResult : class

Parameters

options CollectionFindOneOptions<T>

Returns

Task<TResult>

Type Parameters

TResult

Examples

var exclusiveProjection = Builders<FullObject>.Projection
    .Exclude("PropertyTwo");
var findOptions = new CollectionFindOneOptions<FullObject>()
{
    Projection = exclusiveProjection
};
var result = await collection.FindOneAsync<ObjectWithoutPropertyTwo>(findOptions);

Remarks

The FindOneAsync alternatives that accept a TResult type parameter allow for deserializing the document as a different type (most commonly used when using projection to return a subset of fields)

FindOne<TResult>(CollectionFilter<T>, CollectionFindOneOptions<T>)

Returns a single document from the collection.

public TResult FindOne<TResult>(CollectionFilter<T> filter, CollectionFindOneOptions<T> options = null) where TResult : class

Parameters

filter CollectionFilter<T>

options CollectionFindOneOptions<T>

Returns

TResult

Type Parameters

TResult

Examples

var exclusiveProjection = Builders<FullObject>.Projection
    .Exclude("PropertyTwo");
var findOptions = new CollectionFindOneOptions<FullObject>()
{
    Projection = exclusiveProjection
};
var result = await collection.FindOneAsync<ObjectWithoutPropertyTwo>(findOptions);

Remarks

The FindOneAsync alternatives that accept a TResult type parameter allow for deserializing the document as a different type (most commonly used when using projection to return a subset of fields)

FindOne<TResult>(CollectionFindOneOptions<T>)

Returns a single document from the collection.

public TResult FindOne<TResult>(CollectionFindOneOptions<T> options = null) where TResult : class

Parameters

options CollectionFindOneOptions<T>

Returns

TResult

Type Parameters

TResult

Examples

var exclusiveProjection = Builders<FullObject>.Projection
    .Exclude("PropertyTwo");
var findOptions = new CollectionFindOneOptions<FullObject>()
{
    Projection = exclusiveProjection
};
var result = await collection.FindOneAsync<ObjectWithoutPropertyTwo>(findOptions);

Remarks

The FindOneAsync alternatives that accept a TResult type parameter allow for deserializing the document as a different type (most commonly used when using projection to return a subset of fields)

Find<TResult>(CollectionFilter<T>, CollectionFindOptions<T>)

Find documents in the collection.

The Find() methods return a CollectionFindCursor<T, TResult> object that can be used to further structure the query by adding Sort, Projection, Skip, Limit, etc. to affect the final results.

The CollectionFindCursor<T, TResult> object can be directly enumerated both synchronously and asynchronously.

public CollectionFindCursor<T, TResult> Find<TResult>(CollectionFilter<T> filter, CollectionFindOptions<T> options = null) where TResult : class

Parameters

filter CollectionFilter<T>

options CollectionFindOptions<T>

Returns

CollectionFindCursor<T, TResult>

Type Parameters

TResult

Examples

Synchronous Enumeration:

var cursor = collection.Find();
foreach (var document in cursor)
{
    // Process document
}

Asynchronous Enumeration:

var results = collection.Find();
await foreach (var document in results)
{
    // Process document
}

Remarks

Timeouts passed in the CollectionFindOptions<T> (ConnectionTimeout and RequestTimeout) will be used for each batched request to the API, however BulkOperationCancellationToken settings are ignored due to the nature of Enumeration. If you need to enforce a timeout for the entire operation, you can pass a CancellationToken to GetAsyncEnumerator.

Find<TResult>(CollectionFindOptions<T>)

Find documents in the collection.

The Find() methods return a CollectionFindCursor<T, TResult> object that can be used to further structure the query by adding Sort, Projection, Skip, Limit, etc. to affect the final results.

The CollectionFindCursor<T, TResult> object can be directly enumerated both synchronously and asynchronously.

public CollectionFindCursor<T, TResult> Find<TResult>(CollectionFindOptions<T> options = null) where TResult : class

Parameters

options CollectionFindOptions<T>

Returns

CollectionFindCursor<T, TResult>

Type Parameters

TResult

Examples

Synchronous Enumeration:

var cursor = collection.Find();
foreach (var document in cursor)
{
    // Process document
}

Asynchronous Enumeration:

var results = collection.Find();
await foreach (var document in results)
{
    // Process document
}

Remarks

Timeouts passed in the CollectionFindOptions<T> (ConnectionTimeout and RequestTimeout) will be used for each batched request to the API, however BulkOperationCancellationToken settings are ignored due to the nature of Enumeration. If you need to enforce a timeout for the entire operation, you can pass a CancellationToken to GetAsyncEnumerator.

InsertMany(List<T>, CollectionInsertManyOptions)

Synchronous version of InsertManyAsync(List<T>, CollectionInsertManyOptions)

public CollectionInsertManyResult<TId> InsertMany(List<T> documents, CollectionInsertManyOptions options = null)

Parameters

documents List<T>

The list of documents to insert.

options CollectionInsertManyOptions

Allows specifying the insertion chunk size, ordered/unordered mode, concurrency, as well as other generic command-execution options.

Returns

CollectionInsertManyResult<TId>

InsertManyAsync(List<T>, CollectionInsertManyOptions)

Insert multiple documents into the collection.

public Task<CollectionInsertManyResult<TId>> InsertManyAsync(List<T> documents, CollectionInsertManyOptions options = null)

Parameters

documents List<T>

The list of documents to insert.

options CollectionInsertManyOptions

Allows specifying the insertion chunk size, ordered/unordered mode, concurrency, as well as other generic command-execution options.

Returns

Task<CollectionInsertManyResult<TId>>

InsertOne(T, CollectionInsertOneOptions)

Synchronous version of InsertOneAsync(T, CollectionInsertOneOptions)

public CollectionInsertOneResult<TId> InsertOne(T document, CollectionInsertOneOptions options = null)

Parameters

document T

The document to insert.

options CollectionInsertOneOptions

Options for the insert operation.

Returns

CollectionInsertOneResult<TId>

InsertOneAsync(T, CollectionInsertOneOptions)

Insert a document into the collection.

public Task<CollectionInsertOneResult<TId>> InsertOneAsync(T document, CollectionInsertOneOptions options = null)

Parameters

document T

The document to insert.

options CollectionInsertOneOptions

Options for the insert operation.

Returns

Task<CollectionInsertOneResult<TId>>

ReplaceOne(CollectionFilter<T>, T, CollectionReplaceOneOptions<T>)

Synchronous version of ReplaceOneAsync(CollectionFilter<T>, T, CollectionReplaceOneOptions<T>)

public UpdateResult ReplaceOne(CollectionFilter<T> filter, T replacement, CollectionReplaceOneOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

replacement T

The replacement document.

options CollectionReplaceOneOptions<T>

Options for the replace operation.

Returns

UpdateResult

The result of the replace operation.

ReplaceOneAsync(CollectionFilter<T>, T, CollectionReplaceOneOptions<T>)

Replace a document in the collection that matches the provided filter with the provided replacement. This is similar to FindOneAndReplaceAsync(CollectionFilter<T>, T, CollectionFindOneAndReplaceOptions<T>) but does not return the replaced document.

public Task<UpdateResult> ReplaceOneAsync(CollectionFilter<T> filter, T replacement, CollectionReplaceOneOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

replacement T

The replacement document.

options CollectionReplaceOneOptions<T>

Options for the replace operation.

Returns

Task<UpdateResult>

The result of the replace operation.

UpdateMany(CollectionFilter<T>, UpdateBuilder<T>, CollectionUpdateManyOptions)

Synchronous version of UpdateManyAsync(CollectionFilter<T>, UpdateBuilder<T>, CollectionUpdateManyOptions)

public UpdateResult UpdateMany(CollectionFilter<T> filter, UpdateBuilder<T> update, CollectionUpdateManyOptions options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

update UpdateBuilder<T>

The update operations to apply.

options CollectionUpdateManyOptions

Options for the update operation.

Returns

UpdateResult

The result of the update operation.

UpdateManyAsync(CollectionFilter<T>, UpdateBuilder<T>, CollectionUpdateManyOptions)

Update all documents matching the filter by applying the provided updates.

public Task<UpdateResult> UpdateManyAsync(CollectionFilter<T> filter, UpdateBuilder<T> update, CollectionUpdateManyOptions options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

update UpdateBuilder<T>

The update operations to apply.

options CollectionUpdateManyOptions

Options for the update operation.

Returns

Task<UpdateResult>

The result of the update operation.

UpdateOne(CollectionFilter<T>, UpdateBuilder<T>, CollectionUpdateOneOptions<T>)

Synchronous version of UpdateOneAsync(CollectionFilter<T>, UpdateBuilder<T>, CollectionUpdateOneOptions<T>)

public UpdateResult UpdateOne(CollectionFilter<T> filter, UpdateBuilder<T> update, CollectionUpdateOneOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

update UpdateBuilder<T>

The update operations to apply.

options CollectionUpdateOneOptions<T>

Options for the update operation.

Returns

UpdateResult

The result of the update operation.

UpdateOneAsync(CollectionFilter<T>, UpdateBuilder<T>, CollectionUpdateOneOptions<T>)

Update a single document in the collection using the provided filter and update builder.

This is similar to FindOneAndUpdateAsync(CollectionFilter<T>, UpdateBuilder<T>, CollectionFindOneAndUpdateOptions<T>) but does not return the updated document.

public Task<UpdateResult> UpdateOneAsync(CollectionFilter<T> filter, UpdateBuilder<T> update, CollectionUpdateOneOptions<T> options = null)

Parameters

filter CollectionFilter<T>

The filter to match documents.

update UpdateBuilder<T>

The update operations to apply.

options CollectionUpdateOneOptions<T>

Options for the update operation.

Returns

Task<UpdateResult>

The result of the update operation.