Class: Cuprum::Collections::Query

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/cuprum/collections/query.rb

Overview

Abstract base class for collection Query implementations.

Direct Known Subclasses

Basic::Query

Instance Method Summary collapse

Constructor Details

#initialize(scope: nil) ⇒ Query

Returns a new instance of Query.

Parameters:



17
18
19
20
21
22
 
# File 'lib/cuprum/collections/query.rb', line 17

def initialize(scope: nil)
  @limit  = nil
  @offset = nil
  @order  = {}
  @scope  = scope ? default_scope.and(scope) : default_scope
end

Instance Method Details

#limit ⇒ Integer? #limit(count) ⇒ Query

Sets or returns the maximum number of items returned by the query.

Overloads:

  • #limit ⇒ Integer?

    Returns the current limit for the query.

    Returns:

    • (Integer, nil) —

      the current limit for the query.

  • #limit(count) ⇒ Query

    Returns a copy of the query with the specified limit.

    The query will return at most the specified number of items.

    When #limit is called on a query that already defines a limit, the old limit is replaced with the new.

    Parameters:

    • count (Integer) —

      the maximum number of items to return.

    Returns:

    • (Query) —

      the copy of the query.



53
54
55
56
57
58
59
 
# File 'lib/cuprum/collections/query.rb', line 53

def limit(count = UNDEFINED)
  return @limit if count == UNDEFINED

  validate_limit(count)

  dup.tap { |copy| copy.with_limit(count) }
end

#offset ⇒ Integer? #offset(count) ⇒ Query

Sets or returns the number of ordered items skipped by the query.

Overloads:

  • #offset ⇒ Integer?

    Returns the current offset for the query.

    Returns:

    • (Integer, nil) —

      the current offset for the query.

  • #offset(count) ⇒ Query

    Returns a copy of the query with the specified offset.

    The query will skip the specified number of matching items, and return only matching items after the given offset. If the total number of matching items is less than or equal to the offset, the query will not return any items.

    When #offset is called on a query that already defines an offset, the old offset is replaced with the new.

    Parameters:

    • count (Integer) —

      the number of items to skip.

    Returns:

    • (Query) —

      the copy of the query.



80
81
82
83
84
85
86
 
# File 'lib/cuprum/collections/query.rb', line 80

def offset(count = UNDEFINED)
  return @offset if count == UNDEFINED

  validate_offset(count)

  dup.tap { |copy| copy.with_offset(count) }
end

#order ⇒ Hash{String,Symbol=>Symbol} #order(*attributes) ⇒ Query #order(attributes) ⇒ Query Also known as: order_by

Returns a copy of the query with the specified order.

The query will find the matching items, sort them in the specified order, and then apply limit and/or offset (if applicable) to determine the final returned items.

When #order is called on a query that already defines an ordering, the old ordering is replaced with the new.

Examples:

Sorting By Attribute Names

# This query will sort books by author (ascending), then by title
# (ascending) within authors.
query = query.order(:author, :title)

Sorting With Directions

# This query will sort books by series (ascending), then by the date of
# publication (descending) within series.
query = query.order({ series: :asc, published_at: :desc })

Overloads:

  • #order ⇒ Hash{String,Symbol=>Symbol}

    Returns the current ordering for the query.

    Returns:

    • (Hash{String,Symbol=>Symbol}) —

      the current ordering for the query.

  • #order(*attributes) ⇒ Query

    Orders the results by the given attributes, ascending, and in the specified order, i.e. items with the same value of the first attribute will be sorted by the second (if any), and so on.

    Parameters:

    • attributes (Array<String, Symbol>) —

      The attributes to order by.

  • #order(attributes) ⇒ Query

    Orders the results by the given attributes and sort directions, and in the specified order.

    Parameters:

    • attributes (Hash{String,Symbol=>Symbol}) —

      The attributes to order by. The hash keys should be the names of attributes or columns, and the corresponding values should be the sort direction for that attribute, either :asc or :desc.

Returns:

  • (Query) —

    the copy of the query.



128
129
130
131
132
133
134
 
# File 'lib/cuprum/collections/query.rb', line 128

def order(*attributes)
  return @order if attributes.empty?

  normalized = Cuprum::Collections::Queries::Ordering.normalize(*attributes)

  dup.tap { |copy| copy.with_order(normalized) }
end

#reset ⇒ Cuprum::Collections::Query

Returns a copy of the query with no cached query results.

Once the query has been called (e.g. by calling #each or #to_a), the matching data is cached. If the underlying collection changes, those changes will not be reflected in the query.

Calling #reset clears the cached results. The next time the query is called, the results will be drawn from the current collection state.

Returns:



148
149
150
 
# File 'lib/cuprum/collections/query.rb', line 148

def reset
  dup.reset!
end

#scope ⇒ Cuprum::Collections::Scopes::Base

Returns the current scope for the query.

Composition methods should not be called on the scope directly, as they will not change the scope object bound to the query. Call the corresponding methods on the query itself, i.e. call query.where() instead of query.scope.where().

Returns:



33
34
35
 
# File 'lib/cuprum/collections/query.rb', line 33

def scope
  @scope ||= default_scope
end

#where(hash) ⇒ Object #where(&block) ⇒ Object

Overloads:

  • #where(hash) ⇒ Object

    Returns a copy of the query with the specified filters.

    If the query already has a scope, then the filters will be merged with the existing scope. Any items in the collection must match both the previous scope and the new criteria to be returned by the query.

    Examples:

    Filtering Data By Equality

    # The query will only return items whose author is 'J.R.R. Tolkien'.
query = query.where { { author: 'J.R.R. Tolkien' } }

    Parameters:

    • hash (Hash{String=>Object}) —

      the filters to apply to the query.

    See Also:

  • #where(&block) ⇒ Object

    Returns a copy of the query with the specified filters.

    If the query already has a scope, then the filters will be merged with the existing scope. Any items in the collection must match both the previous scope and the new criteria to be returned by the query.

    Yield Returns:

    • (Hash{String=>Object}) —

      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.



179
180
181
 
# File 'lib/cuprum/collections/query.rb', line 179

def where(...)
  dup.with_scope(scope.where(...)).reset!
end