Class: Mongo::Collection

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Helpers, QueryableEncryption, Retryable
Defined in:
lib/mongo/collection.rb,
lib/mongo/collection/view.rb,
lib/mongo/collection/helpers.rb,
lib/mongo/collection/view/iterable.rb,
lib/mongo/collection/view/readable.rb,
lib/mongo/collection/view/writable.rb,
lib/mongo/collection/view/immutable.rb,
lib/mongo/collection/view/map_reduce.rb,
lib/mongo/collection/view/aggregation.rb,
lib/mongo/collection/view/explainable.rb,
lib/mongo/collection/view/change_stream.rb,
lib/mongo/collection/queryable_encryption.rb,
lib/mongo/collection/view/builder/map_reduce.rb,
lib/mongo/collection/view/builder/aggregation.rb,
lib/mongo/collection/view/change_stream/retryable.rb

Overview

Represents a collection in the database and operations that can directly be applied to one.

Since:

  • 2.0.0

Defined Under Namespace

Modules: Helpers, QueryableEncryption Classes: View

Constant Summary collapse

CAPPED =

The capped option.

Since:

  • 2.1.0

'capped'.freeze
NS =

The ns field constant.

Since:

  • 2.1.0

'ns'.freeze
CHANGEABLE_OPTIONS =

Options that can be updated on a new Collection instance via the #with method.

Since:

  • 2.1.0

[ :read, :read_concern, :write, :write_concern ].freeze
CREATE_COLLECTION_OPTIONS =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Options map to transform create collection options.

Since:

  • 2.0.0

API:

  • private

{
  :time_series => :timeseries,
  :expire_after => :expireAfterSeconds,
  :clustered_index => :clusteredIndex,
  :change_stream_pre_and_post_images => :changeStreamPreAndPostImages,
  :encrypted_fields => :encryptedFields,
  :validator => :validator,
  :view_on => :viewOn
}

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Helpers

#do_drop

Methods included from QueryableEncryption

#maybe_create_qe_collections, #maybe_drop_emm_collections

Methods included from Retryable

#legacy_write_with_retry, #nro_write_with_retry, #read_with_one_retry, #read_with_retry, #read_with_retry_cursor, #write_with_retry

Constructor Details

#initialize(database, name, options = {}) ⇒ Collection

Instantiate a new collection.

Examples:

Instantiate a new collection.

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

Options Hash (options):

  • :write (Hash) —

    Deprecated. Equivalent to :write_concern option.

  • :write_concern (Hash) —

    The write concern options. Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.

  • :time_series (Hash) —

    Create a time-series collection. See mongodb.com/docs/manual/core/timeseries-collections/ for more information about time-series collection.

  • :expire_after (Integer) —

    Number indicating after how many seconds old time-series data should be deleted.

Raises:

Since:

  • 2.0.0

Parameters:

  • The collection’s database.

  • The collection name.

  • (defaults to: {})

    The collection options.



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/mongo/collection.rb', line 118

def initialize(database, name, options = {})
  raise Error::InvalidCollectionName.new unless name
  if options[:write] && options[:write_concern] && options[:write] != options[:write_concern]
    raise ArgumentError, "If :write and :write_concern are both given, they must be identical: #{options.inspect}"
  end
  @database = database
  @name = name.to_s.freeze
  @options = options.dup
=begin WriteConcern object support
  if @options[:write_concern].is_a?(WriteConcern::Base)
    # Cache the instance so that we do not needlessly reconstruct it.
    @write_concern = @options[:write_concern]
    @options[:write_concern] = @write_concern.options
  end
=end

  @options.freeze
end

Instance Attribute Details

#database ⇒ Mongo::Database (readonly)

Returns The database the collection resides in.

Since:

  • 2.0.0

Returns:

  • The database the collection resides in.



46
47
48
 
# File 'lib/mongo/collection.rb', line 46

def database
  @database
end

#name ⇒ String (readonly)

Returns The name of the collection.

Since:

  • 2.0.0

Returns:

  • The name of the collection.



49
50
51
 
# File 'lib/mongo/collection.rb', line 49

def name
  @name
end

#options ⇒ Hash (readonly)

Returns The collection options.

Since:

  • 2.0.0

Returns:

  • The collection options.



52
53
54
 
# File 'lib/mongo/collection.rb', line 52

def options
  @options
end

Instance Method Details

#==(other) ⇒ true, false

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

Examples:

Check collection equality.

collection == other

Since:

  • 2.0.0

Parameters:

  • The object to check.

Returns:

  • If the objects are equal.



89
90
91
92
 
# File 'lib/mongo/collection.rb', line 89

def ==(other)
  return false unless other.is_a?(Collection)
  name == other.name && database == other.database && options == other.options
end

#aggregate(pipeline, options = {}) ⇒ Aggregation

Perform an aggregation on the collection.

Examples:

Perform an aggregation.

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

Options Hash (options):

  • :allow_disk_use (true, false) —

    Set to true if disk usage is allowed during the aggregation.

  • :batch_size (Integer) —

    The number of documents to return per batch.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :collation (Hash) —

    The collation to use.

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :hint (String) —

    The index to use for the aggregation.

  • :let (Hash) —

    Mapping of variables to use in the pipeline. See the server documentation for details.

  • :max_time_ms (Integer) —

    The maximum amount of time in milliseconds to allow the aggregation to run.

  • :use_cursor (true, false) —

    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.

  • :session (Session) —

    The session to use.

Since:

  • 2.1.0

Parameters:

  • The aggregation pipeline.

  • (defaults to: {})

    The aggregation options.

Returns:

  • The aggregation object.



428
429
430
 
# File 'lib/mongo/collection.rb', line 428

def aggregate(pipeline, options = {})
  View.new(self, {}, options).aggregate(pipeline, options)
end

#bulk_write(requests, options = {}) ⇒ BulkWrite::Result

Execute a batch of bulk write operations.

Examples:

Execute a bulk write.

collection.bulk_write(operations, options)

Options Hash (options):

  • :ordered (true, false) —

    Whether the operations should be executed in order.

  • :write_concern (Hash) —

    The write concern options. Can be :w => Integer, :fsync => Boolean, :j => Boolean.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :session (Session) —

    The session to use for the set of operations.

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.0.0

Parameters:

  • The bulk write requests.

  • (defaults to: {})

    The options.

Returns:

  • The result of the operation.



725
726
727
 
# File 'lib/mongo/collection.rb', line 725

def bulk_write(requests, options = {})
  BulkWrite.new(self, requests, options).execute
end

#capped? ⇒ true, false

Is the collection capped?

Examples:

Is the collection capped?

collection.capped?

Since:

  • 2.0.0

Returns:

  • If the collection is capped.



243
244
245
 
# File 'lib/mongo/collection.rb', line 243

def capped?
  database.read_command(:collstats => name).documents[0][CAPPED]
end

#count(filter = nil, options = {}) ⇒ Integer

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 an estimated number of matching documents in the collection.

Examples:

Get the count.

collection.count(name: 1)

Options Hash (options):

  • :hint (Hash) —

    The index to use.

  • :limit (Integer) —

    The maximum number of documents to count.

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run.

  • :skip (Integer) —

    The number of documents to skip before counting.

  • :read (Hash) —

    The read preference options.

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

  • :comment (Object) —

    A user-provided comment to attach to this command.

Since:

  • 2.1.0

Parameters:

  • (defaults to: nil)

    A filter for matching documents.

  • (defaults to: {})

    The count options.

Returns:

  • The document count.



532
533
534
 
# File 'lib/mongo/collection.rb', line 532

def count(filter = nil, options = {})
  View.new(self, filter || {}, options).count(options)
end

#count_documents(filter = {}, options = {}) ⇒ Integer

Gets the number of documents matching the query. Unlike the deprecated #count method, this will return the exact number of documents matching the filter (or exact number of documents in the collection, if no filter is provided) rather than an estimate.

Use #estimated_document_count to retrieve an estimate of the number of documents in the collection using the collection metadata.

Options Hash (options):

  • :skip (Integer) —

    The number of documents to skip.

  • :hint (Hash) —

    Override default index selection and force MongoDB to use a specific index for the query. Requires server version 3.6+.

  • :limit (Integer) —

    Max number of docs to count.

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run.

  • :read (Hash) —

    The read preference options.

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

  • :comment (Object) —

    A user-provided comment to attach to this command.

Since:

  • 2.6.0

Parameters:

  • (defaults to: {})

    A filter for matching documents.

  • (defaults to: {})

    Options for the operation.

Returns:

  • The document count.



562
563
564
 
# File 'lib/mongo/collection.rb', line 562

def count_documents(filter = {}, options = {})
  View.new(self, filter, options).count_documents(options)
