Class: Mongo::Operation::Result
- Inherits:
-
Object
- Object
- Mongo::Operation::Result
- Extended by:
- Forwardable
- Includes:
- Enumerable
- Defined in:
- build/ruby-driver-v2.17/lib/mongo/operation/result.rb,
build/ruby-driver-v2.17/lib/mongo/operation/shared/result/aggregatable.rb,
build/ruby-driver-v2.17/lib/mongo/operation/shared/result/use_legacy_error_parser.rb
Overview
Result wrapper for wire protocol replies.
An operation has zero or one replies. The only operations producing zero replies are unacknowledged writes; all other operations produce one reply. This class provides an object that can be operated on (for example, to check whether an operation succeeded) even when the operation did not produce a reply (in which case it is assumed to have succeeded).
Direct Known Subclasses
Aggregate::Result, CollectionsInfo::Result, Delete::BulkResult, Delete::Result, Explain::Result, Find::Legacy::Result, Find::Result, GetMore::Result, Indexes::Result, Insert::BulkResult, Insert::Result, ListCollections::Result, MapReduce::Result, ParallelScan::Result, Update::BulkResult, Update::Legacy::Result, Update::Result, UsersInfo::Result
Defined Under Namespace
Modules: Aggregatable, UseLegacyErrorParser
Constant Summary collapse
- CURSOR =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
The field name for the cursor document in an aggregation.
'cursor'.freeze
- CURSOR_ID =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
The cursor id field in the cursor document.
'id'.freeze
- FIRST_BATCH =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
The field name for the first batch of a cursor.
'firstBatch'.freeze
- NEXT_BATCH =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
The field name for the next batch of a cursor.
'nextBatch'.freeze
- NAMESPACE =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
The namespace field in the cursor document.
'ns'.freeze
- N =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
The number of documents updated in the write.
'n'.freeze
- OK =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
The ok status field in the result.
'ok'.freeze
- RESULT =
This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.
The result field constant.
'result'.freeze
Instance Attribute Summary collapse
-
#connection_description ⇒ Server::Description
readonly
private
Server description of the server that the operation was performed on that this result is for.
-
#replies ⇒ Array<Protocol::Message>
readonly
private
Replies The wrapped wire protocol replies.
Instance Method Summary collapse
-
#acknowledged? ⇒ true, false
Is the result acknowledged?.
-
#cluster_time ⇒ ClusterTime | nil
Get the cluster time reported in the server response.
-
#cursor_id ⇒ Integer
private
Get the cursor id if the response is acknowledged.
-
#documents ⇒ Array<BSON::Document>
Get the documents in the result.
-
#each {|Each| ... } ⇒ Enumerator
Iterate over the documents in the replies.
-
#error ⇒ Error::OperationFailure
private
The exception instance (of the Error::OperationFailure class) that would be raised during processing of this result.
-
#initialize(replies, connection_description = nil) ⇒ Result
constructor
private
Initialize a new result.
-
#inspect ⇒ String
Get the pretty formatted inspection of the result.
-
#labels ⇒ Array
private
Gets the set of error labels associated with the result.
-
#namespace ⇒ Nil
private
Get the namespace of the cursor.
-
#ok? ⇒ true, false
Check the first document’s ok field.
-
#operation_time ⇒ Object | nil
Get the operation time reported in the server response.
-
#reply ⇒ Protocol::Message
private
Get the reply from the result.
-
#returned_count ⇒ Integer
Get the count of documents returned by the server.
- #snapshot_timestamp ⇒ Object
-
#successful? ⇒ true, false
If the result was a command then determine if it was considered a success.
-
#topology_version ⇒ TopologyVersion | nil
private
The topology version.
-
#validate! ⇒ Result
private
Validate the result by checking for any errors.
-
#write_concern_error? ⇒ Boolean
private
Whether the operation failed with a write concern error.
-
#written_count ⇒ Integer
(also: #n)
Get the number of documents written by the server.
Constructor Details
#initialize(replies, connection_description = nil) ⇒ Result
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Initialize a new result.
For an unkacknowledged write, pass nil in replies.
For all other operations, replies must be a Protocol::Message instance or an array containing a single Protocol::Message instance.
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 102 def initialize(replies, connection_description = nil) if replies if replies.is_a?(Array) if replies.length != 1 raise ArgumentError, "Only one (or zero) reply is supported, given #{replies.length}" end reply = replies.first else reply = replies end unless reply.is_a?(Protocol::Message) raise ArgumentError, "Argument must be a Message instance, but is a #{reply.class}: #{reply.inspect}" end @replies = [ reply ] @connection_description = connection_description end end |
Instance Attribute Details
#connection_description ⇒ Server::Description (readonly)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns Server description of the server that the operation was performed on that this result is for.
129 130 131 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 129 def connection_description @connection_description end |
#replies ⇒ Array<Protocol::Message> (readonly)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns replies The wrapped wire protocol replies.
123 124 125 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 123 def replies @replies end |
Instance Method Details
#acknowledged? ⇒ true, false
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.
Is the result acknowledged?
147 148 149 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 147 def acknowledged? !!@replies end |
#cluster_time ⇒ ClusterTime | nil
Get the cluster time reported in the server response.
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.
408 409 410 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 408 def cluster_time first_document && ClusterTime[first_document['$clusterTime']] end |
#cursor_id ⇒ Integer
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Cursor ids of 0 indicate there is no cursor on the server.
Get the cursor id if the response is acknowledged.
162 163 164 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 162 def cursor_id acknowledged? ? replies.last.cursor_id : 0 end |
#documents ⇒ Array<BSON::Document>
Get the documents in the result.
186 187 188 189 190 191 192 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 186 def documents if acknowledged? replies.flat_map(&:documents) else [] end end |
#each {|Each| ... } ⇒ Enumerator
Iterate over the documents in the replies.
207 208 209 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 207 def each(&block) documents.each(&block) end |
#error ⇒ Error::OperationFailure
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
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.
325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 325 def error @error ||= Error::OperationFailure.new( parser., self, code: parser.code, code_name: parser.code_name, write_concern_error_document: parser.write_concern_error_document, write_concern_error_code: parser.write_concern_error_code, write_concern_error_code_name: parser.write_concern_error_code_name, write_concern_error_labels: parser.write_concern_error_labels, labels: parser.labels, wtimeout: parser.wtimeout, connection_description: connection_description, document: parser.document, server_message: parser., ) end |
#inspect ⇒ String
Get the pretty formatted inspection of the result.
220 221 222 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 220 def inspect "#<#{self.class.name}:0x#{object_id} documents=#{documents}>" end |
#labels ⇒ Array
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Gets the set of error labels associated with the result.
421 422 423 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 421 def labels @labels ||= parser.labels end |
#namespace ⇒ Nil
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Get the namespace of the cursor. The method should be defined in result classes where ‘ns’ is in the server response.
173 174 175 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 173 def namespace nil end |
#ok? ⇒ true, false
Check the first document’s ok field.
289 290 291 292 293 294 295 296 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 289 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 ⇒ Object | nil
Get the operation time reported in the server response.
391 392 393 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 391 def operation_time first_document && first_document[OPERATION_TIME] end |
#reply ⇒ Protocol::Message
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Get the reply from the result.
Returns nil if there is no reply (i.e. the operation was an unacknowledged write).
233 234 235 236 237 238 239 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 233 def reply if acknowledged? replies.first else nil end end |
#returned_count ⇒ Integer
Get the count of documents returned by the server.
250 251 252 253 254 255 256 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 250 def returned_count if acknowledged? reply.number_returned else 0 end end |
#snapshot_timestamp ⇒ Object
432 433 434 435 436 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 432 def if doc = reply.documents.first doc['cursor']&.[]('atClusterTime') || doc['atClusterTime'] end end |
#successful? ⇒ true, false
If the write was unacknowledged, then this will always return true.
If the result was a command then determine if it was considered a success.
271 272 273 274 275 276 277 278 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 271 def successful? return true if !acknowledged? if first_document.has_key?(OK) ok? && parser..empty? else !query_failure? && parser..empty? end end |
#topology_version ⇒ TopologyVersion | nil
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns The topology version.
354 355 356 357 358 359 360 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 354 def topology_version unless defined?(@topology_version) @topology_version = first_document['topologyVersion'] && TopologyVersion.new(first_document['topologyVersion']) end @topology_version end |
#validate! ⇒ Result
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
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.
Validate the result by checking for any errors.
313 314 315 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 313 def validate! !successful? ? raise_operation_failure : self end |
#write_concern_error? ⇒ Boolean
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Whether the operation failed with a write concern error.
428 429 430 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 428 def write_concern_error? !!(first_document && first_document['writeConcernError']) end |
#written_count ⇒ Integer Also known as: n
Get the number of documents written by the server.
371 372 373 374 375 376 377 |
# File 'build/ruby-driver-v2.17/lib/mongo/operation/result.rb', line 371 def written_count if acknowledged? first_document[N] || 0 else 0 end end |