Instantiate a new collection.

@example Instantiate a new collection.

  Mongo::Collection.new(database, 'test')

@param [ Mongo::Database ] database The collection‘s database. @param [ String, Symbol ] name The collection name. @param [ Hash ] options The collection options.

@since 2.0.0

Check if a collection is equal to another object. Will check the name and the database for equality.

@example Check collection equality.

  collection == other

@param [ Object ] other The object to check.

@return [ true, false ] If the objects are equal.

@since 2.0.0

Perform an aggregation on the collection.

@example Perform an aggregation.

  collection.aggregate([ { "$group" => { "_id" => "$city", "tpop" => { "$sum" => "$pop" }}} ])

@param [ Array<Hash> ] pipeline The aggregation pipeline. @param [ Hash ] options The aggregation options.

@option options [ true, false ] :allow_disk_use Set to true if disk usage is allowed during

  the aggregation.

@option options [ Integer ] :batch_size The number of documents to return per batch. @option options [ Integer ] :max_time_ms The maximum amount of time in milliseconds to allow the

  aggregation to run.

@option options [ true, false ] :use_cursor Indicates whether the command will request that the server

  provide results using a cursor. Note that as of server version 3.6, aggregations always provide results
  using a cursor and this option is therefore not valid.

@option options [ true, false ] :bypass_document_validation Whether or

  not to skip document level validation.

@option options [ Hash ] :collation The collation to use. @option options [ String ] :comment Associate a comment with the aggregation. @option options [ Session ] :session The session to use.

@return [ Aggregation ] The aggregation object.

@since 2.1.0

Execute a batch of bulk write operations.

@example Execute a bulk write.

  collection.bulk_write(operations, options)

@param [ Array<Hash> ] requests The bulk write requests. @param [ Hash ] options The options.

@option options [ true, false ] :ordered Whether the operations

  should be executed in order.

@option options [ Hash ] :write_concern The write concern options.

  Can be :w => Integer, :fsync => Boolean, :j => Boolean.

@option options [ true, false ] :bypass_document_validation Whether or

  not to skip document level validation.

@option options [ Session ] :session The session to use for the set of operations.

@return [ BulkWrite::Result ] The result of the operation.

@since 2.0.0

Is the collection capped?

@example Is the collection capped?

  collection.capped?

@return [ true, false ] If the collection is capped.

@since 2.0.0

Gets the number of matching documents in the collection.

@example Get the count.

  collection.count(name: 1)

@param [ Hash ] filter A filter for matching documents. @param [ Hash ] options The count options.

@option options [ Hash ] :hint The index to use. @option options [ Integer ] :limit The maximum number of documents to count. @option options [ Integer ] :max_time_ms The maximum amount of time to allow the command to run. @option options [ Integer ] :skip The number of documents to skip before counting. @option options [ Hash ] :read The read preference options. @option options [ Hash ] :collation The collation to use. @option options [ Session ] :session The session to use.

@return [ Integer ] The document count.

@since 2.1.0

@deprecated Use count_documents or estimated_document_count instead. However, note that the

  following operators will need to be substituted when switching to #count_documents:
    * $where should be replaced with $expr (only works on 3.6+)
    * $near should be replaced with $geoWithin with $center
    * $nearSphere should be replaced with $geoWithin with $centerSphere

Gets the number of of matching documents in the collection. Unlike the deprecated count method, this will return the exact number of documents matching the filter rather than the estimate.

@example Get the number of documents in the collection.

  collection_view.count_documents

@param [ Hash ] filter A filter for matching documents. @param [ Hash ] options Options for the operation.

@option opts :skip [ Integer ] The number of documents to skip. @option opts :hint [ Hash ] Override default index selection and force

  MongoDB to use a specific index for the query. Requires server version 3.6+.

@option opts :limit [ Integer ] Max number of docs to count. @option opts :max_time_ms [ Integer ] The maximum amount of time to allow the

  command to run.

@option opts [ Hash ] :read The read preference options. @option opts [ Hash ] :collation The collation to use.

@return [ Integer ] The document count.

@since 2.6.0

Force the collection to be created in the database.

@example Force the collection to be created.

  collection.create

@param [ Hash ] opts The options for the create operation.

@option options [ Session ] :session The session to use for the operation.

@return [ Result ] The result of the command.

