Class: Mongo::Collection::View

Relationships & Source Files
Namespace Children
Modules: `Builder`, `Explainable`, `Immutable`, `Iterable`, `Readable`, `Writable`
Classes: `Aggregation`, `ChangeStream`, `MapReduce`
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Forwardable
Instance Chain: self, `Writable`, `Explainable`, `Readable`, `Iterable`, `Immutable`, Enumerable
Inherits:	Object
Defined in:	lib/mongo/collection/view.rb, lib/mongo/collection/view/aggregation.rb, lib/mongo/collection/view/change_stream.rb, lib/mongo/collection/view/explainable.rb, lib/mongo/collection/view/immutable.rb, lib/mongo/collection/view/iterable.rb, lib/mongo/collection/view/map_reduce.rb, lib/mongo/collection/view/readable.rb, lib/mongo/collection/view/writable.rb, lib/mongo/collection/view/builder/aggregation.rb, lib/mongo/collection/view/builder/map_reduce.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 ::Mongo::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

Constant Summary

`Explainable` - Included

ALL_PLANS_EXECUTION, EXECUTION_STATS, QUERY_PLANNER

`Writable` - Included

ARRAY_FILTERS

Class Method Summary

.new(collection, filter = {}, options = {}) ⇒ View constructor

Creates a new View.

Instance Attribute Summary

#collection ⇒ Collection readonly
#filter ⇒ Hash (also: #selector) readonly
#selector readonly

Alias for #filter.

`Explainable` - Included

#explained?

`Iterable` - Included

#cursor	Returns the cursor associated with this view, if any.
#use_query_cache?

`Immutable` - Included

#options

Instance Method Summary

#==(other) ⇒ true, false (also: #eql?)

Compare two View objects.
#eql?(other)

Alias for #==.
#hash ⇒ Integer

A hash value for the View composed of the collection namespace, hash of the options and hash of the filter.
#inspect ⇒ String

Get a human-readable string representation of View.
#write_concern ⇒ Mongo::WriteConcern

Get the write concern on this View.
#initialize_copy(other) private
#new(options) private
#view private
#with_session(opts = {}, &block) private

`Writable` - Included

#delete_many	Remove documents from the collection.
#delete_one	Remove a document from the collection.
#find_one_and_delete	Finds a single document in the database via findAndModify and deletes it, returning the original document.
#find_one_and_replace	Finds a single document and replaces it.
#find_one_and_update	Finds a single document and updates it.
#replace_one	Replaces a single document in the database with the new document.
#update_many	Update documents in the collection.
#update_one	Update a single document in the collection.
#validate_replacement_documents!	Check the replacement documents to make sure they don’t have atomic modifiers.
#validate_update_documents!	Checks the update documents to make sure they only have atomic modifiers.

`Explainable` - Included

#explain	Get the query plan for the query.
#explain_options

`Readable` - Included

#aggregate	Execute an aggregation on the collection view.
#allow_disk_use	Allows the server to write temporary data to disk while executing a find operation.
#allow_partial_results	Allows the query to get partial results if some shards are down.
#await_data	Tell the query’s cursor to stay open and wait for data.
#batch_size	The number of documents returned in each batch of results from MongoDB.
#comment	Associate a comment with the query.
#count	Get a count of matching documents in the collection.
#count_documents	Get a count of matching documents in the collection.
#cursor_type	The type of cursor to use.
#distinct	Get a list of distinct values for a specific field.
#estimated_document_count	Gets an estimate of the count of documents in a collection using collection metadata.
#hint	The index that MongoDB will be forced to use for the query.
#limit	The max number of docs to return from the query.
#map_reduce	Execute a map/reduce operation on the collection view.
#max_await_time_ms	A cumulative time limit in milliseconds for processing get more operations on a cursor.
#max_scan	Set the max number of documents to scan.
#max_time_ms	A cumulative time limit in milliseconds for processing operations on a cursor.
#max_value	Set the maximum value to search.
#min_value	Set the minimum value to search.
#modifiers	If called without arguments or with a nil argument, returns the legacy (OP_QUERY) server modifiers for the current view.
#no_cursor_timeout	The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use.
#projection	The fields to include or exclude from each doc in the result set.
#read	The read preference to use for the query.
#read_concern, #read_preference,
#return_key	Set whether to return only the indexed field or fields.
#show_disk_loc	Set whether the disk location should be shown for each document.
#show_record_id	Alias for Readable#show_disk_loc.
#skip	The number of docs to skip before returning results.
#snapshot	Set the snapshot value for the view.
#sort	The key and direction pairs by which the result set will be sorted.
#collation, #parallel_scan, #server_selector, #validate_doc!

