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

Constant Summary collapse

QUERY =

The query modifier constant.

Since:

  • 2.2.0

'$query'.freeze
MODIFIERS =

The modifiers option constant.

Since:

  • 2.2.0

'modifiers'.freeze

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.

Returns:

Since:

  • 2.0.0



47
48
49
 
# File 'lib/mongo/collection/view/readable.rb', line 47

def aggregate(pipeline, options = {})
  Aggregation.new(self, pipeline, options)
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

Returns:

  • (View) —

    The new view.

Since:

  • 2.0.0



59
60
61
 
# File 'lib/mongo/collection/view/readable.rb', line 59

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

Returns:

  • (View) —

    The new view.

Since:

  • 2.0.0



71
72
73
 
# File 'lib/mongo/collection/view/readable.rb', line 71

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.

new View.

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

Since:

  • 2.0.0



88
89
90
 
# File 'lib/mongo/collection/view/readable.rb', line 88

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 (String) (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



106
107
108
 
# File 'lib/mongo/collection/view/readable.rb', line 106

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.

Returns:

  • (Integer) —

    The document count.

Since:

  • 2.0.0



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/mongo/collection/view/readable.rb', line 136

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|
      apply_collation!(cmd, server, opts)
      Operation::Count.new(
                             :selector => cmd,
                             :db_name => database.name,
                             :options => {:limit => -1},
                             :read => read_pref,
                             :session => session
      ).execute(server, client: client)
    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.

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.

Returns:

  • (Integer) —

    The document count.

Since:

  • 2.6.0



182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/mongo/collection/view/readable.rb', line 182

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



544
545
546
 
# File 'lib/mongo/collection/view/readable.rb', line 544

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



246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/mongo/collection/view/readable.rb', line 246

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|
      apply_collation!(cmd, server, opts)
      Operation::Distinct.new({
                                :selector => cmd,
                                :db_name => database.name,
                                :options => {:limit => -1},
                                :read => read_pref,
                                :session => session
                               }).execute(server, client: client)
    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.

Returns:

  • (Integer) —

    The document count.

Since:

  • 2.6.0



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/mongo/collection/view/readable.rb', line 208

def estimated_document_count(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
  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,
        read: read_pref,
        session: session
      ).execute(server, client: client)
    end.n.to_i
  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



285
286
287
 
# File 'lib/mongo/collection/view/readable.rb', line 285

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



299
300
301
 
# File 'lib/mongo/collection/view/readable.rb', line 299

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



315
316
317
 
# File 'lib/mongo/collection/view/readable.rb', line 315

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



516
517
518
 
# File 'lib/mongo/collection/view/readable.rb', line 516

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



332
333
334
 
# File 'lib/mongo/collection/view/readable.rb', line 332

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



530
531
532
 
# File 'lib/mongo/collection/view/readable.rb', line 530

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



346
347
348
 
# File 'lib/mongo/collection/view/readable.rb', line 346

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



360
361
362
 
# File 'lib/mongo/collection/view/readable.rb', line 360

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

#modifiers(doc = nil) ⇒ Hash, View

“meta” operators that let you modify the output or behavior of a query.

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



500
501
502
503
 
# File 'lib/mongo/collection/view/readable.rb', line 500

def modifiers(doc = nil)
  return Builder::Modifiers.map_server_modifiers(options) if doc.nil?
  new(options.merge(Builder::Modifiers.map_driver_options(doc)))
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

Returns:

  • (View) —

    The new view.

Since:

  • 2.0.0



373
374
375
 
# File 'lib/mongo/collection/view/readable.rb', line 373

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



391
392
393
394
 
# File 'lib/mongo/collection/view/readable.rb', line 391

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



407
408
409
410
 
# File 'lib/mongo/collection/view/readable.rb', line 407

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



549
550
551
552
553
554
555
 
# File 'lib/mongo/collection/view/readable.rb', line 549

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



558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
 
# File 'lib/mongo/collection/view/readable.rb', line 558

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



422
423
424
 
# File 'lib/mongo/collection/view/readable.rb', line 422

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



437
438
439
 
# File 'lib/mongo/collection/view/readable.rb', line 437

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



453
454
455
 
# File 'lib/mongo/collection/view/readable.rb', line 453

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



471
472
473
 
# File 'lib/mongo/collection/view/readable.rb', line 471

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



486
487
488
 
# File 'lib/mongo/collection/view/readable.rb', line 486

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