Parent

Included Modules

Mongo::BulkWriteCollectionView

A bulk write view to a collection of documents in a database.

Attributes

collection[R]
op_args[R]
ops[R]
options[R]

Public Class Methods

new(collection, options = {}) click to toggle source

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

Public Instance Methods

execute(opts = {}) click to toggle source

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
find(q) click to toggle source

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(document) click to toggle source

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
inspect() click to toggle source
# 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() click to toggle source

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_one() click to toggle source

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_one(u) click to toggle source

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(u) click to toggle source

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(u) click to toggle source

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
upsert(value = true) click to toggle source

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
upsert!(value = true) click to toggle source

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.