class Mongo::Operation::Result

Result wrapper for operations.

@since 2.0.0

Constants

CURSOR

The field name for the cursor document in an aggregation.

@since 2.2.0

CURSOR_ID

The cursor id field in the cursor document.

@since 2.2.0

FIRST_BATCH

The field name for the first batch of a cursor.

@since 2.2.0

N

The number of documents updated in the write.

@since 2.0.0

NAMESPACE

The namespace field in the cursor document.

@since 2.2.0

NEXT_BATCH

The field name for the next batch of a cursor.

@since 2.2.0

OK

The ok status field in the result.

@since 2.0.0

RESULT

The result field constant.

@since 2.2.0

Attributes

replies[R]

@return [ Array<Protocol::Reply> ] replies The wrapped wire protocol replies.

Public Class Methods

new(replies) click to toggle source

Initialize a new result.

@example Instantiate the result.

Result.new(replies)

@param [ Protocol::Reply ] replies The wire protocol replies.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 75
def initialize(replies)
  @replies = [ *replies ] if replies
end

Public Instance Methods

acknowledged?() click to toggle source

Is the result acknowledged?

@note On MongoDB 2.6 and higher all writes are acknowledged since the

driver uses write commands for all write operations. On 2.4 and
lower, the result is acknowledged if the GLE has been executed after
the command. If not, no replies will be specified. Reads will always
return true here since a replies is always provided.

@return [ true, false ] If the result is acknowledged.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 93
def acknowledged?
  !!@replies
end
cluster_time() click to toggle source

Get the cluster time reported in the server response.

@example Get the cluster time.

result.cluster_time

@return [ BSON::Document ] The cluster time document.

@since 2.5.0

# File lib/mongo/operation/result.rb, line 311
def cluster_time
  first_document && first_document[CLUSTER_TIME]
end
cursor_id() click to toggle source

Get the cursor id if the response is acknowledged.

@note Cursor ids of 0 indicate there is no cursor on the server.

@example Get the cursor id.

result.cursor_id

@return [ Integer ] The cursor id.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 120
def cursor_id
  acknowledged? ? replies.last.cursor_id : 0
end
documents() click to toggle source

Get the documents in the result.

@example Get the documents.

result.documents

@return [ Array<BSON::Document> ] The documents.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 142
def documents
  if acknowledged?
    replies.flat_map{ |reply| reply.documents }
  else
    []
  end
end
each(&block) click to toggle source

Iterate over the documents in the replies.

@example Iterate over the documents.

result.each do |doc|
  p doc
end

@return [ Enumerator ] The enumerator.

@since 2.0.0

@yieldparam [ BSON::Document ] Each document in the result.

# File lib/mongo/operation/result.rb, line 162
def each(&block)
  documents.each(&block)
end
inspect() click to toggle source

Get the pretty formatted inspection of the result.

@example Inspect the result.

result.inspect

@return [ String ] The inspection.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 174
def inspect
  "#<#{self.class.name}:0x#{object_id} documents=#{documents}>"
end
multiple?() click to toggle source

Determine if this result is a collection of multiple replies from the server.

@example Is the result for multiple replies?

result.multiple?

@return [ true, false ] If the result is for multiple replies.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 106
def multiple?
  replies.size > 1
end
n()
Alias for: written_count
namespace() click to toggle source

Get the namespace of the cursor. The method should be defined in result classes where 'ns' is in the server response.

@return [ Nil ]

@since 2.0.0

# File lib/mongo/operation/result.rb, line 130
def namespace
  nil
end
ok?() click to toggle source

Check the first document's ok field.

@example Check the ok field.

result.ok?

@return [ true, false ] If the command returned ok.

@since 2.1.0

# File lib/mongo/operation/result.rb, line 239
def ok?
  # first_document[OK] is a float, and the server can return
  # ok as a BSON int32, BSON int64 or a BSON double.
  # The number 1 is exactly representable in a float, hence
  # 1.0 == 1 is going to perform correctly all of the time
  # (until the server returns something other than 1 for success, that is)
  first_document[OK] == 1
end
operation_time() click to toggle source

Get the operation time reported in the server response.

@example Get the operation time.

result.operation_time

@return [ Object ] The operation time value.

@since 2.5.0

# File lib/mongo/operation/result.rb, line 299
def operation_time
  first_document && first_document[OPERATION_TIME]
end
reply() click to toggle source

Get the first reply from the result.

@example Get the first reply.

result.reply

@return [ Protocol::Reply ] The first reply.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 186
def reply
  if acknowledged?
    replies.first
  else
    nil
  end
end
returned_count() click to toggle source

Get the count of documents returned by the server.

@example Get the number returned.

result.returned_count

@return [ Integer ] The number of documents returned.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 202
def returned_count
  if acknowledged?
    multiple? ? aggregate_returned_count : reply.number_returned
  else
    0
  end
end
successful?() click to toggle source

If the result was a command then determine if it was considered a success.

@note If the write was unacknowledged, then this will always return

true.

@example Was the command successful?

result.successful?

@return [ true, false ] If the command was successful.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 222
def successful?
  return true if !acknowledged?
  if first_document.has_key?(OK)
    ok? && parser.message.empty?
  else
    !query_failure? && parser.message.empty?
  end
end
validate!() click to toggle source

Validate the result by checking for any errors.

@note This only checks for errors with writes since authentication is

handled at the connection level and any authentication errors would
be raised there, before a Result is ever created.

@example Validate the result.

result.validate!

@raise [ Error::OperationFailure ] If an error is in the result.

@return [ Result ] The result if verification passed.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 262
def validate!
  !successful? ? raise_operation_failure : self
end
written_count() click to toggle source

Get the number of documents written by the server.

@example Get the number of documents written.

result.written_count

@return [ Integer ] The number of documents written.

@since 2.0.0

# File lib/mongo/operation/result.rb, line 282
def written_count
  if acknowledged?
    multiple? ? aggregate_written_count : (first_document[N] || 0)
  else
    0
  end
end
Also aliased as: n

Private Instance Methods

aggregate_returned_count() click to toggle source
# File lib/mongo/operation/result.rb, line 317
def aggregate_returned_count
  replies.reduce(0) do |n, reply|
    n += reply.number_returned
    n
  end
end
aggregate_written_count() click to toggle source
# File lib/mongo/operation/result.rb, line 324
def aggregate_written_count
  documents.reduce(0) do |n, document|
    n += (document[N] || 0)
    n
  end
end
first_document() click to toggle source
# File lib/mongo/operation/result.rb, line 335
def first_document
  @first_document ||= first || BSON::Document.new
end
parser() click to toggle source
# File lib/mongo/operation/result.rb, line 331
def parser
  @parser ||= Error::Parser.new(first_document, replies)
end
query_failure?() click to toggle source
# File lib/mongo/operation/result.rb, line 339
def query_failure?
  replies.first && (replies.first.query_failure? || replies.first.cursor_not_found?)
end
raise_operation_failure() click to toggle source
# File lib/mongo/operation/result.rb, line 266
def raise_operation_failure
  raise Error::OperationFailure.new(
    parser.message,
    self,
    :code => parser.code, :code_name => parser.code_name)
end