end

#create(opts = {}) ⇒ Result

Force the collection to be created in the database.

Examples:

Force the collection to be created.

collection.create

Options Hash (opts):

  • :session (Session) —

    The session to use for the operation.

  • :write_concern (Hash) —

    The write concern options.

  • :time_series (Hash) —

    Create a time-series collection.

  • :expire_after (Integer) —

    Number indicating after how many seconds old time-series data should be deleted.

  • :change_stream_pre_and_post_images (Hash) —

    Used to enable pre- and post-images on the created collection.

  • :encrypted_fields (Hash) —

    Hash describing encrypted fields for queryable encryption.

  • :validator (Hash) —

    Hash describing document validation options for the collection.

Since:

  • 2.0.0

Parameters:

  • (defaults to: {})

    The options for the create operation.

Returns:

  • The result of the command.



269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/mongo/collection.rb', line 269

def create(opts = {})
  # Passing read options to create command causes it to break.
  # Filter the read options out.
  # TODO put the list of read options in a class-level constant when
  # we figure out what the full set of them is.
  options = Hash[self.options.reject do |key, value|
    %w(read read_preference read_concern).include?(key.to_s)
  end]
  options.update(opts.slice(*CREATE_COLLECTION_OPTIONS.keys))
  # Converting Ruby options to server style.
  CREATE_COLLECTION_OPTIONS.each do |ruby_key, server_key|
    if options.key?(ruby_key)
      options[server_key] = options.delete(ruby_key)
    end
  end
  operation = { :create => name }.merge(options)
  operation.delete(:write)
  operation.delete(:write_concern)
  client.send(:with_session, opts) do |session|
    write_concern = if opts[:write_concern]
      WriteConcern.get(opts[:write_concern])
    else
      self.write_concern
    end

    context = Operation::Context.new(client: client, session: session)
    maybe_create_qe_collections(opts[:encrypted_fields], client, session) do |encrypted_fields|
      Operation::Create.new(
        selector: operation,
        db_name: database.name,
        write_concern: write_concern,
        session: session,
        # Note that these are collection options, collation isn't
        # taken from options passed to the create method.
        collation: options[:collation] || options['collation'],
        encrypted_fields: encrypted_fields,
        validator: options[:validator],
      ).execute(next_primary(nil, session), context: context)
    end
  end
end

#delete_many(filter = nil, options = {}) ⇒ Result

Remove documents from the collection.

Examples:

Remove multiple documents from the collection.

collection.delete_many

Options Hash (options):

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

  • :hint (Hash | String) —

    The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. “id”).

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.1.0

Parameters:

  • (defaults to: nil)

    The filter to use.

  • (defaults to: {})

    The options.

Returns:

  • The response from the database.



769
770
771
 
# File 'lib/mongo/collection.rb', line 769

def delete_many(filter = nil, options = {})
  find(filter, options).delete_many(options)
end

#delete_one(filter = nil, options = {}) ⇒ Result

Remove a document from the collection.

Examples:

Remove a single document from the collection.

collection.delete_one

Options Hash (options):

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

  • :hint (Hash | String) —

    The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. “id”).

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.1.0

Parameters:

  • (defaults to: nil)

    The filter to use.

  • (defaults to: {})

    The options.

Returns:

  • The response from the database.



747
748
749
 
# File 'lib/mongo/collection.rb', line 747

def delete_one(filter = nil, options = {})
  find(filter, options).delete_one(options)
end

#distinct(field_name, filter = nil, options = {}) ⇒ Array<Object>

Get a list of distinct values for a specific field.

Examples:

Get the distinct values.

collection.distinct('name')

Options Hash (options):

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run.

  • :read (Hash) —

    The read preference options.

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

Since:

  • 2.1.0

Parameters:

  • The name of the field.

  • (defaults to: nil)

    The documents from which to retrieve the distinct values.

  • (defaults to: {})

    The distinct command options.

Returns:

  • The list of distinct values.



604
605
606
 
# File 'lib/mongo/collection.rb', line 604

def distinct(field_name, filter = nil, options = {})
  View.new(self, filter || {}, options).distinct(field_name, options)
end

#drop(opts = {}) ⇒ Result

Note:

An error returned if the collection doesn’t exist is suppressed.

Drop the collection. Will also drop all indexes associated with the collection, as well as associated queryable encryption collections.

Examples:

Drop the collection.

collection.drop

