Class: Mongo::Collection::View

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable, Explainable, Immutable, Iterable, Readable, Writable
Defined in:
lib/mongo/collection/view.rb,
lib/mongo/collection/view/iterable.rb,
lib/mongo/collection/view/readable.rb,
lib/mongo/collection/view/writable.rb,
lib/mongo/collection/view/immutable.rb,
lib/mongo/collection/view/map_reduce.rb,
lib/mongo/collection/view/aggregation.rb,
lib/mongo/collection/view/explainable.rb,
lib/mongo/collection/view/change_stream.rb,
lib/mongo/collection/view/builder/map_reduce.rb,
lib/mongo/collection/view/builder/aggregation.rb,
lib/mongo/collection/view/aggregation/behavior.rb,
lib/mongo/collection/view/change_stream/retryable.rb

Overview

Note:

The View API is semipublic.

Representation of a query and options producing a result set of documents.

A View can be modified using helpers. Helpers can be chained, as each one returns a View if arguments are provided.

The query message is sent to the server when a “terminator” is called. For example, when #each is called on a View, a Cursor object is created, which then sends the query to the server.

A View is not created directly by a user. Rather, View creates a View when a CRUD operation is called and returns it to the user to interact with.

Since:

  • 2.0.0

Defined Under Namespace

Modules: Builder, Explainable, Immutable, Iterable, Readable, Writable Classes: Aggregation, ChangeStream, MapReduce

Constant Summary

Constants included from Writable

Writable::ARRAY_FILTERS

Constants included from Explainable

Explainable::ALL_PLANS_EXECUTION, Explainable::EXECUTION_STATS, Explainable::QUERY_PLANNER

Instance Attribute Summary collapse

Attributes included from Mongo::CursorHost

#cursor, #timeout_mode

Attributes included from Immutable

#options

Instance Method Summary collapse

Methods included from Writable

#delete_many, #delete_one, #find_one_and_delete, #find_one_and_replace, #find_one_and_update, #replace_one, #update_many, #update_one

Methods included from Explainable

#explain

Methods included from Readable

#aggregate, #allow_disk_use, #allow_partial_results, #await_data, #batch_size, #comment, #count, #count_documents, #cursor_type, #distinct, #estimated_document_count, #hint, #limit, #map_reduce, #max_await_time_ms, #max_scan, #max_time_ms, #max_value, #min_value, #modifiers, #no_cursor_timeout, #parallel_scan, #projection, #read, #read_concern, #read_preference, #return_key, #show_disk_loc, #skip, #snapshot, #sort

Methods included from Iterable

#close_query, #each

Methods included from Mongo::CursorHost

#validate_timeout_mode!

Constructor Details

#initialize(collection, filter = {}, options = {}) ⇒ View

Creates a new View.

Examples:

Find all users named Emily.

View.new(collection, {:name => 'Emily'})

Find all users named Emily skipping 5 and returning 10.

View.new(collection, {:name => 'Emily'}, :skip => 5, :limit => 10)

Find all users named Emily using a specific read preference.

View.new(collection, {:name => 'Emily'}, :read => :secondary_preferred)

Parameters:

  • collection (Collection) —

    The Collection to query.

  • filter (Hash) (defaults to: {}) —

    The query filter.

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

    The additional query options.

Options Hash (options):

  • :allow_disk_use (true, false) —

    When set to true, the server can write temporary data to disk while executing the find operation. This option is only available on MongoDB server versions 4.4 and newer.

  • :batch_size (Integer) —

    The number of documents to return in each response from MongoDB.

  • :collation (Hash) —

    The collation to use.

  • :comment (String) —

    Associate a comment with the query.

  • :cursor_type (:tailable, :tailable_await) —

    The type of cursor to use.

  • :explain (Hash) —

    Execute an explain with the provided explain options (known options are :verbose and :verbosity) rather than a find.

  • :hint (Hash) —

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

  • :limit (Integer) —

    Max number of documents to return.

  • :max_scan (Integer) —

    Constrain the query to only scan the specified number of documents. Use to prevent queries from running for too long. Deprecated as of MongoDB server version 4.0.

  • :projection (Hash) —

    The fields to include or exclude in the returned documents.

  • :read (Hash) —

    The read preference to use for the query. If none is provided, the collection’s default read preference is used.

  • :read_concern (Hash) —

    The read concern to use for the query.

  • :show_disk_loc (true | false) —

    Return disk location info as a field in each doc.

  • :skip (Integer) —

    The number of documents to skip.

  • :snapshot (true | false) —

    Prevents returning a document more than once. Deprecated as of MongoDB server version 4.0.

  • :sort (Hash) —

    The key and direction pairs used to sort the results.

  • :timeout_mode (:cursor_lifetime | :iteration) —

    How to interpret :timeout_ms (whether it applies to the lifetime of the cursor, or per iteration).

  • :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


