Class Collection<TSchema>

The name of this collection

The name of the database this collection belongs to

The current index hint for the collection

The namespace of this collection, in the format ${this.dbName}.${this.collectionName}

The current readConcern of the collection. If not explicitly defined for this collection, will be inherited from the parent DB

The current readPreference of the collection. If not explicitly defined for this collection, will be inherited from the parent DB

The current writeConcern of the collection. If not explicitly defined for this collection, will be inherited from the parent DB

Execute an aggregation framework pipeline against the collection, needs MongoDB >= 2.2

Perform a bulkWrite operation without a fluent API

Legal operation types are

• insertOne
• replaceOne
• updateOne
• updateMany
• deleteOne
• deleteMany

If documents passed in do not contain the _id field, one will be added to each of the documents missing it by the driver, mutating the document. This behavior can be overridden by setting the forceServerObjectId flag.

Throws

MongoDriverError if operations is not an array

An estimated count of matching documents in the db to a filter.

NOTE: This method has been deprecated, since it does not provide an accurate count of the documents in a collection. To obtain an accurate count of documents in the collection, use Collection#countDocuments| countDocuments. To obtain an estimated count of all documents in the collection, use Collection#estimatedDocumentCount| estimatedDocumentCount.

Deprecated

use Collection#countDocuments| countDocuments or Collection#estimatedDocumentCount| estimatedDocumentCount instead

Gets the number of documents matching the filter. For a fast count of the total documents in a collection see Collection#estimatedDocumentCount| estimatedDocumentCount.

Due to countDocuments using the $match aggregation pipeline stage, certain query operators cannot be used in countDocuments. This includes the $where and $near query operators, among others. Details can be found in the documentation for the $match aggregation pipeline stage.

Note: When migrating from Collection#count| count to Collection#countDocuments| countDocuments the following query operators must be replaced:

See

• https://www.mongodb.com/docs/manual/reference/operator/query/expr/
• https://www.mongodb.com/docs/manual/reference/operator/query/geoWithin/
• https://www.mongodb.com/docs/manual/reference/operator/query/center/#op._S_center
• https://www.mongodb.com/docs/manual/reference/operator/query/centerSphere/#op._S_centerSphere

Creates an index on the db and collection collection.

Example

const collection = client.db('foo').collection('bar');

await collection.createIndex({ a: 1, b: -1 });

// Alternate syntax for { c: 1, d: -1 } that ensures order of indexes
await collection.createIndex([ [c, 1], [d, -1] ]);

// Equivalent to { e: 1 }
await collection.createIndex('e');

// Equivalent to { f: 1, g: 1 }
await collection.createIndex(['f', 'g'])

// Equivalent to { h: 1, i: -1 }
await collection.createIndex([ { h: 1 }, { i: -1 } ]);

// Equivalent to { j: 1, k: -1, l: 2d }
await collection.createIndex(['j', ['k', -1], { l: '2d' }])
Copy

Creates multiple indexes in the collection, this method is only supported for MongoDB 2.6 or higher. Earlier version of MongoDB will throw a command not supported error.

Note: Unlike Collection#createIndex| createIndex, this function takes in raw index specifications. Index specifications are defined here.

Example

const collection = client.db('foo').collection('bar');
await collection.createIndexes([
  // Simple index on field fizz
  {
    key: { fizz: 1 },
  }
  // wildcard index
  {
    key: { '$**': 1 }
  },
  // named index on darmok and jalad
  {
    key: { darmok: 1, jalad: -1 }
    name: 'tanagra'
  }
]);
Copy

Creates a single search index for the collection.

Remarks

Only available when used against a 7.0+ Atlas cluster.

Creates multiple search indexes for the current collection.

Remarks

Only available when used against a 7.0+ Atlas cluster.

Delete multiple documents from a collection

Delete a document from a collection

The distinct command returns a list of distinct values for the given key across a collection.

Drop the collection from the database, removing it permanently. New accesses will create a new collection.

Drops an index from this collection.

Drops all indexes from this collection.

Deletes a search index by index name.

Remarks

Only available when used against a 7.0+ Atlas cluster.

Gets an estimate of the count of documents in a collection using collection metadata. This will always run a count command on all server versions.

due to an oversight in versions 5.0.0-5.0.8 of MongoDB, the count command, which estimatedDocumentCount uses in its implementation, was not included in v1 of the Stable API, and so users of the Stable API with estimatedDocumentCount are recommended to upgrade their server version to 5.0.9+ or set apiStrict: false to avoid encountering errors.

See

Behavior

Creates a cursor for a filter that can be used to iterate over results from MongoDB

