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
@return [ Array<Protocol::Reply> ] replies The wrapped wire protocol replies.
Public Class Methods
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
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 96 def acknowledged? !!@replies end
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 317 def cluster_time first_document && first_document[CLUSTER_TIME] end
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 123 def cursor_id acknowledged? ? replies.last.cursor_id : 0 end
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 145 def documents if acknowledged? replies.flat_map{ |reply| reply.documents } else [] end end
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 165 def each(&block) documents.each(&block) end
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 177 def inspect "#<#{self.class.name}:0x#{object_id} documents=#{documents}>" end
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 329 def labels @labels ||= parser.labels end
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 109 def multiple? replies.size > 1 end
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 133 def namespace nil end
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 242 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
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 305 def operation_time first_document && first_document[OPERATION_TIME] end
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 189 def reply if acknowledged? replies.first else nil end end
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 205 def returned_count if acknowledged? multiple? ? aggregate_returned_count : reply.number_returned else 0 end end
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 225 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 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 265 def validate! !successful? ? raise_operation_failure : self end
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 288 def written_count if acknowledged? multiple? ? aggregate_written_count : (first_document[N] || 0) else 0 end end
Private Instance Methods
# File lib/mongo/operation/result.rb, line 335 def aggregate_returned_count replies.reduce(0) do |n, reply| n += reply.number_returned n end end
# File lib/mongo/operation/result.rb, line 342 def aggregate_written_count documents.reduce(0) do |n, document| n += (document[N] || 0) n end end
# File lib/mongo/operation/result.rb, line 353 def first_document @first_document ||= first || BSON::Document.new end
# File lib/mongo/operation/result.rb, line 349 def parser @parser ||= Error::Parser.new(first_document, replies) end
# File lib/mongo/operation/result.rb, line 357 def query_failure? replies.first && (replies.first.query_failure? || replies.first.cursor_not_found?) end
# File lib/mongo/operation/result.rb, line 269 def raise_operation_failure raise Error::OperationFailure.new( parser.message, self, code: parser.code, code_name: parser.code_name, labels: parser.labels, wtimeout: parser.wtimeout) end