Options Hash (opts):

  • :write_concern (Hash) —

    The write concern options.

Since:

  • 2.0.0

Parameters:

  • (defaults to: {})

    The options for the drop operation.

  • a customizable set of options

Returns:

  • The result of the command.



327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/mongo/collection.rb', line 327

def drop(opts = {})
  client.send(:with_session, opts) do |session|
    maybe_drop_emm_collections(opts[:encrypted_fields], client, session) do
      temp_write_concern = write_concern
      write_concern = if opts[:write_concern]
        WriteConcern.get(opts[:write_concern])
      else
        temp_write_concern
      end
      context = Operation::Context.new(client: client, session: session)
      operation = Operation::Drop.new({
        selector: { :drop => name },
        db_name: database.name,
        write_concern: write_concern,
        session: session,
      })
      do_drop(operation, session, context)
    end
  end
end

#estimated_document_count(options = {}) ⇒ Integer

Gets an estimate of the number of documents in the collection using the collection metadata.

Use #count_documents to retrieve the exact number of documents in the collection, or to count documents matching a filter.

Options Hash (options):

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run for on the server.

  • :read (Hash) —

    The read preference options.

  • :comment (Object) —

    A user-provided comment to attach to this command.

Since:

  • 2.6.0

Parameters:

  • (defaults to: {})

    Options for the operation.

Returns:

  • The document count.



583
584
585
 
# File 'lib/mongo/collection.rb', line 583

def estimated_document_count(options = {})
  View.new(self, {}, options).estimated_document_count(options)
end

#find(filter = nil, options = {}) ⇒ CollectionView

Find documents in the collection.

Examples:

Find documents in the collection by a selector.

collection.find(name: 1)

Get all documents in a collection.

collection.find

Options Hash (options):

  • :allow_disk_use (true, false) —

    When set to true, the server can write temporary data to disk while executing the find operation. This option is only available on MongoDB server versions 4.4 and newer.

  • :allow_partial_results (true, false) —

    Allows the query to get partial results if some shards are down.

  • :batch_size (Integer) —

    The number of documents returned in each batch of results from MongoDB.

  • :collation (Hash) —

    The collation to use.

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :cursor_type (:tailable, :tailable_await) —

    The type of cursor to use.

  • :limit (Integer) —

    The max number of docs to return from the query.

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the query to run, in milliseconds.

  • :modifiers (Hash) —

    A document containing meta-operators modifying the output or behavior of a query.

  • :no_cursor_timeout (true, false) —

    The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use. Set this option to prevent that.

  • :oplog_replay (true, false) —

    For internal replication use only, applications should not set this option.

  • :projection (Hash) —

    The fields to include or exclude from each doc in the result set.

  • :session (Session) —

    The session to use.

  • :skip (Integer) —

    The number of docs to skip before returning results.

  • :sort (Hash) —

    The key and direction pairs by which the result set will be sorted.

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.0.0

Parameters:

  • (defaults to: nil)

    The filter to use in the find.

  • (defaults to: {})

    The options for the find.

Returns:

  • The collection view.



393
394
395
 
# File 'lib/mongo/collection.rb', line 393

def find(filter = nil, options = {})
  View.new(self, filter || {}, options)
end

#find_one_and_delete(filter, options = {}) ⇒ BSON::Document?

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

Examples:

Find one document and delete it.

collection.find_one_and_delete(name: 'test')

Options Hash (options):

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run in milliseconds.

  • :projection (Hash) —

    The fields to include or exclude in the returned doc.

  • :sort (Hash) —

    The key and direction pairs by which the result set will be sorted.

  • :write_concern (Hash) —

    The write concern options. Defaults to the collection’s write concern.

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

  • :hint (Hash | String) —

    The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. “id”).

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.1.0

Parameters:

  • The filter to use.

  • (defaults to: {})

    The options.

Returns:

  • The document, if found.



907
908
909
 
# File 'lib/mongo/collection.rb', line 907

def find_one_and_delete(filter, options = {})
  find(filter, options).find_one_and_delete(options)
end

#find_one_and_replace(filter, replacement, options = {}) ⇒ BSON::Document

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

Examples:

Find a document and replace it, returning the original.

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

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

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

