Class: Cuprum::Collections::Basic::Commands::FindMatching

Inherits:
Cuprum::Collections::Basic::Command show all
Includes:
Commands::AbstractFindMatching
Defined in:
lib/cuprum/collections/basic/commands/find_matching.rb

Overview

Command for querying filtered, ordered data from a basic collection.

Instance Attribute Summary

Attributes inherited from Cuprum::Collections::Basic::Command

#collection_name, #data, #default_contract, #member_name, #options, #primary_key_name, #primary_key_type

Instance Method Summary collapse

Methods inherited from Cuprum::Collections::Basic::Command

#initialize, subclass

Constructor Details

This class inherits a constructor from Cuprum::Collections::Basic::Command

Instance Method Details

#call(limit: nil, offset: nil, order: nil, &block) ⇒ Cuprum::Result<Enumerator> #call(limit: nil, offset: nil, order: nil, &block) ⇒ Cuprum::Result<Hash{String, Array<Hash{String, Object}>}>

Queries the collection for items matching the given conditions.

Examples:

Querying all items in the collection.

command = FindMatching.new(collection_name: 'books', data: books)
command.call
#=> an enumerable iterating all items in the collection

Querying all items matching some critera:

command.call { { author: 'Nnedi Okorafor' } }
#=> an enumerable iterating all items in the collection whose author
    is 'Nnedi Okorafor'

Ordering query results

command.call(order: :title) { { author: 'Nnedi Okorafor' } }
#=> an enumerable iterating all items in the collection whose author
#   is 'Nnedi Okorafor', sorted by :title in ascending order

Advanced filtering

command.call do
  {
    category: eq('Science Fiction and Fantasy'),
    author:   ne('J.R.R. Tolkien')
  }
end
#=> an enumerable iterating all items in the collection whose category
#   is 'Science Fiction and Fantasy', and whose author is not
#   'J.R.R. Tolkien'.

Advanced ordering

order = { author: :asc, genre: :desc }
command.call(order: order) { { author: 'Nnedi Okorafor' } }
#=> an enumerable iterating all items in the collection whose author
#   is 'Nnedi Okorafor', sorted first by :author in ascending order
#   and within the same author by genre in descending order

Filtering, ordering, and subsets

command.call(offset: 50, limit: 10, order: :author) do
  { category: 'Science Fiction and Fantasy' }
end
#=> an enumerable iterating the 51st through 60th items in the
#   collection whose category is 'Science Fiction and Fantasy', sorted
#   by :author in ascending order.

Wrapping the result in an envelope

command =
  FindMatching.new(
    collection_name: 'books',
    data:            books
  )
command.call(envelope: true)
#=> {
  'books' => [] # an array containing the matching items
}

Overloads:

  • #call(limit: nil, offset: nil, order: nil, &block) ⇒ Cuprum::Result<Enumerator>

    When the :envelope option is false (default), the command returns an Enumerator which can be iterated to return the matching items.

    Returns:

    • (Cuprum::Result<Enumerator>) —

      the matching items in the specified order as an Enumerator.

  • #call(limit: nil, offset: nil, order: nil, &block) ⇒ Cuprum::Result<Hash{String, Array<Hash{String, Object}>}>

    When the :envelope option is true, the command immediately evaluates the query and wraps the resulting array in a Hash, using the name of the collection as the key.

    Returns:

    • (Cuprum::Result<Hash{String, Array<Hash{String, Object}>}>) —

      a hash with the collection name as key and the matching items as value.

Parameters:

  • envelope (Boolean) (defaults to: false) —

    If true, wraps the result value in a Hash.

  • limit (Integer) (defaults to: nil) —

    The maximum number of results to return.

  • offset (Integer) (defaults to: nil) —

    The initial ordered items to skip.

  • order (Array<String, Symbol>, Hash<{String, Symbol => Symbol}>) (defaults to: nil) —

    The sort order of the returned items. Should be either an array of attribute names or a hash of attribute names and directions.

  • scope (Cuprum::Collections::Basic::Query, nil) (defaults to: nil) —

    Optional scope for the query. Items must match the scope as well as the :where filters.

  • where (Object) (defaults to: nil) —

    Additional filters for selecting data. The command will only return data matching these filters.

Yields:

  • The given block is passed to a QueryBuilder, which converts the block to query criteria and generates a new query using those criteria.

Yield Returns:

  • (Hash) —

    The filters to apply to the query. The hash keys should be the names of attributes or columns, and the corresponding values should be either the literal value for that attribute or a method call for a valid operation defined for the query.



105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/cuprum/collections/basic/commands/find_matching.rb', line 105

validate_parameters :call do
  keyword :envelope,
    Stannum::Constraints::Boolean.new,
    default: true
  keyword :limit, Integer, optional: true
  keyword :offset, Integer, optional: true
  keyword :order,
    Cuprum::Collections::Constraints::Ordering.new,
    optional: true
  keyword :scope,
    Cuprum::Collections::Basic::Query,
    optional: true
  keyword :where, Object, optional: true
end