@since 2.0.0

Remove documents from the collection.

@example Remove multiple documents from the collection.

  collection.delete_many

@param [ Hash ] filter The filter to use. @param [ Hash ] options The options.

@option options [ Hash ] :collation The collation to use. @option options [ Session ] :session The session to use.

@return [ Result ] The response from the database.

@since 2.1.0

Remove a document from the collection.

@example Remove a single document from the collection.

  collection.delete_one

@param [ Hash ] filter The filter to use. @param [ Hash ] options The options.

@option options [ Hash ] :collation The collation to use. @option options [ Session ] :session The session to use.

@return [ Result ] The response from the database.

@since 2.1.0

Get a list of distinct values for a specific field.

@example Get the distinct values.

  collection.distinct('name')

@param [ Symbol, String ] field_name The name of the field. @param [ Hash ] filter The documents from which to retrieve the distinct values. @param [ Hash ] options The distinct command options.

@option options [ Integer ] :max_time_ms The maximum amount of time to allow the command to run. @option options [ Hash ] :read The read preference options. @option options [ Hash ] :collation The collation to use. @option options [ Session ] :session The session to use.

@return [ Array<Object> ] The list of distinct values.

@since 2.1.0

Drop the collection. Will also drop all indexes associated with the collection.

@note An error returned if the collection doesn‘t exist is suppressed.

@example Drop the collection.

  collection.drop

@param [ Hash ] opts The options for the drop operation.

@option options [ Session ] :session The session to use for the operation.

@return [ Result ] The result of the command.

@since 2.0.0

Gets an estimate of the count of documents in a collection using collection metadata.

@example Get the number of documents in the collection.

  collection_view.estimated_document_count

@param [ Hash ] options Options for the operation.

@option opts :max_time_ms [ Integer ] The maximum amount of time to allow the command to

  run.

@option opts [ Hash ] :read The read preference options.

@return [ Integer ] The document count.

@since 2.6.0

Find documents in the collection.

@example Find documents in the collection by a selector.

  collection.find(name: 1)

@example Get all documents in a collection.

  collection.find

@param [ Hash ] filter The filter to use in the find. @param [ Hash ] options The options for the find.

@option options [ true, false ] :allow_partial_results Allows the query to get partial

  results if some shards are down.

@option options [ Integer ] :batch_size The number of documents returned in each batch

  of results from MongoDB.

@option options [ String ] :comment Associate a comment with the query. @option options [ :tailable, :tailable_await ] :cursor_type The type of cursor to use. @option options [ Integer ] :limit The max number of docs to return from the query. @option options [ Integer ] :max_time_ms The maximum amount of time to allow the query

  to run in milliseconds.

@option options [ Hash ] :modifiers A document containing meta-operators modifying the

  output or behavior of a query.

@option options [ true, false ] :no_cursor_timeout The server normally times out idle

  cursors after an inactivity period (10 minutes) to prevent excess memory use.
  Set this option to prevent that.

@option options [ true, false ] :oplog_replay Internal replication use only - driver

  should not set.

@option options [ Hash ] :projection The fields to include or exclude from each doc

  in the result set.

@option options [ Integer ] :skip The number of docs to skip before returning results. @option options [ Hash ] :sort The key and direction pairs by which the result set

  will be sorted.

@option options [ Hash ] :collation The collation to use. @option options [ Session ] :session The session to use.

@return [ CollectionView ] The collection view.

@since 2.0.0

Finds a single document in the database via findAndModify and deletes it, returning the original document.

@example Find one document and delete it.

  collection.find_one_and_delete(name: 'test')

@param [ Hash ] filter The filter to use. @param [ Hash ] options The options.

@option options [ Integer ] :max_time_ms The maximum amount of time to allow the command

  to run in milliseconds.

@option options [ Hash ] :projection The fields to include or exclude in the returned doc. @option options [ Hash ] :sort The key and direction pairs by which the result set

  will be sorted.

@option options [ Hash ] :write_concern The write concern options.

  Defaults to the collection's write concern.

@option options [ Hash ] :collation The collation to use. @option options [ Session ] :session The session to use.

@return [ BSON::Document, nil ] The document, if found.

@since 2.1.0

Finds a single document and replaces it, returning the original doc unless otherwise specified.

