Module: Mongoid::Criterion::Optional

Included in:
Mongoid::Criteria
Defined in:
lib/mongoid/criterion/optional.rb

Instance Method Summary collapse

Instance Method Details

#ascending(*fields) ⇒ Criteria Also known as: asc

Adds fields to be sorted in ascending order. Will add them in the order they were passed into the method.

Examples:

Sort in ascending order.

criteria.ascending(:title, :dob)
criteria.asc(:title, :dob)

Parameters:

Returns:



16
17
18
19
20
21
 
# File 'lib/mongoid/criterion/optional.rb', line 16

def ascending(*fields)
  clone.tap do |crit|
    crit.options[:sort] = [] unless options[:sort] || fields.first.nil?
    fields.flatten.each { |field| merge_options(crit.options[:sort], [ field, :asc ]) }
  end
end

#cache ⇒ Criteria

Tells the criteria that the cursor that gets returned needs to be cached. This is so multiple iterations don’t hit the database multiple times, however this is not advisable when working with large data sets as the entire results will get stored in memory.

Examples:

Flag the criteria as cached.

criteria.cache

Returns:



33
34
35
 
# File 'lib/mongoid/criterion/optional.rb', line 33

def cache
  clone.tap { |crit| crit.options.merge!(:cache => true) }
end

#cached? ⇒ true, false

Will return true if the cache option has been set.

Examples:

Is the criteria cached?

criteria.cached?

Returns:

  • (true, false) —

    If the criteria is flagged as cached.



43
44
45
 
# File 'lib/mongoid/criterion/optional.rb', line 43

def cached?
  options[:cache] == true
end

#descending(*fields) ⇒ Criteria Also known as: desc

Adds fields to be sorted in descending order. Will add them in the order they were passed into the method.

Examples:

Sort the criteria in descending order.

criteria.descending(:title, :dob)
criteria.desc(:title, :dob)

Parameters:

Returns:



57
58
59
60
61
62
 
# File 'lib/mongoid/criterion/optional.rb', line 57

def descending(*fields)
  clone.tap do |crit|
    crit.options[:sort] = [] unless options[:sort] || fields.first.nil?
    fields.flatten.each { |field| merge_options(crit.options[:sort], [ field, :desc ]) }
  end
end

#extras(extras) ⇒ Criteria

Adds a criterion to the Criteria that specifies additional options to be passed to the Ruby driver, in the exact format for the driver.

Examples:

Add extra params to the criteria.

criteria.extras(:limit => 20, :skip => 40)

Parameters:

  • extras (Hash) —

    The extra driver options.

Returns:



74
75
76
77
78
 
# File 'lib/mongoid/criterion/optional.rb', line 74

def extras(extras)
  clone.tap do |crit|
    crit.options.merge!(extras)
  end
end

#for_ids(*ids) ⇒ Criteria

Adds a criterion to the Criteria that specifies an id that must be matched.

Examples:

Add a single id criteria.

criteria.for_ids("4ab2bc4b8ad548971900005c")

Add multiple id criteria.

criteria.for_ids(["4ab2bc4b8ad548971900005c", "4c454e7ebf4b98032d000001"])

Parameters:

  • ids: (Array) —

    A single id or an array of ids.

Returns:



91
92
93
94
95
96
97
98
 
# File 'lib/mongoid/criterion/optional.rb', line 91

def for_ids(*ids)
  ids.flatten!
  if ids.size > 1
    where(:_id.in => ::BSON::ObjectId.convert(klass, ids))
  else
    where(:_id => ids.first)
  end
end

#limit(value = 20) ⇒ Criteria

Adds a criterion to the Criteria that specifies the maximum number of results to return. This is mostly used in conjunction with skip() to handle paginated results.

Examples:

Limit the result set size.

criteria.limit(100)

Parameters:

  • value (Integer) (defaults to: 20) —

    The max number of results.

Returns:



110
111
112
 
# File 'lib/mongoid/criterion/optional.rb', line 110

def limit(value = 20)
  clone.tap { |crit| crit.options[:limit] = value }
end

#offset(*args) ⇒ Integer

Returns the offset option. If a per_page option is in the list then it will replace it with a skip parameter and return the same value. Defaults to 20 if nothing was provided.

Examples:

Get the offset.

criteria.offset(10)

Returns:

  • (Integer) —

    The number of documents to skip.



122
123
124
 
# File 'lib/mongoid/criterion/optional.rb', line 122

def offset(*args)
  args.size > 0 ? skip(args.first) : options[:skip]
end

#order_by(*args) ⇒ Criteria Also known as: order

Adds a criterion to the Criteria that specifies the sort order of the returned documents in the database. Similar to a SQL “ORDER BY”.

Examples:

Order by specific fields.

criteria.order_by([[:field1, :asc], [:field2, :desc]])

Parameters:

  • params: (Array) —

    An Array of [field, direction] sorting pairs.

Returns:



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/mongoid/criterion/optional.rb', line 135

def order_by(*args)
  clone.tap do |crit|
    arguments = args.size == 1 ? args.first : args
    crit.options[:sort] = [] unless options[:sort] || args.first.nil?
    if arguments.is_a?(Array)
      #[:name, :asc]
      if arguments.size == 2 && (arguments.first.is_a?(Symbol) || arguments.first.is_a?(String))
        build_order_options(arguments, crit)
      else
        arguments.each { |argument| build_order_options(argument, crit) }
      end
    else
      build_order_options(arguments, crit)
    end
  end
end

#skip(value = 0) ⇒ Criteria

Adds a criterion to the Criteria that specifies how many results to skip when returning Documents. This is mostly used in conjunction with limit() to handle paginated results, and is similar to the traditional “offset” parameter.

Examples:

Skip a specified number of documents.

criteria.skip(20)

Parameters:

  • value (Integer) (defaults to: 0) —

    The number of results to skip.

Returns:



164
165
166
 
# File 'lib/mongoid/criterion/optional.rb', line 164

def skip(value = 0)
  clone.tap { |crit| crit.options[:skip] = value }
end

#type(types) ⇒ Criteria

Adds a criterion to the Criteria that specifies a type or an Array of types that must be matched.

Examples:

Match only specific models.

criteria.type('Browser')
criteria.type(['Firefox', 'Browser'])

Parameters:

  • types (Array<String>) —

    The types to match against.

Returns:



178
179
180
181
 
# File 'lib/mongoid/criterion/optional.rb', line 178

def type(types)
  types = [types] unless types.is_a?(Array)
  any_in(:_type => types)
end