Fetches the first document that matches the filter

Find a document and delete it in one atomic operation. Requires a write lock for the duration of the operation.

Find a document and replace it in one atomic operation. Requires a write lock for the duration of the operation.

Find a document and update it in one atomic operation. Requires a write lock for the duration of the operation.

Retrieve all the indexes on the collection.

Checks if one or more indexes exist on the collection, fails on first non-existing index

Retrieves this collections index info.

Initiate an In order bulk write operation. Operations will be serially executed in the order they are added, creating a new operation for each switch in types.

Throws

MongoNotConnectedError

Remarks

NOTE: MongoClient must be connected prior to calling this method due to a known limitation in this legacy implementation. However, collection.bulkWrite() provides an equivalent API that does not require prior connecting.

Initiate an Out of order batch write operation. All operations will be buffered into insert/update/remove commands executed out of order.

Throws

MongoNotConnectedError

Remarks

NOTE: MongoClient must be connected prior to calling this method due to a known limitation in this legacy implementation. However, collection.bulkWrite() provides an equivalent API that does not require prior connecting.

Inserts an array of documents into MongoDB. If documents passed in do not contain the _id field, one will be added to each of the documents missing it by the driver, mutating the document. This behavior can be overridden by setting the forceServerObjectId flag.

Inserts a single document into MongoDB. If documents passed in do not contain the _id field, one will be added to each of the documents missing it by the driver, mutating the document. This behavior can be overridden by setting the forceServerObjectId flag.

Returns if the collection is a capped collection

Get the list of all indexes information for the collection.

Returns all search indexes for the current collection.

Remarks

Only available when used against a 7.0+ Atlas cluster.

Returns all search indexes for the current collection.

Remarks

Only available when used against a 7.0+ Atlas cluster.

Returns the options of the collection.

Rename the collection.

Remarks

This operation does not inherit options from the Db or MongoClient.

Replace a document in a collection with another document

Update multiple documents in a collection

The value of update can be either:

• UpdateFilter - A document that contains update operator expressions,
• Document[] - an aggregation pipeline.

Update a single document in a collection

The value of update can be either:

• UpdateFilter - A document that contains update operator expressions,
• Document[] - an aggregation pipeline.

Updates a search index by replacing the existing index definition with the provided definition.

Remarks

Only available when used against a 7.0+ Atlas cluster.

Create a new Change Stream, watching for new changes (insertions, updates, replacements, deletions, and invalidations) in this collection.

Remarks

watch() accepts two generic arguments for distinct use cases:

• The first is to override the schema that may be defined for this specific collection
• The second is to override the shape of the change stream document entirely, if it is not provided the type will default to ChangeStreamDocument of the first argument

Example

By just providing the first argument I can type the change to be ChangeStreamDocument<{ _id: number }>

collection.watch<{ _id: number }>()
  .on('change', change => console.log(change._id.toFixed(4)));
Copy

Example

Passing a second argument provides a way to reflect the type changes caused by an advanced pipeline. Here, we are using a pipeline to have MongoDB filter for insert changes only and add a comment. No need start from scratch on the ChangeStreamInsertDocument type! By using an intersection we can save time and ensure defaults remain the same type!

collection
  .watch<Schema, ChangeStreamInsertDocument<Schema> & { comment: string }>([
    { $addFields: { comment: 'big changes' } },
    { $match: { operationType: 'insert' } }
  ])
  .on('change', change => {
    change.comment.startsWith('big');
    change.operationType === 'insert';
    // No need to narrow in code because the generics did that for us!
    expectType<Schema>(change.fullDocument);
  });
Copy

Example

In iterator mode, if a next() call throws a timeout error, it will attempt to resume the change stream. The next call can just be retried after this succeeds.

const changeStream = collection.watch([], { timeoutMS: 100 });
try {
    await changeStream.next();
} catch (e) {
    if (e instanceof MongoOperationTimeoutError && !changeStream.closed) {
      await changeStream.next();
    }
    throw e;
}
Copy

Example

In emitter mode, if the change stream goes timeoutMS without emitting a change event, it will emit an error event that returns a MongoOperationTimeoutError, but will not close the change stream unless the resume attempt fails. There is no need to re-establish change listeners as this will automatically continue emitting change events once the resume attempt completes.

const changeStream = collection.watch([], { timeoutMS: 100 });
changeStream.on('change', console.log);
changeStream.on('error', e => {
    if (e instanceof MongoOperationTimeoutError && !changeStream.closed) {
        // do nothing
    } else {
        changeStream.close();
    }
});
Copy