Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Basic Searching

Jon Atack edited this page · 18 revisions
Clone this wiki locally

The primary method of searching in Ransack is by using what is 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.ransack(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.ransack(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.ransack(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.ransack(name_cont: 'Rya').result.to_sql
    => "SELECT "users".* FROM "users"

eq (equals)

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

    >> User.ransack(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.ransack(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 (less than)

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

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

Opposite: gt (greater than)

lteq (less than or equal to)

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

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

Opposite: gteq (greater than or equal to)

in

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

    >> User.ransack(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.ransack(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.ransack(first_name_cont: 'Rya').result.to_sql
    => SELECT "users".* FROM "users"  WHERE ("users"."first_name" LIKE '%Rya%')

Opposite: not_cont

cont_any (contains any)

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

    >> User.ransack(first_name_cont_any: %w(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

i_cont (work-in-progress, don't use yet)

The i_cont case-insensitive predicate returns all records where a field contains a given value and ignores case:

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

Opposite: i_not_cont

start (starts with)

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

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

Opposite: not_start

end (ends with)

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

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

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.ransack(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: not_true

false

The false predicate returns all records where a field is false.

    >> User.ransack(awesome_false: '1').result.to_sql
    => SELECT "users".* FROM "users"  WHERE ("users"."awesome" = 'f')

Opposite: not_false

Note: the false predicate may be considered the opposite of the true predicate if the field does not contain null values. Otherwise, use not_false.

present

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

    >> User.ransack(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.ransack(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.