module Mongo::Collection::View::Iterable

Defines iteration related behavior for collection views, including cursor instantiation.

@since 2.0.0

Public Instance Methods

close_query() click to toggle source

Cleans up resources associated with this query.

If there is a server cursor associated with this query, it is closed by sending a KillCursors command to the server.

@note This method propagates any errors that occur when closing the

server-side cursor.

@return [ nil ] Always nil.

@raise [ Error::OperationFailure ] If the server cursor close fails.

@since 2.1.0

# File lib/mongo/collection/view/iterable.rb, line 86
def close_query
  if @cursor
    @cursor.close
  end
end
Also aliased as: kill_cursors
each() { |doc| ... } click to toggle source

Iterate through documents returned by a query with this View.

@example Iterate through the result of the view.

view.each do |document|
  p document
end

@return [ Enumerator ] The enumerator.

@since 2.0.0

@yieldparam [ Hash ] Each matching document.

# File lib/mongo/collection/view/iterable.rb, line 37
def each
  @cursor = if use_query_cache? && cached_cursor
    cached_cursor
  else
    session = client.send(:get_session, @options)
    select_cursor(session)
  end

  if use_query_cache?
    # No need to store the cursor in the query cache if there is
    # already a cached cursor stored at this key.
    QueryCache.set(@cursor, **cache_options) unless cached_cursor

    # If a query with a limit is performed, the query cache will
    # re-use results from an earlier query with the same or larger
    # limit, and then impose the lower limit during iteration.
    limit_for_cached_query = respond_to?(:limit) ? limit : nil
  end

  if block_given?
    # Ruby versions 2.5 and older do not support arr[0..nil] syntax, so
    # this must be a separate conditional.
    cursor_to_iterate = if limit_for_cached_query
      @cursor.to_a[0...limit_for_cached_query]
    else
      @cursor
    end

    cursor_to_iterate.each do |doc|
      yield doc
    end
  else
    @cursor.to_enum
  end
end
kill_cursors()
Alias for: close_query

Private Instance Methods

cache_options() click to toggle source
# File lib/mongo/collection/view/iterable.rb, line 118
def cache_options
  # NB: this hash is passed as keyword argument and must have symbol
  # keys.
  {
    namespace: collection.namespace,
    selector: selector,
    skip: skip,
    sort: sort,
    limit: limit,
    projection: projection,
    collation: collation,
    read_concern: read_concern,
    read_preference: read_preference

  }
end
cached_cursor() click to toggle source
# File lib/mongo/collection/view/iterable.rb, line 114
def cached_cursor
  QueryCache.get(**cache_options)
end
initial_command_op(session) click to toggle source
# File lib/mongo/collection/view/iterable.rb, line 149
def initial_command_op(session)
  builder = Builder::FindCommand.new(self, session)
  if explained?
    Operation::Explain.new(builder.explain_specification)
  else
    Operation::Find.new(builder.specification)
  end
end
initial_query_op(server, session) click to toggle source
# File lib/mongo/collection/view/iterable.rb, line 135
def initial_query_op(server, session)
  if server.with_connection { |connection| connection.features }.find_command_enabled?
    initial_command_op(session)
  else
    # Server versions that do not have the find command feature
    # (versions older than 3.2) do not support the allow_disk_use option
    # but perform no validation and will not raise an error if it is
    # specified. If the allow_disk_use option is specified, raise an error
    # to alert the user.
    raise Error::UnsupportedOption.allow_disk_use_error if options.key?(:allow_disk_use)
    Operation::Find.new(Builder::OpQuery.new(self).specification)
  end
end
select_cursor(session) click to toggle source
# File lib/mongo/collection/view/iterable.rb, line 95
def select_cursor(session)
  if respond_to?(:write?, true) && write?
    server = server_selector.select_server(cluster, nil, session)
    result = send_initial_query(server, session)

    # RUBY-2367: This will be updated to allow the query cache to
    # cache cursors with multi-batch results.
    if use_query_cache?
      CachingCursor.new(view, result, server, session: session)
    else
      Cursor.new(view, result, server, session: session)
    end
  else
    read_with_retry_cursor(session, server_selector, view) do |server|
      send_initial_query(server, session)
    end
  end
end
send_initial_query(server, session = nil) click to toggle source
# File lib/mongo/collection/view/iterable.rb, line 158
def send_initial_query(server, session = nil)
  validate_collation!(server, collation)
  initial_query_op(server, session).execute(server, client: client)
end
use_query_cache?() click to toggle source
# File lib/mongo/collection/view/iterable.rb, line 163
def use_query_cache?
  QueryCache.enabled? && !collection.system_collection?
end