Class: Mongo::Operation::Result

Inherits:
Object
  • Object
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 operations.

Since:

  • 2.0.0

Defined Under Namespace

Modules: Aggregatable, UseLegacyErrorParser

Constant Summary collapse

CURSOR =

The field name for the cursor document in an aggregation.

Since:

  • 2.2.0

'cursor'.freeze
CURSOR_ID =

The cursor id field in the cursor document.

Since:

  • 2.2.0

'id'.freeze
FIRST_BATCH =

The field name for the first batch of a cursor.

Since:

  • 2.2.0

'firstBatch'.freeze
NEXT_BATCH =

The field name for the next batch of a cursor.

Since:

  • 2.2.0

'nextBatch'.freeze
NAMESPACE =

The namespace field in the cursor document.

Since:

  • 2.2.0

'ns'.freeze
N =

The number of documents updated in the write.

Since:

  • 2.0.0

'n'.freeze
OK =

The ok status field in the result.

Since:

  • 2.0.0

'ok'.freeze
RESULT =

The result field constant.

Since:

  • 2.2.0

'result'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(replies) ⇒ Result

Initialize a new result.

Examples:

Instantiate the result.

Result.new(replies)

Parameters:

Since:

  • 2.0.0



76
77
78
# File 'lib/mongo/operation/result.rb', line 76

def initialize(replies)
  @replies = [ *replies ] if replies
end

Instance Attribute Details

#repliesArray<Protocol::Reply> (readonly)

Returns replies The wrapped wire protocol replies.

Returns:

Since:

  • 2.0.0



81
82
83
# File 'lib/mongo/operation/result.rb', line 81

def replies
  @replies
end

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?

Returns:

  • (true, false)

    If the result is acknowledged.

Since:

  • 2.0.0



98
99
100
# File 'lib/mongo/operation/result.rb', line 98

def acknowledged?
  !!@replies
end

#cluster_timenil | ClusterTime

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.

Examples:

Get the cluster time.

result.cluster_time

Returns:

Since:

  • 2.5.0



342
343
344
# File 'lib/mongo/operation/result.rb', line 342

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

#cursor_idInteger

Note:

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



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

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

#documentsArray<BSON::Document>

Get the documents in the result.

Examples:

Get the documents.

result.documents

Returns:

  • (Array<BSON::Document>)

    The documents.

Since:

  • 2.0.0



147
148
149
150
151
152
153
# File 'lib/mongo/operation/result.rb', line 147

def documents
  if acknowledged?
    replies.flat_map{ |reply| reply.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



167
168
169
# File 'lib/mongo/operation/result.rb', line 167

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

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

Returns:

Since:

  • 2.0.0



279
280
281
282
283
284
285
286
287
288
289
290
# File 'lib/mongo/operation/result.rb', line 279

def error
  @error ||= Error::OperationFailure.new(
    parser.message,
    self,
    code: parser.code,
    code_name: parser.code_name,
    write_concern_error: parser.write_concern_error?,
    write_concern_error_code: parser.write_concern_error_code,
    write_concern_error_code_name: parser.write_concern_error_code_name,
    labels: parser.labels,
    wtimeout: parser.wtimeout)
end

#inspectString

Get the pretty formatted inspection of the result.

Examples:

Inspect the result.

result.inspect

Returns:

  • (String)

    The inspection.

Since:

  • 2.0.0



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

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

#labelsArray

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



354
355
356
# File 'lib/mongo/operation/result.rb', line 354

def labels
  @labels ||= parser.labels
end

#multiple?true, false

Determine if this result is a collection of multiple replies from the server.

Examples:

Is the result for multiple replies?

result.multiple?

Returns:

  • (true, false)

    If the result is for multiple replies.

Since:

  • 2.0.0



111
112
113
# File 'lib/mongo/operation/result.rb', line 111

def multiple?
  replies.size > 1
end

#namespaceNil

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

Returns:

  • (Nil)

Since:

  • 2.0.0



135
136
137
# File 'lib/mongo/operation/result.rb', line 135

def namespace
  nil
end

#ok?true, false

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



244
245
246
247
248
249
250
251
# File 'lib/mongo/operation/result.rb', line 244

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_timeObject

Get the operation time reported in the server response.

Examples:

Get the operation time.

result.operation_time

Returns:

  • (Object)

    The operation time value.

Since:

  • 2.5.0



326
327
328
# File 'lib/mongo/operation/result.rb', line 326

def operation_time
  first_document && first_document[OPERATION_TIME]
end

#replyProtocol::Reply

Get the first reply from the result.

Examples:

Get the first reply.

result.reply

Returns:

Since:

  • 2.0.0



191
192
193
194
195
196
197
# File 'lib/mongo/operation/result.rb', line 191

def reply
  if acknowledged?
    replies.first
  else
    nil
  end
end

#returned_countInteger

Get the count of documents returned by the server.

Examples:

Get the number returned.

result.returned_count

Returns:

  • (Integer)

    The number of documents returned.

Since:

  • 2.0.0



207
208
209
210
211
212
213
# File 'lib/mongo/operation/result.rb', line 207

def returned_count
  if acknowledged?
    multiple? ? aggregate_returned_count : reply.number_returned
  else
    0
  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.

Examples:

Was the command successful?

result.successful?

Returns:

  • (true, false)

    If the command was successful.

Since:

  • 2.0.0



227
228
229
230
231
232
233
234
# File 'lib/mongo/operation/result.rb', line 227

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!Result

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:

Since:

  • 2.0.0



267
268
269
# File 'lib/mongo/operation/result.rb', line 267

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.

Returns:

  • (Boolean)

Since:

  • 2.0.0



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

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

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



309
310
311
312
313
314
315
# File 'lib/mongo/operation/result.rb', line 309

def written_count
  if acknowledged?
    multiple? ? aggregate_written_count : (first_document[N] || 0)
  else
    0
  end
end