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

Included in:
Mongo::Collection::View
Defined in:
build/ruby-driver-master/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" }}}
])

Parameters:

  • pipeline (Array<Hash>)

    The aggregation pipeline.

  • options (Hash) (defaults to: {})

    The aggregation options.

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.

  • :use_cursor (true, false)

    Indicates whether the command will request that the server provide results using a cursor. Note that as of server version 3.6, aggregations always provide results using a cursor and this option is therefore not valid.

  • :session (Session)

    The session to use.

Returns:

Since:

  • 2.0.0



60
61
62
63
64
65
66
67
68
69
70
71
72
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 60

def aggregate(pipeline, 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_useView

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

Returns:

  • (View)

    The new view.

Since:

  • 2.0.0



78
79
80
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 78

def allow_disk_use
  configure(:allow_disk_use, true)
end

#allow_partial_resultsView

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

Examples:

Allow partial results.

view.allow_partial_results

Returns:

  • (View)

    The new view.

Since:

  • 2.0.0



90
91
92
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 90

def allow_partial_results
  configure(:allow_partial_results, true)
end

#await_dataView

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

Examples:

Await data on the cursor.

view.await_data

Returns:

  • (View)

    The new view.

Since:

  • 2.0.0



102
103
104
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 102

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)

Parameters:

  • batch_size (Integer) (defaults to: nil)

    The size of each batch of results.

Returns:

  • (Integer, View)

    Either the batch_size value or a new View.

Since:

  • 2.0.0



119
120
121
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 119

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')

Parameters:

  • comment (Object) (defaults to: nil)

    The comment to be associated with the query.

Returns:

  • (String, View)

    Either the comment or a new View.

Since:

  • 2.0.0



137
138
139
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 137

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

Parameters:

  • opts (Hash) (defaults to: {})

    Options for the operation.

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.

Returns:

  • (Integer)

    The document count.

Since:

  • 2.0.0



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 169

def count(opts = {})
  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|
    read_with_retry(session, selector) do |server|
      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],
      ).execute(server, context: Operation::Context.new(client: client, session: session))
    end.n.to_i
  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

Parameters:

  • opts (Hash) (defaults to: {})

    Options for the operation.

  • ops (Hash)

    a customizable set of options

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.

  • :read (Hash)

    The read preference options.

  • :collation (Hash)

    The collation to use.

  • :session (Mongo::Session)

    The session to use for the operation.

Returns:

  • (Integer)

    The document count.

Since:

  • 2.6.0



221
222
223
224
225
226
227
228
229
230
231
232
233
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 221

def count_documents(opts = {})
  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.select { |k, _| [:hint, :max_time_ms, :read, :collation, :session].include?(k) }
  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)

Parameters:

  • type (:tailable, :tailable_await) (defaults to: nil)

    The cursor type.

Returns:

  • (:tailable, :tailable_await, View)

    Either the cursor type setting or a new View.

Since:

  • 2.3.0



633
634
635
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 633

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')

Parameters:

  • field_name (String, Symbol)

    The name of the field.

  • opts (Hash) (defaults to: {})

    Options for the distinct command.

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.

Returns:

  • (Array<Object>)

    The list of distinct values.

Since:

  • 2.0.0



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 326

def distinct(field_name, opts = {})
  if field_name.nil?
    raise ArgumentError, 'Field name for distinct operation must be not nil'
  end
  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|
    read_with_retry(session, selector) do |server|
      Operation::Distinct.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,
      ).execute(server, context: Operation::Context.new(client: client, session: session))
    end.first['values']
  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

Parameters:

  • opts (Hash) (defaults to: {})

    Options for the operation.

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.

Returns:

  • (Integer)

    The document count.

Since:

  • 2.6.0



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
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
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 251

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)
      raise ArgumentError, "Cannot call estimated_document_count when querying with #{opt}"
    end
  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|
    read_with_retry(session, selector) do |server|
      context = Operation::Context.new(client: client, session: session)
      if server.description.server_version_gte?('5.0')
        pipeline = [
          {'$collStats' => {'count' => {}}},
          {'$group' => {'_id' => 1, 'n' => {'$sum' => '$count'}}},
        ]
        spec = Builder::Aggregation.new(
          pipeline,
          self,
          options.merge(session: session)
        ).specification
        result = Operation::Aggregate.new(spec).execute(server, context: context)
        result.documents.first.fetch('n')
      else
        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
        result = Operation::Count.new(
          selector: cmd,
          db_name: database.name,
          read: read_pref,
          session: session,
          comment: opts[:comment],
        ).execute(server, context: context)
        result.n.to_i
      end
    end
  end
