Class: DataMapper::Query

Class | DataMapper::Query
In: | lib/dm-core/query.rb lib/dm-core/query/conditions/comparison.rb lib/dm-core/query/conditions/operation.rb lib/dm-core/query/direction.rb lib/dm-core/query/operator.rb lib/dm-core/query/path.rb lib/dm-core/query/sort.rb
Parent: | Object

Query class represents a query which will be run against the data-store. Generally Query objects can be found inside Collection objects.

### Methods

[] add_reversed? condition_properties filter_records inspect limit_records match_records merge new raw? relative reload? reverse reverse! slice slice! sort_records sorted_fields target_conditions unique? update valid?

### Included Modules

Extlib::Assertions

### Classes and Modules

Module DataMapper::Query::Conditions
Class DataMapper::Query::Direction
Class DataMapper::Query::Operator
Class DataMapper::Query::Path
Class DataMapper::Query::Sort

### Constants

OPTIONS | = | [ :fields, :links, :conditions, :offset, :limit, :order, :unique, :add_reversed, :reload ].to_set.freeze

### Attributes

conditions | [R] | Returns the conditions of the query In the following example: @example
      Team.all(:wins.gt => 30, :conference => 'East')
Conditions are "greater than" operator for "wins" field and exact match operator for "conference". @return [Array]
      the conditions that will be used to scope the results
@api semipublic
fields | [R] | Returns the fields Set in cases like the following: @example
      Document.all(:fields => [:title, :vernacular_title, :abstract])
@return [PropertySet]
      the properties in the Model that will be retrieved
@api semipublic
limit | [R] | Returns the limit query uses Set in cases like the following: @example
      Document.all(:limit => 10)
@return [Integer, NilClass]
      the maximum number of results
@api semipublic
links | [R] | Returns the links (associations) query fetches @return [Array<DataMapper::Associations::Relationship>]
      the relationships that will be used to scope the results
@api private
model | [R] | Returns model (class) that is used to instantiate objects from query result returned by adapter @return [Model]
      the Model to retrieve results from
@api semipublic
offset | [R] | Returns the offset query uses Set in cases like the following: @example
      Document.all(:offset => page.offset)
@return [Integer]
      the offset of the results
@api semipublic
options | [R] | Returns the original options @return [Hash]
      the original options
@api private
order | [R] | Returns the order Set in cases like the following: @example
      Document.all(:order => [:created_at.desc, :length.desc])
query order is a set of two ordering rules, descending on "created_at" field and descending again on "length" field @return [Array]
      the order of results
@api semipublic
repository | [R] | Returns the repository query should be executed in Set in cases like the following: @example
      Document.all(:repository => :medline)
@return [Repository]
      the Repository to retrieve results from
@api semipublic

### Public Class methods

new(repository, model, options = {})

Initializes a Query instance

@example

     JournalIssue.all(:repository => :medline, :created_on.gte => Date.today - 7)

initialized a query with repository defined with name :medline, model JournalIssue and options { :created_on.gte => Date.today - 7 }

@param [Repository] repository

      the Repository to retrieve results from

@param [Model] model

      the Model to retrieve results from

@param [Hash] options

      the conditions and scope

@api semipublic

target_conditions(source, source_key, target_key)

Extract conditions to match a Resource or Collection

@param [Array, Collection, Resource] source

      the source to extract the values from

@param [ProperySet] source_key

      the key to extract the value from the resource

@param [ProperySet] target_key

      the key to match the resource with

@return [AbstractComparison, AbstractOperation]

      the conditions to match the resources with

@api private

### Public Instance methods

[](*args)

Alias for slice

add_reversed?()

Indicates if each result should be returned in reverse order

Set in cases like the following:

@example

      Document.all(:limit => 5).reverse

Note that :add_reversed option may be used in conditions directly, but this is rarely the case

@return [Boolean]

      true if the results should be reversed, false if not

@api private

condition_properties()

Get the properties used in the conditions

@return [Set<Property>]

     Set of properties used in the conditions

@api private

filter_records(records)

Takes an Enumerable of records, and destructively filters it. First finds all matching conditions, then sorts it, then does offset & limit

@param [Enumerable] records

      The set of records to be filtered

@return [Enumerable]

      Whats left of the given array after the filtering

@api semipublic

inspect()

Returns detailed human readable string representation of the query

@return [String] detailed string representation of the query

@api semipublic

limit_records(records)

Limits a set of records by the offset and/or limit

@param [Enumerable] records

      A list of Recrods to sort

@return [Enumerable]

      The offset & limited records

@api semipublic

match_records(records)

Filter a set of records by the conditions

@param [Enumerable] records

      The set of records to be filtered

@return [Enumerable]

      Whats left of the given array after the matching

@api semipublic

merge(other)

Similar to Query#update, but acts on a duplicate.

@param [Query, Hash] other

      other query to merge with

@return [Query]

      updated duplicate of original query

@api semipublic

raw?()

Indicates if the Query has raw conditions

@return [Boolean]

      true if the query has raw conditions, false if not

@api semipublic

relative(options)

Builds and returns new query that merges original with one given, and slices the result with respect to :limit and :offset options

This method is used by Collection to concatenate options from multiple chained calls in cases like the following:

@example

      author.books.all(:year => 2009).all(:published => false)

@api semipublic

reload?()

Indicates if the Query results should replace the results in the Identity Map

      TODO: needs example

@return [Boolean]

      true if the results should be reloaded, false if not

@api semipublic

reverse()

Returns a new Query with a reversed order

@example

      Document.all(:limit => 5).reverse

Will execute a single query with correct order

@return [Query]

      new Query with reversed order

@api semipublic

reverse!()

Reverses the sort order of the Query

@example

      Document.all(:limit => 5).reverse

Will execute a single query with original order and then reverse collection in the Ruby space

@return [Query]

      self

@api semipublic

slice(*args)

Slices collection by adding limit and offset to the query, so a single query is executed

@example

      Journal.all(:limit => 10).slice(3, 5)

will execute query with the following limit and offset (when repository uses DataObjects adapter, and thus queries use SQL):

      LIMIT 5 OFFSET 3

@api semipublic

slice!(*args)

Slices collection by adding limit and offset to the query, so a single query is executed

@example

      Journal.all(:limit => 10).slice!(3, 5)

will execute query with the following limit (when repository uses DataObjects adapter, and thus queries use SQL):

      LIMIT 10

and then takes a slice of collection in the Ruby space

@api semipublic

sort_records(records)

Sorts a list of Records by the order

@param [Enumerable] records

      A list of Resources to sort

@return [Enumerable]

      The sorted records

@api semipublic

sorted_fields()

Return a list of fields in predictable order

@return [Array<Property>]

      list of fields sorted in deterministic order

@api private

unique?()

Indicates if the Query results should be unique

      TODO: needs example

@return [Boolean]

      true if the results should be unique, false if not

@api semipublic

update(other)

Updates the Query with another Query or conditions

Pretty unrealistic example:

@example

      Journal.all(:limit => 2).query.limit                     # => 2
      Journal.all(:limit => 2).query.update(:limit => 3).limit # => 3

@param [Query, Hash] other

      other Query or conditions

@return [Query]

      self

@api semipublic

valid?()

Indicates if the Query is valid

@return [Boolean]

      true if the query is valid

@api semipublic

[Validate]