Class: Mongo::Operation::Result

Relationships & Source Files
Namespace Children
Modules: `Aggregatable`, `UseLegacyErrorParser`
Extension / Inclusion / Inheritance Descendants
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
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Forwardable
Instance Chain: self, Enumerable
Inherits:	Object
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).

Since:

2.0.0

Constant Summary

CURSOR = Internal use only

The field name for the cursor document in an aggregation.
Since:
- 2.2.0
# File 'lib/mongo/operation/result.rb', line 42
```
'cursor'.freeze
```
CURSOR_ID = Internal use only

The cursor id field in the cursor document.
Since:
- 2.2.0
# File 'lib/mongo/operation/result.rb', line 48
```
'id'.freeze
```
FIRST_BATCH = Internal use only

The field name for the first batch of a cursor.
Since:
- 2.2.0
# File 'lib/mongo/operation/result.rb', line 54
```
'firstBatch'.freeze
```
N = Internal use only

The number of documents updated in the write.
Since:
- 2.0.0
# File 'lib/mongo/operation/result.rb', line 72
```
'n'.freeze
```
NAMESPACE = Internal use only

The namespace field in the cursor document.
Since:
- 2.2.0
# File 'lib/mongo/operation/result.rb', line 66
```
'ns'.freeze
```
NEXT_BATCH = Internal use only

The field name for the next batch of a cursor.
Since:
- 2.2.0
# File 'lib/mongo/operation/result.rb', line 60
```
'nextBatch'.freeze
```
OK = Internal use only

The ok status field in the result.
Since:
- 2.0.0
# File 'lib/mongo/operation/result.rb', line 78
```
'ok'.freeze
```
RESULT = Internal use only

The result field constant.
Since:
- 2.2.0
# File 'lib/mongo/operation/result.rb', line 84
```
'result'.freeze
```

Class Method Summary

.new(replies, connection_description = nil, connection_global_id = nil) ⇒ Result constructor Internal use only Internal use only

Initialize a new result.

Instance Attribute Summary

#acknowledged? ⇒ true, false readonly

Is the result acknowledged?
#connection_description ⇒ Server::Description readonly Internal use only Internal use only
#connection_global_id ⇒ Object readonly Internal use only Internal use only
#has_cursor_id? ⇒ true, false readonly Internal use only Internal use only

Whether the result contains cursor_id.
#ok? ⇒ true, false readonly

Check the first document’s ok field.
#replies ⇒ Array<Protocol::Message> readonly Internal use only Internal use only
#successful? ⇒ true, false readonly

If the result was a command then determine if it was considered a success.
#write_concern_error? ⇒ Boolean readonly Internal use only Internal use only

Whether the operation failed with a write concern error.
#query_failure? ⇒ Boolean readonly private

Instance Method Summary

#cluster_time ⇒ ClusterTime | nil

Get the cluster time reported in the server response.
#cursor_id ⇒ Integer Internal use only Internal use only

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 Internal use only Internal use only

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

Get the pretty formatted inspection of the result.
#labels ⇒ Array Internal use only Internal use only

Gets the set of error labels associated with the result.
#n

Alias for #written_count.
#namespace ⇒ Nil Internal use only Internal use only

Get the namespace of the cursor.
#operation_time ⇒ Object | nil

Get the operation time reported in the server response.
#reply ⇒ Protocol::Message Internal use only Internal use only

Get the reply from the result.
#returned_count ⇒ Integer

Get the number of documents returned by the server in this batch.
#snapshot_timestamp
#topology_version ⇒ TopologyVersion | nil Internal use only Internal use only
#validate! ⇒ Result Internal use only Internal use only

Validate the result by checking for any errors.
#written_count ⇒ Integer (also: #n)

Get the number of documents written by the server.
#aggregate_returned_count private
#aggregate_written_count private
#first_document private
#parser private
#raise_operation_failure private

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

Instance Attribute Details

#acknowledged? ⇒ `true`, `false` (readonly)

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?

Returns:

(true, false) —

If the result is acknowledged.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 157


def acknowledged?
  !!@replies
end

#connection_description ⇒ Server::Description (readonly)

This method is for internal use only.

Returns:

(Server::Description) —

::Mongo::Server description of the server that the operation was performed on that this result is for.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 133


