Class: Mongo::Cursor

Inherits:

Object

• Object
• Mongo::Cursor

show all

Includes:

Enumerable, Constants, Conversions, Logging, ReadPreference

Defined in:

lib/mongo/cursor.rb

Overview

Constant Summary

Constant Summary

Constants included from ReadPreference

ReadPreference::MONGOS_MODES, ReadPreference::READ_PREFERENCES

Constants included from Conversions

Mongo::Conversions::ASCENDING_CONVERSION, Mongo::Conversions::DESCENDING_CONVERSION

Constants included from Constants

Mongo::Constants::OP_DELETE, Mongo::Constants::OP_GET_MORE, Mongo::Constants::OP_INSERT, Mongo::Constants::OP_KILL_CURSORS, Mongo::Constants::OP_MSG, Mongo::Constants::OP_QUERY, Mongo::Constants::OP_QUERY_AWAIT_DATA, Mongo::Constants::OP_QUERY_EXHAUST, Mongo::Constants::OP_QUERY_NO_CURSOR_TIMEOUT, Mongo::Constants::OP_QUERY_OPLOG_REPLAY, Mongo::Constants::OP_QUERY_SLAVE_OK, Mongo::Constants::OP_QUERY_TAILABLE, Mongo::Constants::OP_REPLY, Mongo::Constants::OP_UPDATE, Mongo::Constants::REPLY_AWAIT_CAPABLE, Mongo::Constants::REPLY_CURSOR_NOT_FOUND, Mongo::Constants::REPLY_QUERY_FAILURE, Mongo::Constants::REPLY_SHARD_CONFIG_STALE

Instance Attribute Summary (collapse)

• - (Object) acceptable_latency readonly

  Returns the value of attribute acceptable_latency.

• - (Object) collection readonly

  Returns the value of attribute collection.

• - (Object) comment readonly

  Returns the value of attribute comment.

• - (Object) cursor_id readonly

  Returns the value of attribute cursor_id.

• - (Object) fields readonly

  Returns the value of attribute fields.

• - (Object) full_collection_name readonly

  Returns the value of attribute full_collection_name.

• - (Object) hint readonly

  Returns the value of attribute hint.

• - (Object) options readonly

  Returns the value of attribute options.

• - (Object) order readonly

  Returns the value of attribute order.

• - (Object) read readonly

  Returns the value of attribute read.

• - (Object) selector readonly

  Returns the value of attribute selector.

• - (Object) show_disk_loc readonly

  Returns the value of attribute show_disk_loc.

• - (Object) snapshot readonly

  Returns the value of attribute snapshot.

• - (Object) tag_sets readonly

  Returns the value of attribute tag_sets.

• - (Object) timeout readonly

  Returns the value of attribute timeout.

• - (Object) transformer readonly

  Returns the value of attribute transformer.

Instance Method Summary (collapse)

• - (Integer) add_option(opt)

  Add an option to the query options bitfield.

• - (Boolean) alive?

  Guess whether the cursor is alive on the server.

• - (Cursor) batch_size(size = nil)

  Set the batch size for server responses.

• - (True) close

  Close the cursor.

• - (Boolean) closed?

  Is this cursor closed?.

• - (Integer) count(skip_and_limit = false)

  Get the size of the result set for this query.

• - (Object) each { ... }

  Iterate over each document in this cursor, yielding it to the given block, if provided.

• - (Hash) explain

  Get the explain plan for this cursor.

• - (Boolean) has_next?

  Determine whether this cursor has any remaining results.

• - (Cursor) initialize(collection, opts = {}) constructor

  Create a new cursor.

• - (Object) inspect

  Clean output for inspect.

• - (Integer) limit(number_to_return = nil)

  Limit the number of results to be returned by this cursor.

• - (Hash, Nil) next (also: #next_document)

  Get the next document specified the cursor options.

• - (Hash) query_options_hash

  Get the query options for this Cursor.

• - (Integer) query_opts

  Returns an integer indicating which query options have been selected.

• - (Integer) remove_option(opt)

  Remove an option from the query options bitfield.

• - (Object) rewind!

  Reset this cursor on the server.

• - (Integer) skip(number_to_skip = nil)

  Skips the first number_to_skip results of this cursor.

• - (Object) sort(order, direction = nil)

  Sort this cursor's results.

• - (Array) to_a

  Receive all the documents from this cursor as an array of hashes.

Methods included from ReadPreference

mongos, #read_pool, #read_preference, #select_near_pool, #select_pool, #select_secondary_pool, validate

Methods included from Logging

#instrument, instrumenter, instrumenter=, #log, #write_logging_startup_message

Methods included from Conversions

#array_as_sort_parameters, #hash_as_sort_parameters, #sort_value, #string_as_sort_parameters

39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# File 'lib/mongo/cursor.rb', line 39

def initialize(collection, opts={})
  @cursor_id  = nil
  @db         = collection.db
  @collection = collection
  @connection = @db.connection
  @logger     = @connection.logger

  # Query selector
  @selector   = opts[:selector] || {}

  # Special operators that form part of $query
  @order      = opts[:order]
  @explain    = opts[:explain]
  @hint       = opts[:hint]
  @snapshot   = opts[:snapshot]
  @max_scan   = opts.fetch(:max_scan, nil)
  @return_key = opts.fetch(:return_key, nil)
  @show_disk_loc = opts.fetch(:show_disk_loc, nil)
  @comment    = opts[:comment]

  # Wire-protocol settings
  @fields     = convert_fields_for_query(opts[:fields])
  @skip       = opts[:skip]     || 0
  @limit      = opts[:limit]    || 0
  @tailable   = opts[:tailable] || false
  @timeout    = opts.fetch(:timeout, true)
  @options    = 0

  # Use this socket for the query
  @socket = opts[:socket]
  @pool   = nil

  @closed       = false
  @query_run    = false

  @transformer = opts[:transformer]
  @read =  opts[:read] || @collection.read
  Mongo::ReadPreference::validate(@read)
  @tag_sets = opts[:tag_sets] || @collection.tag_sets
  @acceptable_latency = opts[:acceptable_latency] || @collection.acceptable_latency

  batch_size(opts[:batch_size] || 0)

  @full_collection_name = "#{@collection.db.name}.#{@collection.name}"
  @cache        = []
  @returned     = 0

  if(!@timeout)
    add_option(OP_QUERY_NO_CURSOR_TIMEOUT)
  end
  if(@read != :primary)
    add_option(OP_QUERY_SLAVE_OK)
  end
  if(@tailable)
    add_option(OP_QUERY_TAILABLE)
  end

  if @collection.name =~ /^\$cmd/ || @collection.name =~ /^system/
    @command = true
  else
    @command = false
  end
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def acceptable_latency
  @acceptable_latency
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def collection
  @collection
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def comment
  @comment
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def cursor_id
  @cursor_id
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def fields
  @fields
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def full_collection_name
  @full_collection_name
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def hint
  @hint
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def options
  @options
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def order
  @order
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def read
  @read
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def selector
  @selector
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def show_disk_loc
  @show_disk_loc
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def snapshot
  @snapshot
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def tag_sets
  @tag_sets
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def timeout
  @timeout
end

25
26
27

# File 'lib/mongo/cursor.rb', line 25

def transformer
  @transformer
end

381
382
383
384
385
386

# File 'lib/mongo/cursor.rb', line 381

def add_option(opt)
  check_modifiable

  @options |= opt
  @options
end

111
112
113

# File 'lib/mongo/cursor.rb', line 111

def alive?
  @cursor_id && @cursor_id != 0
end

260
261
262
263
264
265
266
267
268
269
270

# File 'lib/mongo/cursor.rb', line 260

def batch_size(size=nil)
  return @batch_size unless size
  check_modifiable
  if size < 0 || size == 1
    raise ArgumentError, "Invalid value for batch_size #{size}; must be 0 or > 1."
  else
    @batch_size = @limit != 0 && size > @limit ? @limit : size
  end

  self
end

336
337
338
339
340
341
342
343
344
345
346
347
348
349
350

# File 'lib/mongo/cursor.rb', line 336

def close
  if @cursor_id && @cursor_id != 0
    message = BSON::ByteBuffer.new([0, 0, 0, 0])
    message.put_int(1)
    message.put_long(@cursor_id)
    log(:debug, "Cursor#close #{@cursor_id}")
    @connection.send_message(
      Mongo::Constants::OP_KILL_CURSORS,
      message,
      :pool => @pool
    )
  end
  @cursor_id = 0
  @closed    = true
end

355
356
357

# File 'lib/mongo/cursor.rb', line 355

def closed?
  @closed
end

177
178
179
180
181
182
183
184
185
186
187
188
189
190
191

# File 'lib/mongo/cursor.rb', line 177

def count(skip_and_limit = false)
  command = BSON::OrderedHash["count",  @collection.name, "query",  @selector]

  if skip_and_limit
    command.merge!(BSON::OrderedHash["limit", @limit]) if @limit != 0
    command.merge!(BSON::OrderedHash["skip", @skip]) if @skip != 0
  end

  command.merge!(BSON::OrderedHash["fields", @fields])

  response = @db.command(command, :read => @read, :comment => @comment)
  return response['n'].to_i if Mongo::Support.ok?(response)
  return 0 if response['errmsg'] == "ns missing"
  raise OperationFailure.new("Count failed: #{response['errmsg']}", response['code'], response)
end

comments.find.each do |doc|
  puts doc['user']
end

283
284
285
286
287
288
289
290
291
292
293
294
295

# File 'lib/mongo/cursor.rb', line 283

def each
  if block_given? || !defined?(Enumerator)
    while doc = self.next
      yield doc
    end
  else
    Enumerator.new do |yielder|
      while doc = self.next
        yielder.yield doc
      end
    end
  end
end

317
318
319
320
321
322
323
324

# File 'lib/mongo/cursor.rb', line 317

def explain
  c = Cursor.new(@collection,
    query_options_hash.merge(:limit => -@limit.abs, :explain => true))
  explanation = c.next_document
  c.close

  explanation
end

166
167
168

# File 'lib/mongo/cursor.rb', line 166

def has_next?
  num_remaining > 0
end

425
426
427
428

# File 'lib/mongo/cursor.rb', line 425

def inspect
  "<Mongo::Cursor:0x#{object_id.to_s(16)} namespace='#{@db.name}.#{@collection.name}' " +
    "@selector=#{@selector.inspect} @cursor_id=#{@cursor_id}>"
end

224
225
226
227
228
229

# File 'lib/mongo/cursor.rb', line 224

def limit(number_to_return=nil)
  return @limit unless number_to_return
  check_modifiable
  @limit = number_to_return
  self
end

118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

# File 'lib/mongo/cursor.rb', line 118

def next
  if @cache.length == 0
    if @query_run && (@options & OP_QUERY_EXHAUST != 0)
      close
      return nil
    else
      refresh
    end
  end
  doc = @cache.shift

  if doc && doc['$err']
    err = doc['$err']

    # If the server has stopped being the master (e.g., it's one of a
    # pair but it has died or something like that) then we close that
    # connection. The next request will re-open on master server.
    if err.include?("not master")
      @connection.close
      raise ConnectionFailure.new(err, doc['code'], doc)
    end

    raise OperationFailure.new(err, doc['code'], doc)
  end

  if @transformer.nil?
    doc
  else
    @transformer.call(doc) if doc
  end
end

408
409
410
411
412
413
414
415
416
417
418
419
420
421
422

# File 'lib/mongo/cursor.rb', line 408

def query_options_hash
  BSON::OrderedHash[
    :selector => @selector,
    :fields   => @fields,
    :skip     => @skip,
    :limit    => @limit,
    :order    => @order,
    :hint     => @hint,
    :snapshot => @snapshot,
    :timeout  => @timeout,
    :max_scan => @max_scan,
    :return_key => @return_key,
    :show_disk_loc => @show_disk_loc,
    :comment  => @comment ]
end

365
366
367
368
369

# File 'lib/mongo/cursor.rb', line 365

def query_opts
  warn "The method Cursor#query_opts has been deprecated " +
    "and will removed in v2.0. Use Cursor#options instead."
  @options
end

398
399
400
401
402
403

# File 'lib/mongo/cursor.rb', line 398

def remove_option(opt)
  check_modifiable

  @options &= ~opt
  @options
end

153
154
155
156
157
158
159
160
161

# File 'lib/mongo/cursor.rb', line 153

def rewind!
  close
  @cache.clear
  @cursor_id  = nil
  @closed     = false
  @query_run  = false
  @n_received = nil
  true
end

240
241
242
243
244
245
246

# File 'lib/mongo/cursor.rb', line 240

def skip(number_to_skip=nil)
  return @skip unless number_to_skip
  check_modifiable

  @skip = number_to_skip
  self
end

207
208
209
210
211
212

# File 'lib/mongo/cursor.rb', line 207

def sort(order, direction=nil)
  check_modifiable
  order = [[order, direction]] unless direction.nil?
  @order = order
  self
end

308
309
310

# File 'lib/mongo/cursor.rb', line 308

def to_a
  super
end