169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/mongo/collection/view.rb', line 169

def initialize(collection, filter = {}, options = {})
  validate_doc!(filter)

  filter = BSON::Document.new(filter)
  options = BSON::Document.new(options)

  @collection = collection
  @operation_timeout_ms = options.delete(:timeout_ms)

  validate_timeout_mode!(options)

  # This is when users pass $query in filter and other modifiers
  # alongside?
  query = filter.delete(:$query)
  # This makes modifiers contain the filter if filter wasn't
  # given via $query but as top-level keys, presumably
  # downstream code ignores non-modifier keys in the modifiers?
  modifiers = filter.merge(options.delete(:modifiers) || {})
  @filter = (query || filter).freeze
  @options = Operation::Find::Builder::Modifiers.map_driver_options(modifiers).merge!(options).freeze
end

Instance Attribute Details

#collection ⇒ Collection (readonly)

Returns The Collection to query.

Returns:

Since:

  • 2.0.0


56
57
58
 
# File 'lib/mongo/collection/view.rb', line 56

def collection
  @collection
end

#filter ⇒ Hash (readonly) Also known as: selector

Returns The query filter.

Returns:

  • (Hash) —

    The query filter.

Since:

  • 2.0.0


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

def filter
  @filter
end

#operation_timeout_ms ⇒ Integer | nil | The timeout_ms value that was passed as an option to the view. (readonly)

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.

Returns Integer | nil | The timeout_ms value that was passed as an option to the view.

Returns:

  • (Integer | nil | The timeout_ms value that was passed as an option to the view.) —

    Integer | nil | The timeout_ms value that was passed as an option to the view.

Since:

  • 2.0.0


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

def operation_timeout_ms
  @operation_timeout_ms
end

Instance Method Details

#==(other) ⇒ true, false Also known as: eql?

Compare two View objects.

Examples:

Compare the view with another object.

view == other

Returns:

  • (true, false) —

    Equal if collection, filter, and options of two View match.

Since:

  • 2.0.0


92
93
94
95
96
97
 
# File 'lib/mongo/collection/view.rb', line 92

def ==(other)
  return false unless other.is_a?(View)
  collection == other.collection &&
      filter == other.filter &&
      options == other.options
end

#hash ⇒ Integer

A hash value for the View composed of the collection namespace, hash of the options and hash of the filter.

Examples:

Get the hash value.

view.hash

Returns:

  • (Integer) —

    A hash value of the View object.

Since:

  • 2.0.0


109
110
111
 
# File 'lib/mongo/collection/view.rb', line 109

def hash
  [ collection.namespace, options.hash, filter.hash ].hash
end

#inspect ⇒ String

Get a human-readable string representation of View.

Examples:

Get the inspection.

view.inspect

Returns:

  • (String) —

    A string representation of a View instance.

Since:

  • 2.0.0


207
208
209
210
 
# File 'lib/mongo/collection/view.rb', line 207

def inspect
  "#<Mongo::Collection::View:0x#{object_id} namespace='#{collection.namespace}'" +
      " @filter=#{filter.to_s} @options=#{options.to_s}>"
end

#operation_timeouts(opts = {}) ⇒ Hash

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.

Returns timeout_ms value set on the operation level (if any), and/or timeout_ms that is set on collection/database/client level (if any).

Returns:

  • (Hash) —

    timeout_ms value set on the operation level (if any), and/or timeout_ms that is set on collection/database/client level (if any).

Since:

  • 2.0.0


228
229
230
231
232
233
234
235
236
 
# File 'lib/mongo/collection/view.rb', line 228

def operation_timeouts(opts = {})
  {}.tap do |result|
    if opts[:timeout_ms] || operation_timeout_ms
      result[:operation_timeout_ms] = opts[:timeout_ms] || operation_timeout_ms
    else
      result[:inherited_timeout_ms] = collection.timeout_ms
    end
  end
end

#timeout_ms ⇒ Integer | nil

The timeout_ms value to use for this operation; either specified as an option to the view, or inherited from the collection.

Returns:

  • (Integer | nil) —

    the timeout_ms for this operation

Since:

  • 2.0.0


195
196
197
 
# File 'lib/mongo/collection/view.rb', line 195

def timeout_ms
  operation_timeout_ms || collection.timeout_ms
end

#write_concern ⇒ Mongo::WriteConcern

Get the write concern on this View.

Examples:

Get the write concern.

view.write_concern

Returns:

Since:

  • 2.0.0


220
221
222
 
# File 'lib/mongo/collection/view.rb', line 220

def write_concern
  WriteConcern.get(options[:write_concern] || options[:write] || collection.write_concern)
end