attr_reader :connection_description

#connection_global_id ⇒ `Object` (readonly)

This method is for internal use only.

Returns:

(Object) —

Global is of the connection that the operation was performed on that this result is for.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 139


attr_reader :connection_global_id

#has_cursor_id? ⇒ `true`, `false` (readonly)

This method is for internal use only.

Whether the result contains cursor_id

Returns:

(true, false) —

If the result contains cursor_id.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 166


def has_cursor_id?
  acknowledged? && replies.last.respond_to?(:cursor_id)
end

#ok? ⇒ `true`, `false` (readonly)

Check the first document’s ok field.

Examples:

Check the ok field.

result.ok?

Returns:

(true, false) —

If the command returned ok.

Since:

2.1.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 305


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

#query_failure? ⇒ `Boolean` (readonly, private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 478


def query_failure?
  replies.first && (replies.first.query_failure? || replies.first.cursor_not_found?)
end

#replies ⇒ `Array`<Protocol::Message> (readonly)

This method is for internal use only.

Returns:

(Array<Protocol::Message>) —

replies The wrapped wire protocol replies.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 127


attr_reader :replies

#successful? ⇒ `true`, `false` (readonly)

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.

Examples:

Was the command successful?

result.successful?

Returns:

(true, false) —

If the command was successful.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 287


def successful?
  return true if !acknowledged?
  if first_document.has_key?(OK)
    ok? && parser.message.empty?
  else
    !query_failure? && parser.message.empty?
  end
end

#write_concern_error? ⇒ `Boolean` (readonly)

This method is for internal use only.

Whether the operation failed with a write concern error.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 444


def write_concern_error?
  !!(first_document && first_document['writeConcernError'])
end

Instance Method Details

#aggregate_returned_count (private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 456


def aggregate_returned_count
  replies.reduce(0) do |n, reply|
    n += reply.number_returned
    n
  end
end

#aggregate_written_count (private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 463


def aggregate_written_count
  documents.reduce(0) do |n, document|
    n += (document[N] || 0)
    n
  end
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 ::Mongo::ClusterTime, which is a subclass of BSON::Document. Previously it was an instance of BSON::Document.

Examples:

Get the cluster time.

result.cluster_time

Returns:

(ClusterTime | nil) —

The cluster time document.

Since:

2.5.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 424


def cluster_time
  first_document && ClusterTime[first_document['$clusterTime']]
end

#cursor_id ⇒ `Integer`

This method is for internal use only.

Note:

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

Get the cursor id if the response is acknowledged.

Examples:

Get the cursor id.

result.cursor_id

Returns:

(Integer) —

The cursor id.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 181


def cursor_id
  acknowledged? ? replies.last.cursor_id : 0
end

#documents ⇒ `Array`<`BSON::Document`>

Get the documents in the result.

Examples:

Get the documents.

result.documents

Returns:

(Array<BSON::Document>) —

The documents.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 205


def documents
  if acknowledged?
    replies.flat_map(&:documents)
  else
    []
  end
end

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

Iterate over the documents in the replies.

Examples:

Iterate over the documents.

result.each do |doc|
  p doc
end

Yield Parameters:

Each (BSON::Document) —

document in the result.

Returns:

(Enumerator) —

The enumerator.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 226


def each(&block)
  documents.each(&block)
end

#error ⇒ Error::OperationFailure

This method is for internal use only.

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

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

Returns:

(Error::OperationFailure) —

The exception.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 341


def error
  @error ||= Error::OperationFailure.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

#first_document (private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 474


def first_document
  @first_document ||= first || BSON::Document.new
end

#inspect ⇒ `String`

Get the pretty formatted inspection of the result.

Examples:

Inspect the result.

result.inspect

Returns:

(String) —

The inspection.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 239


def inspect
  "#<#{self.class.name}:0x#{object_id} documents=#{documents}>"
end

#labels ⇒ `Array`

This method is for internal use only.

Gets the set of error labels associated with the result.

Examples:

Get the labels.

result.labels

Returns:

(Array) —

labels The set of labels.

Since:

2.7.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 437


def labels
  @labels ||= parser.labels
end

#n

Alias for #written_count.

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 396


alias :n :written_count

#namespace ⇒ `Nil`

