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
99
100
101
102
103
 
# File 'lib/mongoid/criterion/optional.rb', line 91

def for_ids(*ids)
  ids.flatten!
  if ids.size > 1
    any_in(
      :_id => ::BSON::ObjectId.convert(klass, ids)
    )
  else
    clone.tap do |crit|
      crit.selector[:_id] =
        ::BSON::ObjectId.convert(klass, ids.first)
    end
  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:



115
116
117
 
# File 'lib/mongoid/criterion/optional.rb', line 115

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.



127
128
129
 
# File 'lib/mongoid/criterion/optional.rb', line 127

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:



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/mongoid/criterion/optional.rb', line 140

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:



169
170
171
 
# File 'lib/mongoid/criterion/optional.rb', line 169

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:



183
184
185
186
 
# File 'lib/mongoid/criterion/optional.rb', line 183

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