Options Hash (options):

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run in milliseconds.

  • :projection (Hash) —

    The fields to include or exclude in the returned doc.

  • :sort (Hash) —

    The key and direction pairs by which the result set will be sorted.

  • :return_document (Symbol) —

    Either :before or :after.

  • :upsert (true, false) —

    Whether to upsert if the document doesn’t exist.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :write_concern (Hash) —

    The write concern options. Defaults to the collection’s write concern.

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

  • :hint (Hash | String) —

    The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. “id”).

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.1.0

Parameters:

  • The filter to use.

  • The replacement document.

  • (defaults to: {})

    The options.

Returns:

  • The document.



985
986
987
 
# File 'lib/mongo/collection.rb', line 985

def find_one_and_replace(filter, replacement, options = {})
  find(filter, options).find_one_and_update(replacement, options)
end

#find_one_and_update(filter, update, options = {}) ⇒ BSON::Document

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

Examples:

Find a document and update it, returning the original.

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

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

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

Options Hash (options):

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run in milliseconds.

  • :projection (Hash) —

    The fields to include or exclude in the returned doc.

  • :sort (Hash) —

    The key and direction pairs by which the result set will be sorted.

  • :return_document (Symbol) —

    Either :before or :after.

  • :upsert (true, false) —

    Whether to upsert if the document doesn’t exist.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :write_concern (Hash) —

    The write concern options. Defaults to the collection’s write concern.

  • :collation (Hash) —

    The collation to use.

  • :array_filters (Array) —

    A set of filters specifying to which array elements an update should apply.

  • :session (Session) —

    The session to use.

  • :hint (Hash | String) —

    The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. “id”).

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.1.0

Parameters:

  • The filter to use.

  • The update document or pipeline.

  • (defaults to: {})

    The options.

Returns:

  • The document.



947
948
949
 
# File 'lib/mongo/collection.rb', line 947

def find_one_and_update(filter, update, options = {})
  find(filter, options).find_one_and_update(update, options)
end

#indexes(options = {}) ⇒ View::Index

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

Examples:

Get the index view.

collection.indexes

Options Hash (options):

  • :session (Session) —

    The session to use.

Since:

  • 2.0.0

Parameters:

  • (defaults to: {})

    Options for getting a list of all indexes.

Returns:

  • The index view.



621
622
623
 
# File 'lib/mongo/collection.rb', line 621

def indexes(options = {})
  Index::View.new(self, options)
end

#insert_many(documents, options = {}) ⇒ Result

Insert the provided documents into the collection.

Examples:

Insert documents into the collection.

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

Options Hash (options):

  • :ordered (true | false) —

    Whether the operations should be executed in order.

  • :session (Session) —

    The session to use for the operation.

Since:

  • 2.0.0

Parameters:

  • The documents to insert.

  • (defaults to: {})

    The insert options.

Returns:

  • The database response wrapper.



697
698
699
700
701
702
 
# File 'lib/mongo/collection.rb', line 697

def insert_many(documents, options = {})
  QueryCache.clear_namespace(namespace)

  inserts = documents.map{ |doc| { :insert_one => doc }}
  bulk_write(inserts, options)
end

#insert_one(document, opts = {}) ⇒ Result

Insert a single document into the collection.

Examples:

Insert a document into the collection.

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

Options Hash (opts):

  • :session (Session) —

    The session to use for the operation.

Since:

  • 2.0.0

Parameters:

  • The document to insert.

  • (defaults to: {})

    The insert options.

Returns:

  • The database response wrapper.



650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
 
# File 'lib/mongo/collection.rb', line 650

def insert_one(document, opts = {})
  QueryCache.clear_namespace(namespace)

  client.send(:with_session, opts) do |session|
    write_concern = if opts[:write_concern]
      WriteConcern.get(opts[:write_concern])
    else
      write_concern_with_session(session)
    end

    if document.nil?
      raise ArgumentError, "Document to be inserted cannot be nil"
    end

    context = Operation::Context.new(client: client, session: session)
    write_with_retry(write_concern, context: context) do |connection, txn_num, context|
      Operation::Insert.new(
        :documents => [ document ],
        :db_name => database.name,
        :coll_name => name,
        :write_concern => write_concern,
        :bypass_document_validation => !!opts[:bypass_document_validation],
        :options => opts,
        :id_generator => client.options[:id_generator],
        :session => session,
        :txn_num => txn_num,
        :comment => opts[:comment]
      ).execute_with_connection(connection, context: context)
    end
  end
end

#inspect ⇒ String

Get a pretty printed string inspection for the collection.

Examples:

Inspect the collection.

