Class DataMapper::Query
In: lib/dm-core/query/direction.rb
lib/dm-core/query/conditions/comparison.rb
lib/dm-core/query/conditions/operation.rb
lib/dm-core/query/path.rb
lib/dm-core/query/sort.rb
lib/dm-core/query/operator.rb
lib/dm-core/query.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

Included Modules

DataMapper::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, nil]

  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

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

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

@param [Repository] repository

  the default repository to scope the query within

@param [Model] model

  the default model for the query

@param [query, Enumerable] source

  the source to generate the query with

@return [Query]

  the query to match the resources with

@api private

Public Instance methods

&(other)

Alias for intersection

+(other)

Alias for union

-(other)

Alias for difference

[](*args)

Alias for slice

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

Clear conditions

@return [self]

@api semipublic

Get the properties used in the conditions

@return [Set<Property>]

 Set of properties used in the conditions

@api private

Return the difference with another query

@param [Query] other

  the other query

@return [Query]

  the difference of the query and other

@api semipublic

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

Returns detailed human readable string representation of the query

@return [String] detailed string representation of the query

@api semipublic

Return the intersection with another query

@param [Query] other

  the other query

@return [Query]

  the intersection of the query and other

@api semipublic

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

@param [Enumerable] records

  A list of records to sort

@return [Enumerable]

  The offset & limited records

@api semipublic

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

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

Indicates if the Query has raw conditions

@return [Boolean]

  true if the query has raw conditions, false if not

@api semipublic

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

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

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

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

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

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

Sorts a list of Records by the order

@param [Enumerable] records

  A list of Resources to sort

@return [Enumerable]

  The sorted records

@api semipublic

Return a list of fields in predictable order

@return [Array<Property>]

  list of fields sorted in deterministic order

@api private

Hash representation of a Query

@return [Hash]

  Hash representation of a Query

@api private

Extract options from a Query

@param [Query] query

  the query to extract options from

@return [Hash]

  the options to use to initialize the new query

@api private

Transform Query into subquery conditions

@return [AndOperation]

  a subquery for the Query

@api private

Return the union with another query

@param [Query] other

  the other query

@return [Query]

  the union of the query and other

@api semipublic

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

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

Indicates if the Query is valid

@return [Boolean]

  true if the query is valid

@api semipublic

|(other)

Alias for union

[Validate]