@example Find a document and replace it, returning the original.

  collection.find_one_and_replace({ name: 'test' }, { name: 'test1' })

@example Find a document and replace it, returning the new document.

  collection.find_one_and_replace({ name: 'test' }, { name: 'test1' }, :return_document => :after)

@param [ Hash ] filter The filter to use. @param [ BSON::Document ] replacement The replacement document. @param [ Hash ] options The options.

@option options [ Integer ] :max_time_ms The maximum amount of time to allow the command

  to run in milliseconds.

@option options [ Hash ] :projection The fields to include or exclude in the returned doc. @option options [ Hash ] :sort The key and direction pairs by which the result set

  will be sorted.

@option options [ Symbol ] :return_document Either :before or :after. @option options [ true, false ] :upsert Whether to upsert if the document doesn‘t exist. @option options [ true, false ] :bypass_document_validation Whether or

  not to skip document level validation.

@option options [ Hash ] :write_concern The write concern options.

  Defaults to the collection's write concern.

@option options [ Hash ] :collation The collation to use. @option options [ Session ] :session The session to use.

@return [ BSON::Document ] The document.

@since 2.1.0

Finds a single document via findAndModify and updates it, returning the original doc unless otherwise specified.

@example Find a document and update it, returning the original.

  collection.find_one_and_update({ name: 'test' }, { "$set" => { name: 'test1' }})

@example Find a document and update it, returning the updated document.

  collection.find_one_and_update({ name: 'test' }, { "$set" => { name: 'test1' }}, :return_document => :after)

@param [ Hash ] filter The filter to use. @param [ BSON::Document ] update The update statement. @param [ Hash ] options The options.

@option options [ Integer ] :max_time_ms The maximum amount of time to allow the command

  to run in milliseconds.

@option options [ Hash ] :projection The fields to include or exclude in the returned doc. @option options [ Hash ] :sort The key and direction pairs by which the result set

  will be sorted.

@option options [ Symbol ] :return_document Either :before or :after. @option options [ true, false ] :upsert Whether to upsert if the document doesn‘t exist. @option options [ true, false ] :bypass_document_validation Whether or

  not to skip document level validation.

@option options [ Hash ] :write_concern The write concern options.

  Defaults to the collection's write concern.

@option options [ Hash ] :collation The collation to use. @option options [ Array ] :array_filters A set of filters specifying to which array elements

  an update should apply.

@option options [ Session ] :session The session to use.

@return [ BSON::Document ] The document.

@since 2.1.0

Get a view of all indexes for this collection. Can be iterated or has more operations.

@example Get the index view.

  collection.indexes

@param [ Hash ] options Options for getting a list of all indexes.

@option options [ Session ] :session The session to use.

@return [ View::Index ] The index view.

@since 2.0.0

Insert the provided documents into the collection.

@example Insert documents into the collection.

  collection.insert_many([{ name: 'test' }])

@param [ Array<Hash> ] documents The documents to insert. @param [ Hash ] options The insert options.

@option options [ Session ] :session The session to use for the operation.

@return [ Result ] The database response wrapper.

@since 2.0.0

Insert a single document into the collection.

@example Insert a document into the collection.

  collection.insert_one({ name: 'test' })

@param [ Hash ] document The document to insert. @param [ Hash ] opts The insert options.

@option opts [ Session ] :session The session to use for the operation.

@return [ Result ] The database response wrapper.

@since 2.0.0

Get a pretty printed string inspection for the collection.

@example Inspect the collection.

  collection.inspect

@return [ String ] The collection inspection.

@since 2.0.0

Get the fully qualified namespace of the collection.

@example Get the fully qualified namespace.

  collection.namespace

@return [ String ] The collection namespace.

@since 2.0.0

Execute a parallel scan on the collection view.

Returns a list of up to cursor_count cursors that can be iterated concurrently. As long as the collection is not modified during scanning, each document appears once in one of the cursors’ result sets.

@example Execute a parallel collection scan.

  collection.parallel_scan(2)

@param [ Integer ] cursor_count The max number of cursors to return. @param [ Hash ] options The parallel scan command options.

@option options [ Integer ] :max_time_ms The maximum amount of time to allow the command

  to run in milliseconds.

@option options [ Session ] :session The session to use.

@return [ Array<Cursor> ] An array of cursors.

