Class Collection<TSchema>

The Collection class is an internal class that embodies a MongoDB collection allowing for insert/find/update/delete and other command operation on that MongoDB collection.Collection类是一个内部类,它体现了一个MongoDB集合,允许对该MongoDB集合进行插入/查找/更新/删除和其他命令操作。

COLLECTION Cannot directly be instantiatedCOLLECTION不能直接实例化

import { MongoClient } from 'mongodb';

interface Pet {
name: string;
kind: 'dog' | 'cat' | 'fish';
}

const client = new MongoClient('mongodb://localhost:27017');
const pets = client.db().collection<Pet>('pets');

const petCursor = pets.find();

for await (const pet of petCursor) {
console.log(`${pet.name} is a ${pet.kind}!`);
}

Type Parameters

Properties

db: Db

Get the database object for the collection.获取集合的数据库对象。

Accessors

  • get collectionName(): string
  • The name of this collection此集合的名称

    Returns string

  • get dbName(): string
  • The name of the database this collection belongs to此集合所属的数据库的名称

    Returns string

  • get namespace(): string
  • The namespace of this collection, in the format 集合的命名空间,格式为:${this.dbName}.${this.collectionName}

    Returns string

  • get readConcern(): undefined | ReadConcern
  • The current readConcern of the collection. If not explicitly defined for this collection, will be inherited from the parent DB该集合的当前读取关注。如果没有为此集合明确定义,将从父数据库继承

    Returns undefined | ReadConcern

  • get readPreference(): undefined | ReadPreference
  • The current readPreference of the collection. If not explicitly defined for this collection, will be inherited from the parent DB集合的当前readPreference。如果没有为此集合明确定义,将从父数据库继承

    Returns undefined | ReadPreference

  • get writeConcern(): undefined | WriteConcern
  • The current writeConcern of the collection. If not explicitly defined for this collection, will be inherited from the parent DB该集合的当前写入关注。如果没有为此集合明确定义,将从父数据库继承

    Returns undefined | WriteConcern

