Skip to content
This repository

The primary method of searching in Ransack is by using what's known as predicates.

Predicates are used within Ransack search queries to determine what information to match. For instance, the cont predicate will check to see if an attribute called "first_name" contains a value using a wildcard query:

>> User.search(:first_name_cont => "Rya").result.to_sql
=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE '%Rya%')

You can also combine predicates for OR queries:

>> User.search(:first_name_or_last_name_cont => "Rya").result.to_sql
=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE '%Rya%' 
   OR "users"."last_name" LIKE '%Rya%')

The syntax for OR queries on an associated model is not immediately obvious, but makes sense. Assuming a User has_one Account and the Account has attributes foo and bar:

>> User.search(:account_foo_or_account_bar => "val").result.to_sql
=> SELECT "users".* FROM "users" INNER JOIN accounts ON accounts.user_id = users.id WHERE ("accounts.foo LIKE '%val%' OR accounts.bar LIKE '%val%')

Below is a list of the built-in predicates of Ransack and their opposites. You may already be familiar with some of the predicates, as they also exist in the ARel library.

If you want to add your own, please see the Custom-Predicates page.

Please note: any attempt to use a predicate for an attribute that does not exist will silently fail. For instance, this will not work when there is no name attribute:

>> User.search(:name_cont => "Rya").result.to_sql
=> "SELECT "users".* FROM "users"

eq

The eq predicate returns all records where a field is exactly equal to a given value:

>> User.search(:first_name_eq => "Ryan").result.to_sql
=> SELECT "users".* FROM "users" WHERE "users"."first_name" = 'Ryan'

Opposite: not_eq

matches

The matches predicate returns all records where a field is like a given value:

>> User.search(:first_name_matches => "Ryan").result.to_sql
=> SELECT "users".* FROM "users" WHERE ("users"."first_name" LIKE 'Ryan')

Opposite: does_not_match

*Note: If you want to do wildcard matching, you may be looking for the cont/not_cont predicates instead.

lt

The lt predicate returns all records where a field is less than a given value:

>> User.search(:age_lt => 25).result.to_sql
=> SELECT "users".* FROM "users" WHERE ("users"."age" < 25)

Opposite: gt

lteq

The lteq predicate returns all records where a field is less than or equal to a given value:

>> User.search(:age_lteq => 25).result.to_sql
=> SELECT "users".* FROM "users" WHERE ("users"."age" <= 25)

Opposite: gteq

in

The in predicate returns all records where a field is within a specified list:

>> User.search(:age_in => 20..25).result.to_sql
=> SELECT "users".* FROM "users" WHERE "users"."age" IN (20, 21, 22, 23, 24, 25)

It can also take an array:

>> User.search(:age_in => [20, 21, 22, 23, 24, 25]).result.to_sql
=> SELECT "users".* FROM "users" WHERE "users"."age" IN (20, 21, 22, 23, 24, 25)

Opposite: not_in

cont

The cont predicate returns all records where a field contains a given value:

>> User.search(:first_name_cont => "Rya").result.to_sql
=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE '%Rya%')

Opposite: not_cont

cont_any

The cont_any predicate returns all records where a field contains any of given values:

>> User.search(:first_name_cont_any => ["Rya", "Lis"]).result.to_sql
=> SELECT "users".* FROM "users"  WHERE (("users"."first_name" LIKE '%Rya%' OR "users"."first_name" LIKE '%Lis%'))

Opposite: not_cont_any

start

The start predicate returns all records where a field begins with a given value:

>> User.search(:first_name_start => "Rya").result.to_sql
=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE 'Rya%')

Opposite: not_start

end

The end predicate returns all records where a field ends with a given value:

>> User.search(:first_name_end => "Rya").result.to_sql
=> SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE '%Rya')

Opposite: not_end

true

The true predicate returns all records where a field is true. The "1" indicates that to Ransack that you indeed want to check the truthiness of this field. The other truthy values are 'true', 'TRUE', 't' or 'T'.

>> User.search(:awesome_true => "1").result.to_sql
=> SELECT "users".* FROM "users"  WHERE ("users"."awesome" = 't')

Note: different database systems use different values to represent truth. In the above example, we are using SQLite3.

Opposite: false

present

The present predicate returns all records where a field is present (not null and not a blank string).

>> User.search(:first_name_present => "1")
=> SELECT "users".* FROM "users"  WHERE (("users"."first_name" IS NOT NULL AND "users"."first_name" != ''))

Opposite: blank

null

The null predicate returns all records where a field is null:

>> User.search(:first_name_null => 1).result.to_sql
=> SELECT "users".* FROM "users"  WHERE "users"."first_name" IS NULL

Opposite: not_null

Something went wrong with that request. Please try again.