@since 2.1

Get the read concern for this collection instance.

@example Get the read concern.

  collection.read_concern

@return [ Hash ] The read concern.

@since 2.2.0

Get the read preference on this collection.

@example Get the read preference.

  collection.read_preference

@return [ Hash ] The read preference.

@since 2.0.0

Replaces a single document in the collection with the new document.

@example Replace a single document.

  collection.replace_one({ name: 'test' }, { name: 'test1' })

@param [ Hash ] filter The filter to use. @param [ Hash ] replacement The replacement document.. @param [ Hash ] options The options.

@option options [ true, false ] :upsert Whether to upsert if the

  document doesn't exist.

@option options [ true, false ] :bypass_document_validation Whether or

  not to skip document level validation.

@option options [ Hash ] :collation The collation to use. @option options [ Session ] :session The session to use.

@return [ Result ] The response from the database.

@since 2.1.0

Get the server selector on this collection.

@example Get the server selector.

  collection.server_selector

@return [ Mongo::ServerSelector ] The server selector.

@since 2.0.0

Update documents in the collection.

@example Update multiple documents in the collection.

  collection.update_many({ name: 'test'}, '$set' => { name: 'test1' })

@param [ Hash ] filter The filter to use. @param [ Hash ] update The update statement. @param [ Hash ] options The options.

@option options [ true, false ] :upsert Whether to upsert if the

  document doesn't exist.

@option options [ true, false ] :bypass_document_validation Whether or

  not to skip document level validation.

@option options [ Hash ] :collation The collation to use. @option options [ Array ] :array_filters A set of filters specifying to which array elements

  an update should apply.

@option options [ Session ] :session The session to use.

@return [ Result ] The response from the database.

@since 2.1.0

Update a single document in the collection.

@example Update a single document in the collection.

  collection.update_one({ name: 'test'}, '$set' => { name: 'test1'})

@param [ Hash ] filter The filter to use. @param [ Hash ] update The update statement. @param [ Hash ] options The options.

@option options [ true, false ] :upsert Whether to upsert if the

  document doesn't exist.

@option options [ true, false ] :bypass_document_validation Whether or

  not to skip document level validation.

@option options [ Hash ] :collation The collation to use. @option options [ Array ] :array_filters A set of filters specifying to which array elements

  an update should apply.

@option options [ Session ] :session The session to use.

@return [ Result ] The response from the database.

@since 2.1.0

As of version 3.6 of the MongoDB server, a ``$changeStream`` pipeline stage is supported in the aggregation framework. This stage allows users to request that notifications are sent for all changes to a particular collection.

@example Get change notifications for a given collection.

  collection.watch([{ '$match' => { operationType: { '$in' => ['insert', 'replace'] } } }])

@param [ Array<Hash> ] pipeline Optional additional filter operators. @param [ Hash ] options The change stream options.

@option options [ String ] :full_document Allowed values: ‘default’,

  ‘updateLookup’. Defaults to ‘default’. When set to ‘updateLookup’,
  the change notification for partial updates will include both a delta
  describing the changes to the document, as well as a copy of the entire
  document that was changed from some time after the change occurred.

@option options [ BSON::Document, Hash ] :resume_after Specifies the

  logical starting point for the new change stream.

@option options [ Integer ] :max_await_time_ms The maximum amount of time

  for the server to wait on new documents to satisfy a change stream query.

@option options [ Integer ] :batch_size The number of documents to return

  per batch.

@option options [ BSON::Document, Hash ] :collation The collation to use. @option options [ Session ] :session The session to use. @option options [ BSON::Timestamp ] :start_at_operation_time Only return

  changes that occurred at or after the specified timestamp. Any command run
  against the server will return a cluster time that can be used here.
  Only recognized by server versions 4.0+.

@note A change stream only allows ‘majority’ read concern. @note This helper method is preferable to running a raw aggregation with

  a $changeStream stage, for the purpose of supporting resumability.

@return [ ChangeStream ] The change stream object.

@since 2.5.0

@param [ Hash ] new_options The new options to use.

@return [ Mongo::Collection ] A new collection instance.

@since 2.1.0

Get the write concern on this collection.

@example Get the write concern.

  collection.write_concern

@return [ Mongo::WriteConcern ] The write concern.

@since 2.0.0