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 76
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 98
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 [ nil | ClusterTime ] The cluster time document.

Changed in version 2.9.0: This attribute became an instance of ClusterTime, which is a subclass of BSON::Document. Previously it was an instance of BSON::Document.

@since 2.5.0

# File lib/mongo/operation/result.rb, line 342
def cluster_time
  first_document && ClusterTime[first_document['$clusterTime']]
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 125
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 147
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 167
def each(&block)
  documents.each(&block)
end
error() click to toggle source

The exception instance (of the Error::OperationFailure class) that would be raised during processing of this result.

This method should only be called when result is not successful.

@return [ Error::OperationFailure ] The exception.

@api private

# File lib/mongo/operation/result.rb, line 279
def error
  @error ||= Error::OperationFailure.new(
    parser.message,
    self,
    code: parser.code,
    code_name: parser.code_name,
    write_concern_error: parser.write_concern_error?,
    write_concern_error_code: parser.write_concern_error_code,
    write_concern_error_code_name: parser.write_concern_error_code_name,
    labels: parser.labels,
    wtimeout: parser.wtimeout)
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 179
def inspect
  "#<#{self.class.name}:0x#{object_id} documents=#{documents}>"
end
labels() click to toggle source

Gets the set of error labels associated with the result.

@example Get the labels.

result.labels

@return [ Array ] labels The set of labels.

@since 2.7.0

# File lib/mongo/operation/result.rb, line 354
def labels
  @labels ||= parser.labels
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 111
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 135
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 244
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 326
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 191
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 207
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 227
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 267
def validate!
  !successful? ? raise_operation_failure : self
end
write_concern_error?() click to toggle source

Whether the operation failed with a write concern error.

@api private

# File lib/mongo/operation/result.rb, line 361
def write_concern_error?
  !!(first_document && first_document['writeConcernError'])
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 309
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 367
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 374
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 385
def first_document
  @first_document ||= first || BSON::Document.new
end
parser() click to toggle source
# File lib/mongo/operation/result.rb, line 381
def parser
  @parser ||= Error::Parser.new(first_document, replies)
end
query_failure?() click to toggle source
# File lib/mongo/operation/result.rb, line 389
def query_failure?
  replies.first && (replies.first.query_failure? || replies.first.cursor_not_found?)
end
raise_operation_failure() click to toggle source

Raises a Mongo::OperationFailure exception corresponding to the error information in this result.

@raise Error::OperationFailure

# File lib/mongo/operation/result.rb, line 296
def raise_operation_failure
  raise error
end