Class: Mongo::Collection

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Retryable
Defined in:
lib/mongo/collection.rb,
lib/mongo/collection/view.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/builder/flags.rb,
lib/mongo/collection/view/change_stream.rb,
lib/mongo/collection/view/builder/op_query.rb,
lib/mongo/collection/view/builder/modifiers.rb,
lib/mongo/collection/view/builder/map_reduce.rb,
lib/mongo/collection/view/builder/aggregation.rb,
lib/mongo/collection/view/builder/find_command.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

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 ].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Retryable

#read_with_one_retry, #read_with_retry, #write_with_retry

Constructor Details

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

Instantiate a new collection.

Examples:

Instantiate a new collection.

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

Parameters:

  • database (Mongo::Database) —

    The collection’s database.

  • name (String, Symbol) —

    The collection name.

  • options (Hash) (defaults to: {}) —

    The collection options.

Raises:

Since:

  • 2.0.0



84
85
86
87
88
89
 
# File 'lib/mongo/collection.rb', line 84

def initialize(database, name, options = {})
  raise Error::InvalidCollectionName.new unless name
  @database = database
  @name = name.to_s.freeze
  @options = options.freeze
end

Instance Attribute Details

#database ⇒ Mongo::Database (readonly)

Returns The database the collection resides in.

Returns:

Since:

  • 2.0.0



39
40
41
 
# File 'lib/mongo/collection.rb', line 39

def database
  @database
end

#name ⇒ String (readonly)

Returns The name of the collection.

Returns:

  • (String) —

    The name of the collection.

Since:

  • 2.0.0



42
43
44
 
# File 'lib/mongo/collection.rb', line 42

def name
  @name
end

#options ⇒ Hash (readonly)

Returns The collection options.

Returns:

  • (Hash) —

    The collection options.

Since:

  • 2.0.0



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

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

Parameters:

  • other (Object) —

    The object to check.

Returns:

  • (true, false) —

    If the objects are equal.

Since:

  • 2.0.0



69
70
71
72
 
# File 'lib/mongo/collection.rb', line 69

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" }}} ])

Parameters:

  • pipeline (Array<Hash>) —

    The aggregation pipeline.

  • options (Hash) (defaults to: {}) —

    The aggregation options.

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.

  • :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.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :collation (Hash) —

    The collation to use.

  • :comment (String) —

    Associate a comment with the aggregation.

  • :session (Session) —

    The session to use.

Returns:

  • (Aggregation) —

    The aggregation object.

Since:

  • 2.1.0



297
298
299
 
# File 'lib/mongo/collection.rb', line 297

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)

Parameters:

  • requests (Array<Hash>) —

    The bulk write requests.

  • options (Hash) (defaults to: {}) —

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

Returns:

Since:

  • 2.0.0



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

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?

Returns:

  • (true, false) —

    If the collection is capped.

Since:

  • 2.0.0



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

def capped?
  database.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 the number of matching documents in the collection.

Examples:

Get the count.

collection.count(name: 1)

Parameters:

  • filter (Hash) (defaults to: nil) —

    A filter for matching documents.

  • options (Hash) (defaults to: {}) —

    The count options.

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.

Returns:

  • (Integer) —

    The document count.

Since:

  • 2.1.0



366
367
368
 
# File 'lib/mongo/collection.rb', line 366

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

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

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.

Examples:

Get the number of documents in the collection.

collection_view.count_documents

Parameters:

  • filter (Hash) —

    A filter for matching documents.

  • options (Hash) (defaults to: {}) —

    Options for the operation.

  • opts (Hash) —

    a customizable set of options

Returns:

  • (Integer) —

    The document count.

Since:

  • 2.6.0



391
392
393
 
# File 'lib/mongo/collection.rb', line 391

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

Parameters:

  • opts (Hash) (defaults to: {}) —

    The options for the create operation.

  • options (Hash) —

    a customizable set of options

Returns:

  • (Result) —

    The result of the command.

Since:

  • 2.0.0



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/mongo/collection.rb', line 184

def create(opts = {})
  operation = { :create => name }.merge(options)
  operation.delete(:write)
  server = next_primary
  if (options[:collation] || options[Operation::COLLATION]) && !server.features.collation_enabled?
    raise Error::UnsupportedCollation.new
  end
  client.send(:with_session, opts) do |session|
    Operation::Create.new({
                            selector: operation,
                            db_name: database.name,
                            write_concern: write_concern,
                            session: session
                            }).execute(server)
  end
end

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

Remove documents from the collection.