rescue Error::OperationFailure => 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

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

Parameters:

  • hint (Hash) (defaults to: nil)

    The index to use for the query.

Returns:

  • (Hash, View)

    Either the hint or a new View.

Since:

  • 2.0.0



367
368
369
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 367

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)

Parameters:

  • limit (Integer) (defaults to: nil)

    The number of docs to return.

Returns:

  • (Integer, View)

    Either the limit or a new View.

Since:

  • 2.0.0



381
382
383
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 381

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)

Parameters:

  • map (String)

    The map js function.

  • reduce (String)

    The reduce js function.

  • options (Hash) (defaults to: {})

    The map/reduce options.

Returns:

Since:

  • 2.0.0



397
398
399
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 397

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)

Parameters:

  • max (Integer) (defaults to: nil)

    The max time in milliseconds.

Returns:

  • (Integer, View)

    Either the max await time ms value or a new View.

Since:

  • 2.1.0



605
606
607
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 605

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)

Parameters:

  • value (Integer) (defaults to: nil)

    The max number to scan.

Returns:

  • (Integer, View)

    The value or a new View.

Since:

  • 2.0.0



414
415
416
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 414

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)

Parameters:

  • max (Integer) (defaults to: nil)

    The max time in milliseconds.

Returns:

  • (Integer, View)

    Either the max time ms value or a new View.

Since:

  • 2.1.0



619
620
621
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 619

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)

Parameters:

  • value (Hash) (defaults to: nil)

    The max field and value.

Returns:

  • (Hash, View)

    The value or a new View.

Since:

  • 2.1.0



428
429
430
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 428

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)

Parameters:

  • value (Hash) (defaults to: nil)

    The min field and value.

Returns:

  • (Hash, View)

    The value or a new View.

Since:

  • 2.1.0



442
443
444
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 442

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)

Parameters:

  • doc (Hash) (defaults to: nil)

    The modifiers document.

Returns:

  • (Hash, View)

    Either the modifiers document or a new View.

Since:

  • 2.1.0



586
587
588
589
590
591
592
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 586

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_timeoutView

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

Returns:

  • (View)

    The new view.

Since:

  • 2.0.0



455
456
457
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 455

def no_cursor_timeout
  configure(:no_cursor_timeout, true)
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)

Parameters:

  • document (Hash) (defaults to: nil)

    The field and 1 or 0, to include or exclude it.

Returns:

  • (Hash, View)

    Either the fields or a new View.

Since:

  • 2.0.0



473
474
475
476
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 473

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.

Parameters:

  • value (Hash) (defaults to: nil)

    The read preference mode to use for the query.

Returns:

  • (Symbol, View)

    Either the read preference or a new View.

Since:

  • 2.0.0



489
490
491
492
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 489

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

#read_concernObject

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



638
639
640
641
642
643
644
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 638

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_preferenceObject

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



647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 647

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)

Parameters:

  • value (true, false) (defaults to: nil)

    The return key value.

Returns:

  • (true, false, View)

    The value or a new View.

Since:

  • 2.1.0



504
505
506
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 504

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)

Parameters:

  • value (true, false) (defaults to: nil)

    The value for the field.

Returns:

  • (true, false, View)

    Either the value or a new View.

Since:

  • 2.0.0



519
520
521
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 519

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)

Parameters:

  • number (Integer) (defaults to: nil)

    Number of docs to skip.

Returns:

  • (Integer, View)

    Either the skip value or a new View.

Since:

  • 2.0.0



535
536
537
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 535

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)

Parameters:

  • value (true, false) (defaults to: nil)

    The snapshot value.

Since:

  • 2.0.0



553
554
555
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 553

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)

Parameters:

  • spec (Hash) (defaults to: nil)

    The attributes and directions to sort by.

Returns:

  • (Hash, View)

    Either the sort setting or a new View.

Since:

  • 2.0.0



568
569
570
# File 'build/ruby-driver-master/lib/mongo/collection/view/readable.rb', line 568

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