collection.inspect

Since:

  • 2.0.0

Returns:

  • The collection inspection.



633
634
635
 
# File 'lib/mongo/collection.rb', line 633

def inspect
  "#<Mongo::Collection:0x#{object_id} namespace=#{namespace}>"
end

#namespace ⇒ String

Get the fully qualified namespace of the collection.

Examples:

Get the fully qualified namespace.

collection.namespace

Since:

  • 2.0.0

Returns:

  • The collection namespace.



997
998
999
 
# File 'lib/mongo/collection.rb', line 997

def namespace
  "#{database.name}.#{name}"
end

#parallel_scan(cursor_count, options = {}) ⇒ Array<Cursor>

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.

Examples:

Execute a parallel collection scan.

collection.parallel_scan(2)

Options Hash (options):

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run in milliseconds.

  • :session (Session) —

    The session to use.

Since:

  • 2.1

Parameters:

  • The max number of cursors to return.

  • (defaults to: {})

    The parallel scan command options.

Returns:

  • An array of cursors.



792
793
794
 
# File 'lib/mongo/collection.rb', line 792

def parallel_scan(cursor_count, options = {})
  find({}, options).send(:parallel_scan, cursor_count, options)
end

#read_concern ⇒ Hash

Get the read concern for this collection instance.

Examples:

Get the read concern.

collection.read_concern

Since:

  • 2.2.0

Returns:

  • The read concern.



144
145
146
 
# File 'lib/mongo/collection.rb', line 144

def read_concern
  options[:read_concern] || database.read_concern
end

#read_preference ⇒ Hash

Get the read preference on this collection.

Examples:

Get the read preference.

collection.read_preference

Since:

  • 2.0.0

Returns:

  • The read preference.



168
169
170
 
# File 'lib/mongo/collection.rb', line 168

def read_preference
  @read_preference ||= options[:read] || database.read_preference
end

#replace_one(filter, replacement, options = {}) ⇒ Result

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

Examples:

Replace a single document.

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

Options Hash (options):

  • :upsert (true, false) —

    Whether to upsert if the document doesn’t exist.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

  • :hint (Hash | String) —

    The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. “id”).

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.1.0

Parameters:

  • The filter to use.

  • The replacement document..

  • (defaults to: {})

    The options.

Returns:

  • The response from the database.



819
820
821
 
# File 'lib/mongo/collection.rb', line 819

def replace_one(filter, replacement, options = {})
  find(filter, options).replace_one(replacement, options)
end

#server_selector ⇒ Mongo::ServerSelector

Get the server selector on this collection.

Examples:

Get the server selector.

collection.server_selector

Since:

  • 2.0.0

Returns:

  • The server selector.



156
157
158
 
# File 'lib/mongo/collection.rb', line 156

def server_selector
  @server_selector ||= ServerSelector.get(read_preference || database.server_selector)
end

#system_collection? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Whether the collection is a system collection.

Since:

  • 2.0.0

Returns:

  • Whether the system is a system collection.

API:

  • private



1006
1007
1008
 
# File 'lib/mongo/collection.rb', line 1006

def system_collection?
  name.start_with?('system.')
end

#update_many(filter, update, options = {}) ⇒ Result

Update documents in the collection.

Examples:

Update multiple documents in the collection.

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

Options Hash (options):

  • :upsert (true, false) —

    Whether to upsert if the document doesn’t exist.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :collation (Hash) —

    The collation to use.

  • :array_filters (Array) —

    A set of filters specifying to which array elements an update should apply.

  • :session (Session) —

    The session to use.

  • :hint (Hash | String) —

    The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. “id”).

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.1.0

Parameters:

  • The filter to use.

  • The update document or pipeline.

  • (defaults to: {})

    The options.

Returns:

  • The response from the database.



848
849
850
 
# File 'lib/mongo/collection.rb', line 848

def update_many(filter, update, options = {})
  find(filter, options).update_many(update, options)
end

#update_one(filter, update, options = {}) ⇒ Result

Update a single document in the collection.

Examples:

Update a single document in the collection.

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

Options Hash (options):

  • :upsert (true, false) —

    Whether to upsert if the document doesn’t exist.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :collation (Hash) —

    The collation to use.

  • :array_filters (Array) —

    A set of filters specifying to which array elements an update should apply.

  • :session (Session) —

    The session to use.

  • :hint (Hash | String) —

    The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. “id”).

  • :let (Hash) —

    Mapping of variables to use in the command. See the server documentation for details.