This method is for internal use only.

Get the namespace of the cursor. The method should be defined in result classes where ‘ns’ is in the server response.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 192


def namespace
  nil
end

#operation_time ⇒ `Object` | `nil`

Get the operation time reported in the server response.

Examples:

Get the operation time.

result.operation_time

Returns:

(Object | nil) —

The operation time value.

Since:

2.5.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 407


def operation_time
  first_document && first_document[OPERATION_TIME]
end

#parser (private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 470


def parser
  @parser ||= Error::Parser.new(first_document, replies)
end

#raise_operation_failure (private)

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

Raises:

::Mongo::Error::OperationFailure

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 363


private def raise_operation_failure
  raise error
end

#reply ⇒ Protocol::Message

This method is for internal use only.

Get the reply from the result.

Returns nil if there is no reply (i.e. the operation was an unacknowledged write).

Returns:

(Protocol::Message) —

The first reply.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 252


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.

Returns:

(Integer) —

The number of documents returned.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 266


def returned_count
  if acknowledged?
    reply.number_returned
  else
    0
  end
end

#snapshot_timestamp

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 448


def snapshot_timestamp
  if doc = reply.documents.first
    doc['cursor']&.[]('atClusterTime') || doc['atClusterTime']
  end
end

#topology_version ⇒ TopologyVersion | `nil`

This method is for internal use only.

Returns:

(TopologyVersion | nil) —

The topology version.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 370


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 for internal use only.

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.

Examples:

Validate the result.

result.validate!

Returns:

(Result) —

The result if verification passed.

Raises:

(Error::OperationFailure) —

If an error is in the result.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 329


def validate!
  !successful? ? raise_operation_failure : self
end

#written_count ⇒ `Integer` Also known as: #n

Get the number of documents written by the server.

Examples:

Get the number of documents written.

result.written_count

Returns:

(Integer) —

The number of documents written.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/operation/result.rb', line 387


def written_count
  if acknowledged?
    first_document[N] || 0
  else
    0
  end
end

Class: Mongo::Operation::Result

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#acknowledged? ⇒ true, false (readonly)

#connection_description ⇒ Server::Description (readonly)

#connection_global_id ⇒ Object (readonly)

#has_cursor_id? ⇒ true, false (readonly)

#ok? ⇒ true, false (readonly)

#query_failure? ⇒ Boolean (readonly, private)

#replies ⇒ Array<Protocol::Message> (readonly)

#successful? ⇒ true, false (readonly)

#write_concern_error? ⇒ Boolean (readonly)

Instance Method Details

#aggregate_returned_count (private)

#aggregate_written_count (private)

#cluster_time ⇒ ClusterTime | nil

#cursor_id ⇒ Integer

#documents ⇒ Array<BSON::Document>

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

#error ⇒ Error::OperationFailure

#first_document (private)

#inspect ⇒ String

#labels ⇒ Array

#n

#namespace ⇒ Nil

#operation_time ⇒ Object | nil

#parser (private)

#raise_operation_failure (private)

#reply ⇒ Protocol::Message

#returned_count ⇒ Integer

#snapshot_timestamp

#topology_version ⇒ TopologyVersion | nil

#validate! ⇒ Result

#written_count ⇒ Integer Also known as: #n

#acknowledged? ⇒ `true`, `false` (readonly)

#connection_global_id ⇒ `Object` (readonly)

#has_cursor_id? ⇒ `true`, `false` (readonly)

#ok? ⇒ `true`, `false` (readonly)

#query_failure? ⇒ `Boolean` (readonly, private)

#replies ⇒ `Array`<Protocol::Message> (readonly)

#successful? ⇒ `true`, `false` (readonly)

#write_concern_error? ⇒ `Boolean` (readonly)

#cluster_time ⇒ ClusterTime | `nil`

#cursor_id ⇒ `Integer`

#documents ⇒ `Array`<`BSON::Document`>

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

#inspect ⇒ `String`

#labels ⇒ `Array`

#namespace ⇒ `Nil`

#operation_time ⇒ `Object` | `nil`

#returned_count ⇒ `Integer`

#topology_version ⇒ TopologyVersion | `nil`

#validate! ⇒ `Result`

#written_count ⇒ `Integer` Also known as: #n