Result — Documentation by YARD 0.9.37 (original) (raw)

Class: Mongo::Operation::Result

Inherits:

Object

• Object
• Mongo::Operation::Result show all

Extended by:

Forwardable

Includes:

Enumerable

Defined in:

lib/mongo/operation/result.rb,
lib/mongo/operation/shared/result/aggregatable.rb,
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::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 Summarycollapse

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 ⇒ Object readonly
• #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.
• #context ⇒ Operation::Context | nil readonly private
  The operation context (if any) that was active when this result was produced.
• #replies ⇒ ArrayProtocol::Message readonly private
  Replies The wrapped wire protocol replies.

Instance Method Summarycollapse

• #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 ⇒ ArrayBSON::Document
  Get the documents in the result.
• #each {|Each| ... } ⇒ Enumerator
  Iterate over the documents in the replies.
• #error ⇒ Error::OperationFailure::Family private
  The exception instance (of Error::OperationFailure::Family) that would be raised during processing of this result.
• #has_cursor_id? ⇒ true, false private
  Whether the result contains cursor_id.
• #initialize(replies, connection_description = nil, connection_global_id = nil, context: nil, connection: 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, context: nil, connection: 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.

Instance Attribute Details

#connection ⇒ Object

#connection_description ⇒ Server::Description

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.

#connection_global_id ⇒ Object

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.

#context ⇒ Operation::Context | 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 operation context (if any) that was active when this result was produced.

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.

Instance Method Details

#acknowledged? ⇒ true, false

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.

Is the result acknowledged?

#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.

#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.

Note:

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

Get the cursor id if the response is acknowledged.

#documents ⇒ ArrayBSON::Document

Get the documents in the result.

#each {|Each| ... } ⇒ Enumerator

Iterate over the documents in the replies.

#error ⇒ Error::OperationFailure::Family

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 Error::OperationFailure::Family) that would be raised during processing of this result.

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

| 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 | # File 'lib/mongo/operation/result.rb', line 354 def error @error ||= operation_failure_class.new( parser.message, 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.server_message, ) end | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#has_cursor_id? ⇒ true, false

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 result contains cursor_id

#inspect ⇒ String

Get the pretty formatted inspection of the result.

#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.

| 450 451 452 | # File 'lib/mongo/operation/result.rb', line 450 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.

#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

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).

#returned_count ⇒ Integer

Get the number of documents returned by the server in this batch.

#snapshot_timestamp ⇒ Object

| 461 462 463 464 465 | # File 'lib/mongo/operation/result.rb', line 461 def snapshot_timestamp if doc = reply.documents.first doc['cursor']&.[]('atClusterTime') || doc['atClusterTime'] end end | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#successful? ⇒ true, false

Note:

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.

#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.

#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.

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.

Validate the result by checking for any errors.

#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.

#written_count ⇒ Integer Also known as:n

Get the number of documents written by the server.

| 400 401 402 403 404 405 406 | # File 'lib/mongo/operation/result.rb', line 400 def written_count if acknowledged? first_document[N] || 0 else 0 end end | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |