Module: Mongo::Collection::View::Readable

Included in:
Mongo::Collection::View
Defined in:
lib/mongo/collection/view/readable.rb

Overview

Defines read related behavior for collection view.

Since:

  • 2.0.0

Instance Method Summary collapse

Instance Method Details

#aggregate(pipeline, options = {}) ⇒ Aggregation

Execute an aggregation on the collection view.

Examples:

Aggregate documents.

view.aggregate([
  { "$group" => { "_id" => "$city", "tpop" => { "$sum" => "$pop" }}}
])

Options Hash (options):

  • :allow_disk_use (true, false) —

    Set to true if disk usage is allowed during the aggregation.

  • :batch_size (Integer) —

    The number of documents to return per batch.

  • :bypass_document_validation (true, false) —

    Whether or not to skip document level validation.

  • :collation (Hash) —

    The collation to use.

  • :comment (Object) —

    A user-provided comment to attach to this command.

  • :hint (String) —

    The index to use for the aggregation.

  • :let (Hash) —

    Mapping of variables to use in the pipeline. See the server documentation for details.

  • :max_time_ms (Integer) —

    The maximum amount of time in milliseconds to allow the aggregation to run. This option is deprecated, use :timeout_ms instead.

  • :session (Session) —

    The session to use.

  • :timeout_ms (Integer) —

    The operation timeout in milliseconds. Must be a non-negative integer. An explicit value of 0 means infinite. The default value is unset which means the value is inherited from the collection or the database or the client.

Since:

  • 2.0.0



61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/mongo/collection/view/readable.rb', line 61

def aggregate(pipeline, options = {})
  options = @options.merge(options) unless Mongo.broken_view_options
  aggregation = Aggregation.new(self, pipeline, options)

  # Because the $merge and $out pipeline stages write documents to the
  # collection, it is necessary to clear the cache when they are performed.
  #
  # Opt to clear the entire cache rather than one namespace because
  # the $out and $merge stages do not have to write to the same namespace
  # on which the aggregation is performed.
  QueryCache.clear if aggregation.write?

  aggregation
end

#allow_disk_use ⇒ View

Allows the server to write temporary data to disk while executing a find operation.

Since:

  • 2.0.0



80
81
82
 
# File 'lib/mongo/collection/view/readable.rb', line 80

def allow_disk_use
  configure(:allow_disk_use, true)
end

#allow_partial_results ⇒ View

Allows the query to get partial results if some shards are down.

Examples:

Allow partial results.

view.allow_partial_results

Since:

  • 2.0.0



92
93
94
 
# File 'lib/mongo/collection/view/readable.rb', line 92

def allow_partial_results
  configure(:allow_partial_results, true)
end

#await_data ⇒ View

Tell the query’s cursor to stay open and wait for data.

Examples:

Await data on the cursor.

view.await_data

Since:

  • 2.0.0



104
105
106
 
# File 'lib/mongo/collection/view/readable.rb', line 104

def await_data
  configure(:await_data, true)
end

#batch_size(batch_size = nil) ⇒ Integer, View

Note:

Specifying 1 or a negative number is analogous to setting a limit.

The number of documents returned in each batch of results from MongoDB.

Examples:

Set the batch size.

view.batch_size(5)

Since:

  • 2.0.0



121
122
123
 
# File 'lib/mongo/collection/view/readable.rb', line 121

def batch_size(batch_size = nil)
  configure(:batch_size, batch_size)
end

#comment(comment = nil) ⇒ String, View

Note:

Set profilingLevel to 2 and the comment will be logged in the profile collection along with the query.

Associate a comment with the query.

Examples:

Add a comment.

view.comment('slow query')

Since:

  • 2.0.0



139
140
141
 
# File 'lib/mongo/collection/view/readable.rb', line 139

def comment(comment = nil)
  configure(:comment, comment)
end

#count(opts = {}) ⇒ Integer

Deprecated.

Use #count_documents or #estimated_document_count instead. However, note that the following operators will need to be substituted when switching to #count_documents:

* $where should be replaced with $expr (only works on 3.6+)
* $near should be replaced with $geoWithin with $center
* $nearSphere should be replaced with $geoWithin with $centerSphere

Get a count of matching documents in the collection.

Examples:

Get the number of documents in the collection.

collection_view.count

Options Hash (opts):

  • :skip (Integer) —

    The number of documents to skip.

  • :hint (Hash) —

    Override default index selection and force MongoDB to use a specific index for the query.

  • :limit (Integer) —

    Max number of docs to count.

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run.

  • :read (Hash) —

    The read preference options.

  • :collation (Hash) —

    The collation to use.

  • :session (Mongo::Session) —

    The session to use for the operation.

  • :comment (Object) —

    A user-provided comment to attach to this command.

Since:

  • 2.0.0



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/mongo/collection/view/readable.rb', line 175

def count(opts = {})
  opts = @options.merge(opts) unless Mongo.broken_view_options
  cmd = { :count => collection.name, :query => filter }
  cmd[:skip] = opts[:skip] if opts[:skip]
  cmd[:hint] = opts[:hint] if opts[:hint]
  cmd[:limit] = opts[:limit] if opts[:limit]
  if read_concern
    cmd[:readConcern] = Options::Mapper.transform_values_to_strings(
      read_concern)
  end
  cmd[:maxTimeMS] = opts[:max_time_ms] if opts[:max_time_ms]
  Mongo::Lint.validate_underscore_read_preference(opts[:read])
  read_pref = opts[:read] || read_preference
  selector = ServerSelector.get(read_pref || server_selector)
  with_session(opts) do |session|
    context = Operation::Context.new(
      client: client,
      session: session,
      operation_timeouts: operation_timeouts(opts)
    )
    operation = Operation::Count.new(
      selector: cmd,
      db_name: database.name,
      options: {:limit => -1},
      read: read_pref,
      session: session,
      # For some reason collation was historically accepted as a
      # string key. Note that this isn't documented as valid usage.
      collation: opts[:collation] || opts['collation'] || collation,
      comment: opts[:comment],
    )
    tracer.trace_operation(operation, context) do
      read_with_retry(session, selector, context) do |server|
        operation.execute(
          server,
          context: context
        )
      end.n.to_i
    end
  end
end

#count_documents(opts = {}) ⇒ Integer

Get a count of matching documents in the collection.

Examples:

Get the number of documents in the collection.

collection_view.count

Options Hash (opts):

  • :skip (Integer) —

    The number of documents to skip.

  • :hint (Hash) —

    Override default index selection and force MongoDB to use a specific index for the query. Requires server version 3.6+.

  • :limit (Integer) —

    Max number of docs to count.

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run. This option is deprecated, use :timeout_ms instead.

  • :read (Hash) —

    The read preference options.

  • :collation (Hash) —

    The collation to use.

  • :session (Mongo::Session) —

    The session to use for the operation.

Since:

  • 2.6.0



244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/mongo/collection/view/readable.rb', line 244

def count_documents(opts = {})
  opts = @options.merge(opts) unless Mongo.broken_view_options
  pipeline = [:'$match' => filter]
  pipeline << { :'$skip' => opts[:skip] } if opts[:skip]
  pipeline << { :'$limit' => opts[:limit] } if opts[:limit]
  pipeline << { :'$group' => { _id: 1, n: { :'$sum' => 1 } } }

  opts = opts.slice(:hint, :max_time_ms, :read, :collation, :session, :comment, :timeout_ms)
  opts[:collation] ||= collation

  first = aggregate(pipeline, opts).first
  return 0 unless first
  first['n'].to_i
end

#cursor_type(type = nil) ⇒ :tailable, ...

The type of cursor to use. Can be :tailable or :tailable_await.

Examples:

Set the cursor type.

view.cursor_type(:tailable)

Since:

  • 2.3.0



669
670
671
 
# File 'lib/mongo/collection/view/readable.rb', line 669

def cursor_type(type = nil)
  configure(:cursor_type, type)
end

#distinct(field_name, opts = {}) ⇒ Array<Object>

Get a list of distinct values for a specific field.

Examples:

Get the distinct values.

collection_view.distinct('name')

Options Hash (opts):

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run.

  • :read (Hash) —

    The read preference options.

  • :collation (Hash) —

    The collation to use.

Since:

  • 2.0.0



349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/mongo/collection/view/readable.rb', line 349

def distinct(field_name, opts = {})
  if field_name.nil?
    raise ArgumentError, 'Field name for distinct operation must be not nil'
  end
  opts = @options.merge(opts) unless Mongo.broken_view_options
  cmd = { :distinct => collection.name,
          :key => field_name.to_s,
          :query => filter, }
  cmd[:maxTimeMS] = opts[:max_time_ms] if opts[:max_time_ms]
  if read_concern
    cmd[:readConcern] = Options::Mapper.transform_values_to_strings(
      read_concern)
  end
  Mongo::Lint.validate_underscore_read_preference(opts[:read])
  read_pref = opts[:read] || read_preference
  selector = ServerSelector.get(read_pref || server_selector)
  with_session(opts) do |session|
    context = Operation::Context.new(
      client: client,
      session: session,
      operation_timeouts: operation_timeouts(opts)
    )
    operation = Operation::Distinct.new(
      selector: cmd,
      db_name: database.name,
      options: {:limit => -1},
      read: read_pref,
      session: session,
      comment: opts[:comment],
      # For some reason collation was historically accepted as a
      # string key. Note that this isn't documented as valid usage.
      collation: opts[:collation] || opts['collation'] || collation,
    )
    tracer.trace_operation(operation, context) do
      read_with_retry(session, selector, context) do |server|
        operation.execute(
          server,
          context: context
        )
      end.first['values']
    end
  end
end

#estimated_document_count(opts = {}) ⇒ Integer

Gets an estimate of the count of documents in a collection using collection metadata.

Examples:

Get the number of documents in the collection.

collection_view.estimated_document_count

Options Hash (opts):

  • :max_time_ms (Integer) —

    The maximum amount of time to allow the command to run.

  • :read (Hash) —

    The read preference options.

  • :comment (Object) —

    A user-provided comment to attach to this command.

Since:

  • 2.6.0



279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
 
# File 'lib/mongo/collection/view/readable.rb', line 279

def estimated_document_count(opts = {})
  unless view.filter.empty?
    raise ArgumentError, "Cannot call estimated_document_count when querying with a filter"
  end

  i[limit skip].each do |opt|
    if options.key?(opt) || opts.key?(opt)
      raise ArgumentError, "Cannot call estimated_document_count when querying with #{opt}"
    end
  end

  opts = @options.merge(opts) unless Mongo.broken_view_options
  Mongo::Lint.validate_underscore_read_preference(opts[:read])
  read_pref = opts[:read] || read_preference
  selector = ServerSelector.get(read_pref || server_selector)
  with_session(opts) do |session|
    context = Operation::Context.new(
      client: client,
      session: session,
      operation_timeouts: operation_timeouts(opts)
    )
    cmd = { count: collection.name }
    cmd[:maxTimeMS] = opts[:max_time_ms] if opts[:max_time_ms]
    if read_concern
      cmd[:readConcern] = Options::Mapper.transform_values_to_strings(read_concern)
    end
    operation = Operation::Count.new(
      selector: cmd,
      db_name: database.name,
      read: read_pref,
      session: session,
      comment: opts[:comment],
    )
    tracer.trace_operation(operation, context, op_name: 'estimatedDocumentCount') do
      read_with_retry(session, selector, context) do |server|
        result = operation.execute(server, context: context)
        result.n.to_i
      end
    rescue Error::OperationFailure::Family => exc
      if exc.code == 26
        # NamespaceNotFound
        # This should only happen with the aggregation pipeline path
        # (server 4.9+). Previous servers should return 0 for nonexistent
        # collections.
        0
      else
        raise
      end
    end
  end
end

#hint(hint = nil) ⇒ Hash, View

The index that MongoDB will be forced to use for the query.

Examples:

Set the index hint.

view.hint(name: 1)

Since:

  • 2.0.0



403
404
405
 
# File 'lib/mongo/collection/view/readable.rb', line 403

def hint(hint = nil)
  configure(:hint, hint)
end

#limit(limit = nil) ⇒ Integer, View

The max number of docs to return from the query.

Examples:

Set the limit.

view.limit(5)

Since:

  • 2.0.0



417
418
419
 
# File 'lib/mongo/collection/view/readable.rb', line 417

def limit(limit = nil)
  configure(:limit, limit)
end

#map_reduce(map, reduce, options = {}) ⇒ MapReduce

Execute a map/reduce operation on the collection view.

Examples:

Execute a map/reduce.

view.map_reduce(map, reduce)

Since:

  • 2.0.0



433
434
435
 
# File 'lib/mongo/collection/view/readable.rb', line 433

def map_reduce(map, reduce, options = {})
  MapReduce.new(self, map, reduce, @options.merge(options))
end

#max_await_time_ms(max = nil) ⇒ Integer, View

A cumulative time limit in milliseconds for processing get more operations on a cursor.

Examples:

Set the max await time ms value.

view.max_await_time_ms(500)

Since:

  • 2.1.0



641
642
643
 
# File 'lib/mongo/collection/view/readable.rb', line 641

def max_await_time_ms(max = nil)
  configure(:max_await_time_ms, max)
end

#max_scan(value = nil) ⇒ Integer, View

Deprecated.

This option is deprecated as of MongoDB server version 4.0.

Set the max number of documents to scan.

Examples:

Set the max scan value.

view.max_scan(1000)

Since:

  • 2.0.0



450
451
452
 
# File 'lib/mongo/collection/view/readable.rb', line 450

def max_scan(value = nil)
  configure(:max_scan, value)
end

#max_time_ms(max = nil) ⇒ Integer, View

A cumulative time limit in milliseconds for processing operations on a cursor.

Examples:

Set the max time ms value.

view.max_time_ms(500)

Since:

  • 2.1.0



655
656
657
 
# File 'lib/mongo/collection/view/readable.rb', line 655

def max_time_ms(max = nil)
  configure(:max_time_ms, max)
end

#max_value(value = nil) ⇒ Hash, View

Set the maximum value to search.

Examples:

Set the max value.

view.max_value(_id: 1)

Since:

  • 2.1.0



464
465
466
 
# File 'lib/mongo/collection/view/readable.rb', line 464

def max_value(value = nil)
  configure(:max_value, value)
end

#min_value(value = nil) ⇒ Hash, View

Set the minimum value to search.

Examples:

Set the min value.

view.min_value(_id: 1)

Since:

  • 2.1.0



478
479
480
 
# File 'lib/mongo/collection/view/readable.rb', line 478

def min_value(value = nil)
  configure(:min_value, value)
end

#modifiers(doc = nil) ⇒ Hash, View

If called without arguments or with a nil argument, returns the legacy (OP_QUERY) server modifiers for the current view. If called with a non-nil argument, which must be a Hash or a subclass, merges the provided modifiers into the current view. Both string and symbol keys are allowed in the input hash.

Examples:

Set the modifiers document.

view.modifiers(:$orderby => Mongo::Index::ASCENDING)

Since:

  • 2.1.0



622
623
624
625
626
627
628
 
# File 'lib/mongo/collection/view/readable.rb', line 622

def modifiers(doc = nil)
  if doc.nil?
    Operation::Find::Builder::Modifiers.map_server_modifiers(options)
  else
    new(options.merge(Operation::Find::Builder::Modifiers.map_driver_options(BSON::Document.new(doc))))
  end
end

#no_cursor_timeout ⇒ View

The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use. Set this option to prevent that.

Examples:

Set the cursor to not timeout.

view.no_cursor_timeout

Since:

  • 2.0.0



491
492
493
 
# File 'lib/mongo/collection/view/readable.rb', line 491

def no_cursor_timeout
  configure(:no_cursor_timeout, true)
end

#parallel_scan(cursor_count, options = {}) ⇒ Object

Since:

  • 2.0.0



711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
 
# File 'lib/mongo/collection/view/readable.rb', line 711

def parallel_scan(cursor_count, options = {})
  if options[:session]
    # The session would be overwritten by the one in +options+ later.
    session = client.get_session(@options)
  else
    session = nil
  end
  server = server_selector.select_server(cluster, nil, session)
  spec = {
    coll_name: collection.name,
    db_name: database.name,
    cursor_count: cursor_count,
    read_concern: read_concern,
    session: session,
  }.update(options)
  session = spec[:session]
  op = Operation::ParallelScan.new(spec)
  # Note that the context object shouldn't be reused for subsequent
  # GetMore operations.
  context = Operation::Context.new(client: client, session: session)
  result = op.execute(server, context: context)
  result.cursor_ids.map do |cursor_id|
    spec = {
      cursor_id: cursor_id,
      coll_name: collection.name,
      db_name: database.name,
      session: session,
      batch_size: batch_size,
      to_return: 0,
      # max_time_ms is not being passed here, I assume intentionally?
    }
    op = Operation::GetMore.new(spec)
    context = Operation::Context.new(
      client: client,
      session: session,
      connection_global_id: result.connection_global_id,
    )
    result = if server.load_balancer?
               # Connection will be checked in when cursor is drained.
               connection = server.pool.check_out(context: context)
               op.execute_with_connection(connection, context: context)
             else
               op.execute(server, context: context)
             end
    Cursor.new(self, result, server, session: session)
  end