Examples:

Remove multiple documents from the collection.

collection.delete_many

Parameters:

  • filter (Hash) (defaults to: nil) —

    The filter to use.

  • options (Hash) (defaults to: {}) —

    The options.

Options Hash (options):

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

Returns:

  • (Result) —

    The response from the database.

Since:

  • 2.1.0



567
568
569
 
# File 'lib/mongo/collection.rb', line 567

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

Parameters:

  • filter (Hash) (defaults to: nil) —

    The filter to use.

  • options (Hash) (defaults to: {}) —

    The options.

Options Hash (options):

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

Returns:

  • (Result) —

    The response from the database.

Since:

  • 2.1.0



549
550
551
 
# File 'lib/mongo/collection.rb', line 549

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

Parameters:

  • field_name (Symbol, String) —

    The name of the field.

  • filter (Hash) (defaults to: nil) —

    The documents from which to retrieve the distinct values.

  • options (Hash) (defaults to: {}) —

    The distinct command options.

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.

Returns:

  • (Array<Object>) —

    The list of distinct values.

Since:

  • 2.1.0



430
431
432
 
# File 'lib/mongo/collection.rb', line 430

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.

Examples:

Drop the collection.

collection.drop

Parameters:

  • opts (Hash) (defaults to: {}) —

    The options for the drop operation.

  • options (Hash) —

    a customizable set of options

Returns:

  • (Result) —

    The result of the command.

Since:

  • 2.0.0



216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/mongo/collection.rb', line 216

def drop(opts = {})
  client.send(:with_session, opts) do |session|
    Operation::Drop.new({
                          selector: { :drop => name },
                          db_name: database.name,
                          write_concern: write_concern,
                          session: session
                          }).execute(next_primary)
  end
rescue Error::OperationFailure => ex
  raise ex unless ex.message =~ /ns not found/
  false
end

#estimated_document_count(options = {}) ⇒ Integer

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

Examples:

Get the number of documents in the collection.

collection_view.estimated_document_count

Parameters:

  • options (Hash) (defaults to: {}) —

    Options for the operation.

  • opts (Hash) —

    a customizable set of options

Returns:

  • (Integer) —

    The document count.

Since:

  • 2.6.0



409
410
411
 
# File 'lib/mongo/collection.rb', line 409

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

Parameters:

  • filter (Hash) (defaults to: nil) —

    The filter to use in the find.

  • options (Hash) (defaults to: {}) —

    The options for the find.

Options Hash (options):

  • :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.

  • :comment (String) —

    Associate a comment with the query.

  • :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) —

    Internal replication use only - driver should not set.

  • :projection (Hash) —

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

  • :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.

  • :collation (Hash) —

    The collation to use.

  • :session (Session) —

    The session to use.

Returns:

  • (CollectionView) —

    The collection view.

Since:

  • 2.0.0



268
269
270
 
# File 'lib/mongo/collection.rb', line 268

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

Parameters:

  • filter (Hash) —

    The filter to use.

  • options (Hash) (defaults to: {}) —

    The options.

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.

Returns:

  • (BSON::Document, nil) —

    The document, if found.

Since:

  • 2.1.0



689
690
691
 
# File 'lib/mongo/collection.rb', line 689

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)

Parameters:

  • filter (Hash) —

    The filter to use.

  • replacement (BSON::Document) —

    The replacement document.

  • options (Hash) (defaults to: {}) —

    The options.

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.

Returns:

  • (BSON::Document) —

    The document.

Since:

  • 2.1.0



759
760
761
 
# File 'lib/mongo/collection.rb', line 759

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)

Parameters:

  • filter (Hash) —

    The filter to use.

  • update (BSON::Document) —

    The update statement.

  • options (Hash) (defaults to: {}) —

    The options.

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.

Returns:

  • (BSON::Document) —

    The document.

Since:

  • 2.1.0



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

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

Parameters:

  • options (Hash) (defaults to: {}) —

    Options for getting a list of all indexes.

Options Hash (options):

  • :session (Session) —

    The session to use.

Returns:

  • (View::Index) —

    The index view.

Since:

  • 2.0.0



447
448
449
 
# File 'lib/mongo/collection.rb', line 447

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' }])

Parameters:

  • documents (Array<Hash>) —

    The documents to insert.

  • options (Hash) (defaults to: {}) —

    The insert options.

Options Hash (options):

  • :session (Session) —

    The session to use for the operation.

Returns:

  • (Result) —

    The database response wrapper.

Since:

  • 2.0.0



