Class: Mongo::Operation::Result

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/mongo/operation/result.rb

Overview

Result wrapper for operations.

Since:

  • 2.0.0

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



160
161
162
 
# File 'lib/mongo/operation/result.rb', line 160

def initialize(replies)
  @replies = replies.is_a?(Protocol::Reply) ? [ replies ] : replies
end

Instance Attribute Details

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

Returns replies The wrapped wire protocol replies.

Returns:

Since:

  • 2.0.0



66
67
68
 
# File 'lib/mongo/operation/result.rb', line 66

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



79
80
81
 
# File 'lib/mongo/operation/result.rb', line 79

def acknowledged?
  !!@replies
end

#cursor_id ⇒ Integer

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



106
107
108
 
# File 'lib/mongo/operation/result.rb', line 106

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



128
129
130
131
132
133
134
 
# File 'lib/mongo/operation/result.rb', line 128

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



148
149
150
 
# File 'lib/mongo/operation/result.rb', line 148

def each(&block)
  documents.each(&block)
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



172
173
174
 
# File 'lib/mongo/operation/result.rb', line 172

def inspect
  "#<Mongo::Operation::Result:#{object_id} documents=#{documents}>"
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



92
93
94
 
# File 'lib/mongo/operation/result.rb', line 92

def multiple?
  replies.size > 1
end

#namespace ⇒ Nil

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



116
117
118
 
# File 'lib/mongo/operation/result.rb', line 116

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



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

def ok?
  first_document[OK] == 1
end

#reply ⇒ Protocol::Reply

Get the first reply from the result.

Examples:

Get the first reply.

result.reply

Returns:

Since:

  • 2.0.0



184
185
186
187
188
189
190
 
# File 'lib/mongo/operation/result.rb', line 184

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

#returned_count ⇒ Integer

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



200
201
202
203
204
205
206
 
# File 'lib/mongo/operation/result.rb', line 200

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



220
221
222
223
224
225
226
227
 
# File 'lib/mongo/operation/result.rb', line 220

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



255
256
257
 
# File 'lib/mongo/operation/result.rb', line 255

def validate!
  !successful? ? raise(Error::OperationFailure.new(parser.message)) : 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



267
268
269
270
271
272
273
 
# File 'lib/mongo/operation/result.rb', line 267

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