Class: Mongo::Collection::View

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable, Explainable, Immutable, Iterable, Readable, Writable
Defined in:
build/ruby-driver-v2.19/lib/mongo/collection/view.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/iterable.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/readable.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/writable.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/immutable.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/map_reduce.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/aggregation.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/explainable.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/change_stream.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/builder/map_reduce.rb,
build/ruby-driver-v2.19/lib/mongo/collection/view/builder/aggregation.rb,
build/ruby-driver-v2.19/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 Iterable

#cursor

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, #projection, #read, #read_concern, #read_preference, #return_key, #show_disk_loc, #skip, #snapshot, #sort

Methods included from Iterable

#close_query, #each

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.

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

Since:

  • 2.0.0



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'build/ruby-driver-v2.19/lib/mongo/collection/view.rb', line 155

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

  filter = BSON::Document.new(filter)
  options = BSON::Document.new(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 'build/ruby-driver-v2.19/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 'build/ruby-driver-v2.19/lib/mongo/collection/view.rb', line 59

def filter
  @filter
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



86
87
88
89
90
91
 
# File 'build/ruby-driver-v2.19/lib/mongo/collection/view.rb', line 86

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



103
104
105
 
# File 'build/ruby-driver-v2.19/lib/mongo/collection/view.rb', line 103

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



181
182
183
184
 
# File 'build/ruby-driver-v2.19/lib/mongo/collection/view.rb', line 181

def inspect
  "#<Mongo::Collection::View:0x#{object_id} namespace='#{collection.namespace}'" +
      " @filter=#{filter.to_s} @options=#{options.to_s}>"
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



194
195
196
 
# File 'build/ruby-driver-v2.19/lib/mongo/collection/view.rb', line 194

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