507
508
509
510
 
# File 'lib/mongo/collection.rb', line 507

def insert_many(documents, options = {})
  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' })

Parameters:

  • document (Hash) —

    The document to insert.

  • opts (Hash) (defaults to: {}) —

    The insert options.

Options Hash (opts):

  • :session (Session) —

    The session to use for the operation.

Returns:

  • (Result) —

    The database response wrapper.

Since:

  • 2.0.0



476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
 
# File 'lib/mongo/collection.rb', line 476

def insert_one(document, opts = {})
  client.send(:with_session, opts) do |session|
    write_with_retry(session, write_concern) do |server, txn_num|
      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
       ).execute(server)
    end
  end
end

#inspect ⇒ String

Get a pretty printed string inspection for the collection.

Examples:

Inspect the collection.

collection.inspect

Returns:

  • (String) —

    The collection inspection.

Since:

  • 2.0.0



459
460
461
 
# File 'lib/mongo/collection.rb', line 459

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

Returns:

  • (String) —

    The collection namespace.

Since:

  • 2.0.0



771
772
773
 
# File 'lib/mongo/collection.rb', line 771

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)

Parameters:

  • cursor_count (Integer) —

    The max number of cursors to return.

  • options (Hash) (defaults to: {}) —

    The parallel scan command options.

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.

Returns:

  • (Array<Cursor>) —

    An array of cursors.

Since:

  • 2.1



590
591
592
 
# File 'lib/mongo/collection.rb', line 590

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

Returns:

  • (Hash) —

    The read concern.

Since:

  • 2.2.0



99
100
101
 
# File 'lib/mongo/collection.rb', line 99

def read_concern
  @read_concern ||= options[:read_concern]
end

#read_preference ⇒ Hash

Get the read preference on this collection.

Examples:

Get the read preference.

collection.read_preference

Returns:

  • (Hash) —

    The read preference.

Since:

  • 2.0.0



123
124
125
 
# File 'lib/mongo/collection.rb', line 123

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' })

Parameters:

  • filter (Hash) —

    The filter to use.

  • replacement (Hash) —

    The replacement document..

  • options (Hash) (defaults to: {}) —

    The options.

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.

Returns:

  • (Result) —

    The response from the database.

Since:

  • 2.1.0



613
614
615
 
# File 'lib/mongo/collection.rb', line 613

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

Returns:

Since:

  • 2.0.0



111
112
113
 
# File 'lib/mongo/collection.rb', line 111

def server_selector
  @server_selector ||= ServerSelector.get(read_preference || database.server_selector)
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' })

Parameters:

  • filter (Hash) —

    The filter to use.

  • update (Hash) —

    The update statement.

  • options (Hash) (defaults to: {}) —

    The options.

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.

Returns:

  • (Result) —

    The response from the database.

Since:

  • 2.1.0



638
639
640
 
# File 'lib/mongo/collection.rb', line 638

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'})

Parameters:

  • filter (Hash) —

    The filter to use.

  • update (Hash) —

    The update statement.

  • options (Hash) (defaults to: {}) —

    The options.

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.

Returns:

  • (Result) —

    The response from the database.

Since:

  • 2.1.0



663
664
665
 
# File 'lib/mongo/collection.rb', line 663

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'] } } }])

Parameters:

  • pipeline (Array<Hash>) (defaults to: []) —

    Optional additional filter operators.

  • options (Hash) (defaults to: {}) —

    The change stream options.

Options Hash (options):

  • :full_document (String) —

    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.

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

Returns:

  • (ChangeStream) —

    The change stream object.

Since:

  • 2.5.0



337
338
339
 
# File 'lib/mongo/collection.rb', line 337

def watch(pipeline = [], options = {})
  View::ChangeStream.new(View.new(self, {}, options), pipeline, nil, options)
end

#with(new_options) ⇒ Mongo::Collection

Returns A new collection instance.

Parameters:

  • new_options (Hash) —

    The new options to use.

Returns:

Since:

  • 2.1.0



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

def with(new_options)
  new_options.keys.each do |k|
    raise Error::UnchangeableCollectionOption.new(k) unless CHANGEABLE_OPTIONS.include?(k)
  end
  Collection.new(database, name, options.merge(new_options))
end

#write_concern ⇒ Mongo::WriteConcern

Get the write concern on this collection.

Examples:

Get the write concern.

collection.write_concern

Returns:

Since:

  • 2.0.0



135
136
137
 
# File 'lib/mongo/collection.rb', line 135

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