Class: Cuprum::Collections::Query

Inherits:
Object
  • Object
show all
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 ⇒ Query

Returns a new instance of Query.



12
13
14
 
# File 'lib/cuprum/collections/query.rb', line 12

def initialize
  @criteria = []
end

Instance Method Details

#criteria ⇒ Array<Array>

Returns a normalized representation of the query criteria.

The query criteria define which data from the collection matches the query. Specifically, an item in the collection matches the query if and only if it matches each criterion. If the query has no criteria, then it will match all items in the collection.

Each criterion is represented as an Array with three elements:

  • The name of the property or column to select by.

  • The operation to filter, such as :eq (an equality operation).

  • The expected value.

For example, a query that selects all items whose :series property is equal to ‘The Lord of the Rings’ would have the following criterion: ‘[:series, :eq, ’The Lord of the Rings’]‘.

Returns:

  • (Array<Array>) —

    the query criteria.

See Also:



35
36
37
 
# File 'lib/cuprum/collections/query.rb', line 35

def criteria
  @criteria.dup
end

#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.



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

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.



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

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.



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

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:



150
151
152
 
# File 'lib/cuprum/collections/query.rb', line 150

def reset
  dup.reset!
end

#where { ... } ⇒ Object

Returns a copy of the query with the specified filters.

The given parameters are used to construct query criteria, which define which data from the collection matches the query. Specifically, an item in the collection matches the query if and only if it matches each criterion. If the query has no criteria, then it will match all items in the collection.

When #where is called on a query that already defines criteria, then the new criteria are appended to the old. Any items in the collection must match both the old 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' } }

Filtering Data By Operator

# The query will only return items whose author is 'J.R.R. Tolkien',
# and whose series is not 'The Lord of the Rings'.
query = query.where do
  {
    author: eq('J.R.R. Tolkien'),
    series: ne('The Lord of the Rings')
  }
end

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.

See Also:



191
192
193
194
195
196
197
 
# File 'lib/cuprum/collections/query.rb', line 191

def where(filter = nil, strategy: nil, &block)
  filter ||= block

  return dup if filter.nil? && strategy.nil?

  query_builder.call(strategy: strategy, where: filter)
end