Class: Mongo::Operation::Result
- Inherits:
-
Object
- Object
- Mongo::Operation::Result
- Extended by:
- Forwardable
- Includes:
- Enumerable
- Defined in:
- build/ruby-driver-master/lib/mongo/operation/result.rb,
build/ruby-driver-master/lib/mongo/operation/shared/result/aggregatable.rb,
build/ruby-driver-master/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::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.
-
#connection_global_id ⇒ Object
readonly
private
Global is of the connection 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, connection_global_id = 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 number of documents returned by the server in this batch.
- #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, connection_global_id = 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.
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 105 def initialize(replies, connection_description = nil, connection_global_id = 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 @connection_global_id = connection_global_id 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.
133 134 135 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 133 def connection_description @connection_description end |
#connection_global_id ⇒ Object (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 Global is of the connection that the operation was performed on that this result is for.
139 140 141 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 139 def connection_global_id @connection_global_id 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.
127 128 129 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 127 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?
157 158 159 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 157 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.
415 416 417 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 415 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.
172 173 174 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 172 def cursor_id acknowledged? ? replies.last.cursor_id : 0 end |
#documents ⇒ Array<BSON::Document>
Get the documents in the result.
196 197 198 199 200 201 202 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 196 def documents if acknowledged? replies.flat_map(&:documents) else [] end end |
#each {|Each| ... } ⇒ Enumerator
Iterate over the documents in the replies.
217 218 219 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 217 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.
332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 332 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.
230 231 232 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 230 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.
428 429 430 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 428 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.
183 184 185 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 183 def namespace nil end |
#ok? ⇒ true, false
Check the first document’s ok field.
296 297 298 299 300 301 302 303 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 296 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.
398 399 400 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 398 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).
243 244 245 246 247 248 249 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 243 def reply if acknowledged? replies.first else nil end end |
#returned_count ⇒ Integer
Get the number of documents returned by the server in this batch.
257 258 259 260 261 262 263 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 257 def returned_count if acknowledged? reply.number_returned else 0 end end |
#snapshot_timestamp ⇒ Object
439 440 441 442 443 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 439 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.
278 279 280 281 282 283 284 285 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 278 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.
361 362 363 364 365 366 367 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 361 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.
320 321 322 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 320 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.
435 436 437 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 435 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.
378 379 380 381 382 383 384 |
# File 'build/ruby-driver-master/lib/mongo/operation/result.rb', line 378 def written_count if acknowledged? first_document[N] || 0 else 0 end end |