Since:

  • 2.1.0

Parameters:

  • The filter to use.

  • The update document or pipeline.

  • (defaults to: {})

    The options.

Returns:

  • The response from the database.



877
878
879
 
# File 'lib/mongo/collection.rb', line 877

def update_one(filter, update, options = {})
  find(filter, options).update_one(update, options)
end

#watch(pipeline = [], options = {}) ⇒ ChangeStream

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.

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.

Examples:

Get change notifications for a given collection.

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

Options Hash (options):

  • :full_document (String) —

    Allowed values: nil, ‘default’, ‘updateLookup’, ‘whenAvailable’, ‘required’.

    The default is to not send a value (i.e. nil), which is equivalent to ‘default’. By default, the change notification for partial updates will include a delta describing the changes to the document.

    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.

    When set to ‘whenAvailable’, configures the change stream to return the post-image of the modified document for replace and update change events if the post-image for this event is available.

    When set to ‘required’, the same behavior as ‘whenAvailable’ except that an error is raised if the post-image is not available.

  • :full_document_before_change (String) —

    Allowed values: nil, ‘whenAvailable’, ‘required’, ‘off’.

    The default is to not send a value (i.e. nil), which is equivalent to ‘off’.

    When set to ‘whenAvailable’, configures the change stream to return the pre-image of the modified document for replace, update, and delete change events if it is available.

    When set to ‘required’, the same behavior as ‘whenAvailable’ except that an error is raised if the pre-image is not available.

  • :resume_after (BSON::Document, Hash) —

    Specifies the logical starting point for the new change stream.

  • :max_await_time_ms (Integer) —

    The maximum amount of time for the server to wait on new documents to satisfy a change stream query.

  • :batch_size (Integer) —

    The number of documents to return per batch.

  • :collation (BSON::Document, Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

  • :start_at_operation_time (BSON::Timestamp) —

    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+.

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :show_expanded_events (Boolean) —

    Enables the server to send the ‘expanded’ list of change stream events. The list of additional events included with this flag set are: createIndexes, dropIndexes, modify, create, shardCollection, reshardCollection, refineCollectionShardKey.

Since:

  • 2.5.0

Parameters:

  • (defaults to: [])

    Optional additional filter operators.

  • (defaults to: {})

    The change stream options.

Returns:

  • The change stream object.



499
500
501
502
503
 
# File 'lib/mongo/collection.rb', line 499

def watch(pipeline = [], options = {})
  view_options = options.dup
  view_options[:await_data] = true if options[:max_await_time_ms]
  View::ChangeStream.new(View.new(self, {}, view_options), pipeline, nil, options)
end

#with(new_options) ⇒ Mongo::Collection

Returns A new collection instance.

Since:

  • 2.1.0

Parameters:

  • The new options to use.

Returns:

  • A new collection instance.



221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/mongo/collection.rb', line 221

def with(new_options)
  new_options.keys.each do |k|
    raise Error::UnchangeableCollectionOption.new(k) unless CHANGEABLE_OPTIONS.include?(k)
  end
  options = @options.dup
  if options[:write] && new_options[:write_concern]
    options.delete(:write)
  end
  if options[:write_concern] && new_options[:write]
    options.delete(:write_concern)
  end
  Collection.new(database, name, options.update(new_options))
end

#write_concern ⇒ Mongo::WriteConcern

Get the write concern on this collection.

Examples:

Get the write concern.

collection.write_concern

Since:

  • 2.0.0

Returns:

  • The write concern.



180
181
182
183
 
# File 'lib/mongo/collection.rb', line 180

def write_concern
  @write_concern ||= WriteConcern.get(
    options[:write_concern] || options[:write] || database.write_concern)
end

#write_concern_with_session(session) ⇒ Mongo::WriteConcern

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the write concern for the collection, given the session.

If the session is in a transaction and the collection has an unacknowledged write concern, remove the write concern’s :w option. Otherwise, return the unmodified write concern.

Since:

  • 2.0.0

Returns:

  • The write concern.

API:

  • private



195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/mongo/collection.rb', line 195

def write_concern_with_session(session)
  wc = write_concern
  if session && session.in_transaction?
    if wc && !wc.acknowledged?
      opts = wc.options.dup
      opts.delete(:w)
      return WriteConcern.get(opts)
    end
  end
  wc
end