A bulk write view to a collection of documents in a database.
Initialize a bulk-write-view object to a collection with default query selector {}.
A bulk write operation is initialized from a collection object. For example, for an ordered bulk write view:
bulk = collection.initialize_ordered_bulk_op
or for an unordered bulk write view:
bulk = collection.initialize_unordered_bulk_op
The bulk write view collects individual write operations together so that they can be executed as a batch for significant performance gains. The ordered bulk operation will execute each operation serially in order. Execution will stop at the first occurrence of an error for an ordered bulk operation. The unordered bulk operation will be executed and may take advantage of parallelism. There are no guarantees for the order of execution of the operations on the server. Execution will continue even if there are errors for an unordered bulk operation.
A bulk operation is programmed as a sequence of individual operations. An individual operation is composed of a method chain of modifiers or setters terminated by a write method. A modify method sets a value on the current object. A set methods returns a duplicate of the current object with a value set. A terminator write method appends a write operation to the bulk batch collected in the view.
The API supports mixing of write operation types in a bulk operation. However, server support affects the implementation and performance of bulk operations.
MongoDB version 2.6 servers currently support only bulk commands of the same type. With an ordered bulk operation, contiguous individual ops of the same type can be batched into the same db request, and the next op of a different type must be sent separately in the next request. Performance will improve if you can arrange your ops to reduce the number of db requests. With an unordered bulk operation, individual ops can be grouped by type and sent in at most three requests, one each per insert, update, or delete.
MongoDB pre-version 2.6 servers do not support bulk write commands. The bulk operation must be sent one request per individual op. This also applies to inserts in order to have accurate counts and error reporting.
Important note on pre-2.6 performance: Performance is very poor compared to version 2.6. We recommend bulk operation with pre-2.6 only for compatibility or for development in preparation for version 2.6. For better performance with pre-version 2.6, use bulk insertion with Collection#insert.
@param [Collection] collection the parent collection object
@option opts [Boolean] :ordered (true) Set bulk execution for ordered or unordered
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 79 def initialize(collection, options = {}) @collection = collection @options = options @ops = [] @op_args = DEFAULT_OP_ARGS.dup end
Execute the bulk operation, with an optional write concern overwriting the default w:1. For example:
write_concern = {:w => 1, :j => 1} bulk.execute({write_concern})
On return from execute, the bulk operation is cleared, but the selector and upsert settings are preserved.
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 218 def execute(opts = {}) raise MongoArgumentError, EMPTY_BATCH_MSG if @ops.empty? write_concern = get_write_concern(opts, @collection) @ops.each_with_index{|op, index| op.last.merge!(:ord => index)} # infuse ordinal here to avoid issues with upsert if @collection.db.connection.use_write_command?(write_concern) errors, write_concern_errors, exchanges = @collection.command_writer.bulk_execute(@ops, @options, opts) else errors, write_concern_errors, exchanges = @collection.operation_writer.bulk_execute(@ops, @options, opts) end @ops = [] return true if errors.empty? && (exchanges.empty? || exchanges.first[:response] == true) # w 0 without GLE result = merge_result(errors + write_concern_errors, exchanges) raise BulkWriteError.new(MULTIPLE_ERRORS_MSG, Mongo::ErrorCode::MULTIPLE_ERRORS_OCCURRED, result) if !errors.empty? || !write_concern_errors.empty? result end
Modify the query selector for subsequent bulk write operations. The default query selector on creation of the bulk write view is {}. For operations that require a query selector, find() must be set per operation, or set once for all operations on the bulk object. For example, these operations:
bulk.find({"a" => 2}).update({"$inc" => {"x" => 2}}) bulk.find({"a" => 2}).update({"$set" => {"b" => 3}})
may be rewritten as:
bulk = find({"a" => 2}) bulk.update({"$inc" => {"x" => 2}}) bulk.update({"$set" => {"b" => 3}})
Note that modifying the query selector in this way will not affect operations that do not use a query selector, like insert().
@param [Hash] q the query selector
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 114 def find(q) op_args_set(:q, q) end
Insert a document. For example:
bulk.insert({"x" => 4})
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 203 def insert(document) # TODO - check keys op_push([:insert, {:d => document}]) end
# File lib/mongo/bulk_write_collection_view.rb, line 86 def inspect vars = [:@options, :@ops, :@op_args] vars_inspect = vars.collect{|var| "#{var}=#{instance_variable_get(var).inspect}"} "#<Mongo::BulkWriteCollectionView:0x#{self.object_id} " << "@collection=#<Mongo::Collection:0x#{@collection.object_id}>, #{vars_inspect.join(', ')}>" end
Remove all documents matching the selector. For example:
bulk.find({"a" => 5}).remove;
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 194 def remove op_push([:delete, @op_args.merge(:limit => 0)]) end
Remove a single document matching the selector. For example:
bulk.find({"a" => 4}).remove_one;
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 185 def remove_one op_push([:delete, @op_args.merge(:limit => 1)]) end
Replace entire document (update with whole doc replace). For example:
bulk.find({"a" => 3}).replace_one({"x" => 3})
@param [Hash] u the replacement document
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 175 def replace_one(u) raise MongoArgumentError, "document must not contain any operators" unless replace_doc?(u) op_push([:update, @op_args.merge(:u => u, :multi => false)]) end
Update all documents matching the selector. For example:
bulk.find({"a" => 2}).update({"$inc" => {"x" => 2}})
Use the upsert! or upsert method to specify an upsert. For example:
bulk.find({"a" => 2}).upsert.update({"$inc" => {"x" => 2}})
@param [Hash] u the update document
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 163 def update(u) raise MongoArgumentError, "document must start with an operator" unless update_doc?(u) op_push([:update, @op_args.merge(:u => u, :multi => true)]) end
Update one document matching the selector.
bulk.find({"a" => 1}).update_one({"$inc" => {"x" => 1}})
Use the upsert! or upsert method to specify an upsert. For example:
bulk.find({"a" => 1}).upsert.updateOne({"$inc" => {"x" => 1}})
@param [Hash] u the update document
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 147 def update_one(u) raise MongoArgumentError, "document must start with an operator" unless update_doc?(u) op_push([:update, @op_args.merge(:u => u, :multi => false)]) end
Set the upsert option argument for subsequent bulk write operations.
@param [Boolean] value (true) the upsert option value
@return [BulkWriteCollectionView] a duplicated object
# File lib/mongo/bulk_write_collection_view.rb, line 132 def upsert(value = true) dup.upsert!(value) end
Modify the upsert option argument for subsequent bulk write operations.
@param [Boolean] value (true) the upsert option value
@return [BulkWriteCollectionView]
# File lib/mongo/bulk_write_collection_view.rb, line 123 def upsert!(value = true) op_args_set(:upsert, value) end
Generated with the Darkfish Rdoc Generator 2.