Methods

  • Perform a bulkWrite operation without a fluent API在没有流畅的API的情况下执行bulkWrite操作

    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.如果传入的文档不包含_id字段,驱动程序将向每个缺少该字段的文档添加一个_id字段,从而对文档进行修改。可以通过设置forceServerObjectId标志来覆盖此行为。

    Parameters

    Returns Promise<BulkWriteResult>

    MongoDriverError if operations is not an array如果操作不是数组,则发生MongoDriverError

  • 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 countDocuments. 要获得集合中文档的准确计数,请使用countDocumentsTo obtain an estimated count of all documents in the collection, use estimatedDocumentCount.要获得集合中所有文档的估计计数,请使用estimatedDocumentCount

    Parameters

    • filter: Filter<TSchema> = {}

      The filter for the count.计数筛选器。

    • options: CountOptions = {}

      Optional settings for the command命令的可选设置

    Returns Promise<number>

    use countDocuments or estimatedDocumentCount instead改用countDocumentsestimatedDocumentCount

  • Gets the number of documents matching the filter. For a fast count of the total documents in a collection see estimatedDocumentCount.获取与筛选器匹配的文档数。有关集合中文档总数的快速计数,请参阅estimatedDocumentCount

    Due to countDocuments using the $match aggregation pipeline stage, certain query operators cannot be used in countDocuments. 由于countDocuments使用$match聚合管道阶段,因此某些查询运算符无法在countDocuments中使用。This includes the $where and $near query operators, among others. Details can be found in the documentation for the $match aggregation pipeline stage.这包括$where$near查询运算符等。详细信息可以在$match聚合管道阶段的文档中找到。

    Note: When migrating from count to countDocuments the following query operators must be replaced::从count迁移到countDocuments时,必须替换以下查询运算符:

    Operator运算符 Replacement替换
    $where $expr
    $near $geoWithin with $center
    $nearSphere $geoWithin with $centerSphere

    Parameters

    Returns Promise<number>

  • Creates an index on the db and collection collection.在数据库和集合集合上创建索引。

    Parameters

    • indexSpec: IndexSpecification

      The field name or index specification to create an index for用于创建索引的字段名或索引规范

    • Optionaloptions: CreateIndexesOptions

      Optional settings for the command命令的可选设置

    Returns Promise<string>

    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' }])
  • 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.在集合中创建多个索引,此方法仅支持MongoDB 2.6或更高版本。早期版本的MongoDB将抛出不支持的命令错误。

    Note: Unlike createIndex, this function takes in raw index specifications. Index specifications are defined here.:与createIndex不同,此函数接受原始索引规范。索引规范在此处定义。

    Parameters

    • indexSpecs: IndexDescription[]

      An array of index specifications to be created要创建的索引规范数组

    • Optionaloptions: CreateIndexesOptions

      Optional settings for the command命令的可选设置

    Returns Promise<string[]>

    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'
    }
    ]);
  • Creates a single search index for the collection.为集合创建单个搜索索引。

    Parameters

    • description: SearchIndexDescription

      The index description for the new search index.新搜索索引的索引描述。

    Returns Promise<string>

    A promise that resolves to the name of the new search index.解析为新搜索索引名称的promise。

    Only available when used against a 7.0+ Atlas cluster.仅适用于7.0+Atlas集群。

  • Creates multiple search indexes for the current collection.为当前集合创建多个搜索索引。

    Parameters

    • descriptions: SearchIndexDescription[]

      An array of SearchIndexDescriptions for the new search indexes.新搜索索引的SearchIndexDescription数组。

    Returns Promise<string[]>

    A promise that resolves to an array of the newly created search index names.一个promise,解析为一个新创建的搜索索引名称数组。

    Only available when used against a 7.0+ Atlas cluster.仅适用于7.0+Atlas集群。

  • Delete multiple documents from a collection从集合中删除多个文档

    Parameters

    • filter: Filter<TSchema> = {}

      The filter used to select the documents to remove用于选择要删除的文档的筛选器

    • options: DeleteOptions = {}

      Optional settings for the command命令的可选设置

    Returns Promise<DeleteResult>

  • Delete a document from a collection从集合中删除文档

    Parameters

    • filter: Filter<TSchema> = {}

      The filter used to select the document to remove用于选择要删除的文档的筛选器

    • options: DeleteOptions = {}

      Optional settings for the command命令的可选设置

    Returns Promise<DeleteResult>

  • Drop the collection from the database, removing it permanently. New accesses will create a new collection.从数据库中删除该集合,并将其永久删除。新的访问权限将创建新的集合。

    Parameters

    Returns Promise<boolean>

  • Drops an index from this collection.从此集合中删除索引。

    Parameters

    • indexName: string

      Name of the index to drop.要删除的索引的名称。

    • Optionaloptions: CommandOperationOptions

      Optional settings for the command命令的可选设置

    Returns Promise<Document>

  • Drops all indexes from this collection.删除此集合中的所有索引。

    Parameters

    Returns Promise<boolean>

  • Deletes a search index by index name.按索引名称删除搜索索引。

    Parameters

    • name: string

      The name of the search index to be deleted.要删除的搜索索引的名称。

    Returns Promise<void>

    Only available when used against a 7.0+ Atlas cluster.仅适用于7.0+Atlas集群。

  • 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.由于MongoDB 5.0.0-5.0.8版本中的一个疏忽,estimatedDocumentCount在其实现中使用的count命令未包含在Stable API的v1中,因此建议使用estimatedDocumentCount的Stable API用户将其服务器版本升级到5.0.9+或设置apiStrict:false以避免出现错误。

    Parameters

    Returns Promise<number>

  • Checks if one or more indexes exist on the collection, fails on first non-existing index检查集合上是否存在一个或多个索引,在第一个不存在的索引上失败

    Parameters

    • indexes: string | string[]

      One or more index names to check.要检查的一个或多个索引名称。

    • Optionaloptions: ListIndexesOptions

      Optional settings for the command命令的可选设置

    Returns Promise<boolean>

  • 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.启动按顺序批量写入操作。操作将按添加顺序连续执行,为类型中的每个开关创建一个新操作。

    Parameters

    Returns OrderedBulkOperation

    MongoNotConnectedError

    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.由于此遗留实现中的已知限制,在调用此方法之前必须连接MongoClient。但是,collection.bulkWrite()提供了一个等效的API,不需要预先连接。

  • Initiate an Out of order batch write operation. All operations will be buffered into insert/update/remove commands executed out of order.启动无序批量写入操作。所有操作都将被缓冲到按顺序执行的插入/更新/删除命令中。

    Parameters

    Returns UnorderedBulkOperation

    MongoNotConnectedError

    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.由于此遗留实现中的已知限制,在调用此方法之前必须连接MongoClient。但是,collection.bulkWrite()提供了一个等效的API,不需要预先连接。

  • 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. 将一组文档插入MongoDB。如果传入的文档不包含_id字段,驱动程序将向每个缺少该字段的文档添加一个_id字段,从而对文档进行修改。This behavior can be overridden by setting the forceServerObjectId flag.可以通过设置forceServerObjectId标志来覆盖此行为。

    Parameters

    Returns Promise<InsertManyResult<TSchema>>

  • 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.将单个文档插入MongoDB。如果传入的文档不包含_id字段,驱动程序将向每个缺少该字段的文档添加一个_id字段,从而对文档进行修改。可以通过设置forceServerObjectId标志来覆盖此行为。

    Parameters

    Returns Promise<InsertOneResult<TSchema>>

  • Returns if the collection is a capped collection如果集合是封顶集合,则返回true

    Parameters

    • Optionaloptions: OperationOptions

      Optional settings for the command命令的可选设置

    Returns Promise<boolean>

  • Returns all search indexes for the current collection.返回当前集合的所有搜索索引。

    Parameters

    Returns ListSearchIndexesCursor

    Only available when used against a 7.0+ Atlas cluster.

  • Returns all search indexes for the current collection.返回当前集合的所有搜索索引。

    Parameters

    • name: string

      The name of the index to search for. Only indexes with matching index names will be returned.要搜索的索引的名称。仅返回具有匹配索引名称的索引。

    • Optionaloptions: ListSearchIndexesOptions

      The options for the list indexes operation.列表索引操作的选项。

    Returns ListSearchIndexesCursor

    Only available when used against a 7.0+ Atlas cluster.仅适用于7.0+Atlas集群。

  • Rename the collection.重命名集合。

    Parameters

    • newName: string

      New name of of the collection.集合的新名称。

    • Optionaloptions: RenameOptions

      Optional settings for the command命令的可选设置

    Returns Promise<Collection<Document>>

    This operation does not inherit options from the Db or MongoClient.此操作不继承Db或MongoClient的选项。

  • Replace a document in a collection with another document用另一个文档替换集合中的文档

    Parameters

    • filter: Filter<TSchema>

      The filter used to select the document to replace用于选择要替换的文档的筛选器

    • replacement: WithoutId<TSchema>

      The Document that replaces the matching document替换匹配文档的文档

    • Optionaloptions: ReplaceOptions

      Optional settings for the command命令的可选设置

    Returns Promise<UpdateResult<TSchema>>

  • Update multiple documents in a collection更新集合中的多个文档

    The value of update can be either:update的值可以是:

    • UpdateFilter - A document that contains update operator expressions,包含更新运算符表达式的文档,
    • Document[] - an aggregation pipeline.聚合管道。

    Parameters

    • filter: Filter<TSchema>

      The filter used to select the document to update用于选择要更新的文档的筛选器

    • update: Document[] | UpdateFilter<TSchema>

      The modifications to apply适用的修改

    • Optionaloptions: UpdateOptions

      Optional settings for the command命令的可选设置

    Returns Promise<UpdateResult<TSchema>>

  • Update a single document in a collection更新集合中的单个文档

    The value of update can be either:update的值可以是:

    • UpdateFilter - A document that contains update operator expressions,包含更新运算符表达式的文档,
    • Document[] - an aggregation pipeline.聚合管道。

    Parameters

    • filter: Filter<TSchema>

      The filter used to select the document to update用于选择要更新的文档的筛选器

    • update: Document[] | UpdateFilter<TSchema>

      The modifications to apply适用的修改

    • Optionaloptions: UpdateOptions & {
          sort?: Sort;
      }

      Optional settings for the command命令的可选设置

    Returns Promise<UpdateResult<TSchema>>

  • Updates a search index by replacing the existing index definition with the provided definition.通过用提供的定义替换现有索引定义来更新搜索索引。

    Parameters

    • name: string

      The name of the search index to update.要更新的搜索索引的名称。

    • definition: Document

      The new search index definition.新的搜索索引定义。

    Returns Promise<void>

    Only available when used against a 7.0+ Atlas cluster.仅适用于7.0+Atlas集群。

  • Create a new Change Stream, watching for new changes (insertions, updates, replacements, deletions, and invalidations) in this collection.创建新的更改流,观察此集合中的新更改(插入、更新、替换、删除和无效)。

    Type Parameters

    • TLocal extends Document = TSchema

      Type of the data being detected by the change stream更改流检测到的数据类型

    • TChange extends Document = ChangeStreamDocument<TLocal>

      Type of the whole change stream document emitted发出的整个变更流文档的类型

    Parameters

    • pipeline: Document[] = []

      An array of pipeline stages through which to pass change stream documents. This allows for filtering (using $match) and manipulating the change stream documents.一系列管道阶段,通过这些阶段传递变更流文档。这允许筛选(使用$match)和操纵更改流文档。

    • options: ChangeStreamOptions = {}

      Optional settings for the command命令的可选设置

    Returns ChangeStream<TLocal, TChange>

    watch() accepts two generic arguments for distinct use cases:watch()为不同的用例接受两个泛型参数:

    • 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第二种方法是完全覆盖更改流文档的形状,如果没有提供,则类型将默认为第一个参数的ChangeStreamDocument

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

    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!传递第二个参数提供了一种反映高级管道引起的类型更改的方法。在这里,我们使用一个管道来让MongoDB筛选器仅用于插入更改并添加注释。无需在ChangeStreamInsertDocument类型上从头开始! 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);
    });

    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.在迭代器模式下,如果next()调用抛出超时错误,它将尝试恢复更改流。此操作成功后,可以重试下一个调用。

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

    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. 在发射器模式下,如果更改流经历了timeoutMS而不发出更改事件,它将发出一个错误事件,返回MongoOperationTimeoutError,但除非恢复尝试失败,否则不会关闭更改流。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();
    }
    });