`Iterable` - Included

#close_query	Cleans up resources associated with this query.
#each	Iterate through documents returned by a query with this `View`.
#kill_cursors	Alias for Iterable#close_query.
#cache_options, #cached_cursor, #initial_query_op,
#maybe_set_tailable_options	Add tailable cusror options to the command specifiction if needed.
#select_cursor, #send_initial_query

`Immutable` - Included

#configure

Constructor Details

.new(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.

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/collection/view.rb', line 156


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:

(Collection) —

The Collection to query.

Since:

2.0.0

[ GitHub ]

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


attr_reader :collection

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

Returns:

(Hash) —

The query filter.

Since:

2.0.0

[ GitHub ]

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


attr_reader :filter

#selector (readonly)

Alias for #filter.

[ GitHub ]

# File 'lib/mongo/collection/view.rb', line 75


alias :selector :filter

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

[ GitHub ]

# File '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

#eql?(other)

Alias for #==.

[ GitHub ]

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


alias_method :eql?, :==

#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

[ GitHub ]

# File 'lib/mongo/collection/view.rb', line 103


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

#initialize_copy(other) (private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/collection/view.rb', line 201


def initialize_copy(other)
  @collection = other.collection
  @options = other.options.dup
  @filter = other.filter.dup
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

[ GitHub ]

# File 'lib/mongo/collection/view.rb', line 182


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

#new(options) (private)

Since:

2.0.0

[ GitHub ]

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


def new(options)
  View.new(collection, filter, options)
end

#view (private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/collection/view.rb', line 211


def view; self; end

#with_session(opts = {}, &block) (private)

Since:

2.0.0

[ GitHub ]

# File 'lib/mongo/collection/view.rb', line 213


def with_session(opts = {}, &block)
  client.send(:with_session, @options.merge(opts), &block)
end

#write_concern ⇒ Mongo::WriteConcern

Get the write concern on this View.

Examples:

Get the write concern.

view.write_concern

Returns:

(Mongo::WriteConcern) —

The write concern.

Since:

2.0.0

[ GitHub ]

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


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

Class: Mongo::Collection::View

Overview

Constant Summary

Explainable - Included

Writable - Included

Class Method Summary

Instance Attribute Summary

Explainable - Included

Iterable - Included

Immutable - Included

Instance Method Summary

Writable - Included

Explainable - Included

Readable - Included

Iterable - Included

Immutable - Included

Constructor Details

.new(collection, filter = {}, options = {}) ⇒ View

Instance Attribute Details

#collection ⇒ Collection (readonly)

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

#selector (readonly)

Instance Method Details

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

#eql?(other)

#hash ⇒ Integer

#initialize_copy(other) (private)

#inspect ⇒ String

#new(options) (private)

#view (private)

#with_session(opts = {}, &block) (private)

#write_concern ⇒ Mongo::WriteConcern

`Explainable` - Included

`Writable` - Included

`Explainable` - Included

`Iterable` - Included

`Immutable` - Included

`Writable` - Included

`Explainable` - Included

`Readable` - Included

`Iterable` - Included

`Immutable` - Included

.new(collection, filter = {}, options = {}) ⇒ `View`

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

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

#hash ⇒ `Integer`

#inspect ⇒ `String`