end

#projection(document = nil) ⇒ Hash, View

Note:

A value of 0 excludes a field from the doc. A value of 1 includes it. Values must all be 0 or all be 1, with the exception of the _id value. The _id field is included by default. It must be excluded explicitly.

The fields to include or exclude from each doc in the result set.

Examples:

Set the fields to include or exclude.

view.projection(name: 1)

Since:

  • 2.0.0



509
510
511
512
 
# File 'lib/mongo/collection/view/readable.rb', line 509

def projection(document = nil)
  validate_doc!(document) if document
  configure(:projection, document)
end

#read(value = nil) ⇒ Symbol, View

Note:

If none is specified for the query, the read preference of the collection will be used.

The read preference to use for the query.

Since:

  • 2.0.0



525
526
527
528
 
# File 'lib/mongo/collection/view/readable.rb', line 525

def read(value = nil)
  return read_preference if value.nil?
  configure(:read, value)
end

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

Since:

  • 2.0.0



683
684
685
686
687
688
689
 
# File 'lib/mongo/collection/view/readable.rb', line 683

def read_concern
  if options[:session] && options[:session].in_transaction?
    options[:session].send(:txn_read_concern) || collection.client.read_concern
  else
    collection.read_concern
  end
end

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

Since:

  • 2.0.0



692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
 
# File 'lib/mongo/collection/view/readable.rb', line 692

def read_preference
  @read_preference ||= begin
    # Operation read preference is always respected, and has the
    # highest priority. If we are in a transaction, we look at
    # transaction read preference and default to client, ignoring
    # collection read preference. If we are not in transaction we
    # look at collection read preference which defaults to client.
    rp = if options[:read]
      options[:read]
    elsif options[:session] && options[:session].in_transaction?
      options[:session].txn_read_preference || collection.client.read_preference
    else
      collection.read_preference
    end
    Lint.validate_underscore_read_preference(rp)
    rp
  end
end

#return_key(value = nil) ⇒ true, ...

Set whether to return only the indexed field or fields.

Examples:

Set the return key value.

view.return_key(true)

Since:

  • 2.1.0



540
541
542
 
# File 'lib/mongo/collection/view/readable.rb', line 540

def return_key(value = nil)
  configure(:return_key, value)
end

#show_disk_loc(value = nil) ⇒ true, ... Also known as: show_record_id

Set whether the disk location should be shown for each document.

Examples:

Set show disk location option.

view.show_disk_loc(true)

Since:

  • 2.0.0



555
556
557
 
# File 'lib/mongo/collection/view/readable.rb', line 555

def show_disk_loc(value = nil)
  configure(:show_disk_loc, value)
end

#skip(number = nil) ⇒ Integer, View

The number of docs to skip before returning results.

Examples:

Set the number to skip.

view.skip(10)

Since:

  • 2.0.0



571
572
573
 
# File 'lib/mongo/collection/view/readable.rb', line 571

def skip(number = nil)
  configure(:skip, number)
end

#snapshot(value = nil) ⇒ Object

Deprecated.

This option is deprecated as of MongoDB server version 4.0.

Note:

When set to true, prevents documents from returning more than once.

Set the snapshot value for the view.

Examples:

Set the snapshot value.

view.snapshot(true)

Since:

  • 2.0.0



589
590
591
 
# File 'lib/mongo/collection/view/readable.rb', line 589

def snapshot(value = nil)
  configure(:snapshot, value)
end

#sort(spec = nil) ⇒ Hash, View

The key and direction pairs by which the result set will be sorted.

Examples:

Set the sort criteria

view.sort(name: -1)

Since:

  • 2.0.0



604
605
606
 
# File 'lib/mongo/collection/view/readable.rb', line 604

def sort(spec = nil)
  configure(:sort, spec)
end

#timeout_ms(timeout_ms = nil) ⇒ Integer, View

The per-operation timeout in milliseconds. Must a positive integer.

Since:

  • 2.0.0



678
679
680
 
# File 'lib/mongo/collection/view/readable.rb', line 678

def timeout_ms(timeout_ms = nil)
  configure(:timeout_ms, timeout_ms)
end