- E
- F
- I
- L
- M
- S
- T
Constants
| ONE_AS_ONE | = | "1 AS one" |
Instance Public methods
exists?(conditions = :none)Link
Returns true if a record exists in the table that matches theid or conditions given, or false otherwise. The argument can take six forms:
Integer- Finds the record with this primary key.String- Finds the record with a primary key corresponding to this string (such as'5').Array- Finds the record that matches thesewhere-style conditions (such as['name LIKE ?', "%#{query}%"]).Hash- Finds the record that matches thesewhere-style conditions (such as{name: 'David'}).false- Returns alwaysfalse.No args - Returns
falseif the relation is empty,trueotherwise.
For more information about specifying conditions as a hash or array, see the Conditions section in the introduction toActiveRecord::Base.
Note: You can’t pass in a condition as a string (likename = 'Jamie'), since it would be sanitized and then queried against the primary key column, likeid = 'name = \'Jamie\''.
Person.exists?(5)Person.exists?('5')Person.exists?(['name LIKE ?',"%#{query}%"])Person.exists?(id: [1,4,8])Person.exists?(name:'David')Person.exists?(false)Person.exists?Person.where(name:'Spartacus',rating:4).exists?
# File activerecord/lib/active_record/relation/finder_methods.rb, line 357defexists?(conditions =:none)returnfalseif@noneifBase===conditionsraiseArgumentError,<<-MSG.squish You are passing an instance of ActiveRecord::Base to `exists?`. Please pass the id of the object by calling `.id`. MSGendreturnfalseif!conditions||limit_value==0ifeager_loading?relation =apply_join_dependency(eager_loading:false)returnrelation.exists?(conditions)endrelation =construct_relation_for_exists(conditions)returnfalseifrelation.where_clause.contradiction?skip_query_cache_if_necessarydowith_connectiondo|c|c.select_rows(relation.arel,"#{model.name} Exists?").size==1endendend
fifth()Link
Find the fifth record. If no order is defined it will order by primary key.
Person.fifth# returns the fifth object fetched by SELECT * FROM peoplePerson.offset(3).fifth# returns the fifth object from OFFSET 3 (which is OFFSET 7)Person.where(["user_name = :u", {u:user_name }]).fifth
fifth!()Link
Same asfifth but raisesActiveRecord::RecordNotFound if no record is found.
find(*args)Link
Find by id - This can either be a specific id (ID), a list of ids (ID, ID, ID), or an array of ids ([ID, ID, ID]). ‘ID` refers to an “identifier”. For models with a single-column primary key, `ID` will be a single value, and for models with a composite primary key, it will be an array of values. If one or more records cannot be found for the requested ids, thenActiveRecord::RecordNotFound will be raised. If the primary key is an integer, find by id coerces its arguments by usingto_i.
Person.find(1)# returns the object for ID = 1Person.find("1")# returns the object for ID = 1Person.find("31-sarah")# returns the object for ID = 31Person.find(1,2,6)# returns an array for objects with IDs in (1, 2, 6)Person.find([7,17])# returns an array for objects with IDs in (7, 17), or with composite primary key [7, 17]Person.find([1])# returns an array for the object with ID = 1Person.where("administrator = 1").order("created_on DESC").find(1)
Find a record for a composite primary key model¶↑
TravelRoute.primary_key = [:origin,:destination]TravelRoute.find(["Ottawa","London"])# => #<TravelRoute origin: "Ottawa", destination: "London">TravelRoute.find([["Paris","Montreal"]])# => [#<TravelRoute origin: "Paris", destination: "Montreal">]TravelRoute.find(["New York","Las Vegas"], ["New York","Portland"])# => [# #<TravelRoute origin: "New York", destination: "Las Vegas">,# #<TravelRoute origin: "New York", destination: "Portland"># ]TravelRoute.find([["Berlin","London"], ["Barcelona","Lisbon"]])# => [# #<TravelRoute origin: "Berlin", destination: "London">,# #<TravelRoute origin: "Barcelona", destination: "Lisbon"># ]
NOTE: The returned records are in the same order as the ids you provide. If you want the results to be sorted by database, you can useActiveRecord::QueryMethods#where method and provide an explicitActiveRecord::QueryMethods#order option. ButActiveRecord::QueryMethods#where method doesn’t raiseActiveRecord::RecordNotFound.
Find with lock¶↑
Example for find with a lock: Imagine two concurrent transactions: each will readperson.visits == 2, add 1 to it, and save, resulting in two saves ofperson.visits = 3. By locking the row, the second transaction has to wait until the first is finished; we get the expectedperson.visits == 4.
Person.transactiondoperson =Person.lock(true).find(1)person.visits+=1person.save!end
Variations offind¶↑
Person.where(name:'Spartacus',rating:4)# returns a chainable list (which can be empty).Person.find_by(name:'Spartacus',rating:4)# returns the first item or nil.Person.find_or_initialize_by(name:'Spartacus',rating:4)# returns the first item or returns a new instance (requires you call .save to persist against the database).Person.find_or_create_by(name:'Spartacus',rating:4)# returns the first item or creates it and returns it.
Alternatives forfind¶↑
Person.where(name:'Spartacus',rating:4).exists?(conditions =:none)# returns a boolean indicating if any record with the given conditions exist.Person.where(name:'Spartacus',rating:4).select("field1, field2, field3")# returns a chainable list of instances with only the mentioned fields.Person.where(name:'Spartacus',rating:4).ids# returns an Array of ids.Person.where(name:'Spartacus',rating:4).pluck(:field1,:field2)# returns an Array of the required fields.
Edge Cases¶↑
Person.find(37)# raises ActiveRecord::RecordNotFound exception if the record with the given ID does not exist.Person.find([37])# raises ActiveRecord::RecordNotFound exception if the record with the given ID in the input array does not exist.Person.find(nil)# raises ActiveRecord::RecordNotFound exception if the argument is nil.Person.find([])# returns an empty array if the argument is an empty array.Person.find# raises ActiveRecord::RecordNotFound exception if the argument is not provided.
find_by(arg, *args)Link
Finds the first record matching the specified conditions. There is no implied ordering so if order matters, you should specify it yourself.
If no record is found, returnsnil.
Post.find_byname:'Spartacus',rating:4Post.find_by"published_at < ?",2.weeks.ago
find_by!(arg, *args)Link
Likefind_by, except that if no record is found, raises anActiveRecord::RecordNotFound error.
find_sole_by(arg, *args)Link
Finds the sole matching record. RaisesActiveRecord::RecordNotFound if no record is found. RaisesActiveRecord::SoleRecordExceeded if more than one record is found.
Product.find_sole_by(["price = %?",price])
first(limit = nil)Link
Find the first record (or first N records if a parameter is supplied). If no order is defined it will order by primary key.
Person.first# returns the first object fetched by SELECT * FROM people ORDER BY people.id LIMIT 1Person.where(["user_name = ?",user_name]).firstPerson.where(["user_name = :u", {u:user_name }]).firstPerson.order("created_on DESC").offset(5).firstPerson.first(3)# returns the first three objects fetched by SELECT * FROM people ORDER BY people.id LIMIT 3
first!()Link
Same asfirst but raisesActiveRecord::RecordNotFound if no record is found. Note thatfirst! accepts no arguments.
forty_two()Link
Find the forty-second record. Also known as accessing “the reddit”. If no order is defined it will order by primary key.
Person.forty_two# returns the forty-second object fetched by SELECT * FROM peoplePerson.offset(3).forty_two# returns the forty-second object from OFFSET 3 (which is OFFSET 44)Person.where(["user_name = :u", {u:user_name }]).forty_two
forty_two!()Link
Same asforty_two but raisesActiveRecord::RecordNotFound if no record is found.
fourth()Link
Find the fourth record. If no order is defined it will order by primary key.
Person.fourth# returns the fourth object fetched by SELECT * FROM peoplePerson.offset(3).fourth# returns the fourth object from OFFSET 3 (which is OFFSET 6)Person.where(["user_name = :u", {u:user_name }]).fourth
fourth!()Link
Same asfourth but raisesActiveRecord::RecordNotFound if no record is found.
include?(record)Link
Returns true if the relation contains the given record or false otherwise.
No query is performed if the relation is loaded; the given record is compared to the records in memory. If the relation is unloaded, an efficient existence query is performed, as inexists?.
# File activerecord/lib/active_record/relation/finder_methods.rb, line 389definclude?(record)# The existing implementation relies on receiving an Active Record instance as the input parameter named record.# Any non-Active Record object passed to this implementation is guaranteed to return `false`.returnfalseunlessrecord.is_a?(model)ifloaded?||offset_value||limit_value||having_clause.any?records.include?(record)elseid =ifrecord.class.composite_primary_key?record.class.primary_key.zip(record.id).to_helserecord.idendexists?(id)endend
last(limit = nil)Link
Find the last record (or last N records if a parameter is supplied). If no order is defined it will order by primary key.
Person.last# returns the last object fetched by SELECT * FROM peoplePerson.where(["user_name = ?",user_name]).lastPerson.order("created_on DESC").offset(5).lastPerson.last(3)# returns the last three objects fetched by SELECT * FROM people.
Take note that in that last case, the results are sorted in ascending order:
[#<Person id:2>, #<Person id:3>, #<Person id:4>]
and not:
[#<Person id:4>, #<Person id:3>, #<Person id:2>]
last!()Link
Same aslast but raisesActiveRecord::RecordNotFound if no record is found. Note thatlast! accepts no arguments.
second()Link
Find the second record. If no order is defined it will order by primary key.
Person.second# returns the second object fetched by SELECT * FROM peoplePerson.offset(3).second# returns the second object from OFFSET 3 (which is OFFSET 4)Person.where(["user_name = :u", {u:user_name }]).second
second!()Link
Same assecond but raisesActiveRecord::RecordNotFound if no record is found.
second_to_last()Link
Find the second-to-last record. If no order is defined it will order by primary key.
Person.second_to_last# returns the second-to-last object fetched by SELECT * FROM peoplePerson.offset(3).second_to_last# returns the second-to-last object from OFFSET 3Person.where(["user_name = :u", {u:user_name }]).second_to_last
second_to_last!()Link
Same assecond_to_last but raisesActiveRecord::RecordNotFound if no record is found.
sole()Link
Finds the sole matching record. RaisesActiveRecord::RecordNotFound if no record is found. RaisesActiveRecord::SoleRecordExceeded if more than one record is found.
Product.where(["price = %?",price]).sole
take(limit = nil)Link
Gives a record (or N records if a parameter is supplied) without any implied order. The order will depend on the database implementation. If an order is supplied it will be respected.
Person.take# returns an object fetched by SELECT * FROM people LIMIT 1Person.take(5)# returns 5 objects fetched by SELECT * FROM people LIMIT 5Person.where(["name LIKE '%?'",name]).take
take!()Link
Same astake but raisesActiveRecord::RecordNotFound if no record is found. Note thattake! accepts no arguments.
third()Link
Find the third record. If no order is defined it will order by primary key.
Person.third# returns the third object fetched by SELECT * FROM peoplePerson.offset(3).third# returns the third object from OFFSET 3 (which is OFFSET 5)Person.where(["user_name = :u", {u:user_name }]).third
third!()Link
Same asthird but raisesActiveRecord::RecordNotFound if no record is found.
third_to_last()Link
Find the third-to-last record. If no order is defined it will order by primary key.
Person.third_to_last# returns the third-to-last object fetched by SELECT * FROM peoplePerson.offset(3).third_to_last# returns the third-to-last object from OFFSET 3Person.where(["user_name = :u", {u:user_name }]).third_to_last
third_to_last!()Link
Same asthird_to_last but raisesActiveRecord::RecordNotFound if no record is found.