Ransack is a rewrite of MetaSearch created by Ernie Miller and developed/maintained for years by Jon Atack and Ryan Bigg with the help of a great group of contributors. While it supports many of the same features as MetaSearch, its underlying implementation differs greatly from MetaSearch, and backwards compatibility is not a design goal.
Ransack enables the creation of both simple and advanced search forms for your Ruby on Rails application (demo source code here). If you're looking for something that simplifies query generation at the model or controller layer, you're probably not looking for Ransack (or MetaSearch, for that matter). Try Squeel instead.
If you're viewing this at github.com/activerecord-hackery/ransack, you're reading the documentation for the master branch with the latest features. View documentation for the last release (2.0.0).
Ransack is compatible with Rails 5.0, 5.1 and 5.2 on Ruby 2.2 and later. If you are using Rails <5.0 use the 1.8 line of Ransack. If you are using Ruby 1.8 or an earlier JRuby and run into compatibility issues, you can use an earlier version of Ransack, say, up to 1.3.0.
Ransack works out-of-the-box with Active Record and also features limited support for Mongoid 4 and 5 (without associations, further details below).
In your Gemfile, for the last officially released gem:
gem 'ransack'
If you would like to use the latest updates (recommended), use the master
branch:
gem 'ransack', github: 'activerecord-hackery/ransack'
- Before filing an issue, please read the Contributing Guide.
- File an issue if a bug is caused by Ransack, is new (has not already been reported), and can be reproduced from the information you provide.
- Contributions are welcome, but please do not add "+1" comments to issues or pull requests ๐
- Please do not use the issue tracker for personal support requests. Stack Overflow is a better place for that where a wider community can help you!
Ransack can be used in one of two modes, simple or advanced.
This mode works much like MetaSearch, for those of you who are familiar with it, and requires very little setup effort.
If you're coming from MetaSearch, things to note:
-
The default param key for search params is now
:q
, instead of:search
. This is primarily to shorten query strings, though advanced queries (below) will still run afoul of URL length limits in most browsers and require a switch to HTTP POST requests. This key is configurable. -
form_for
is nowsearch_form_for
, and validates that a Ransack::Search object is passed to it. -
Common ActiveRecord::Relation methods are no longer delegated by the search object. Instead, you will get your search results (an ActiveRecord::Relation in the case of the ActiveRecord adapter) via a call to
Ransack#result
.
def index
@q = Person.ransack(params[:q])
@people = @q.result(distinct: true)
end
or without distinct: true
, for sorting on an associated table's columns (in
this example, with preloading each Person's Articles and pagination):
def index
@q = Person.ransack(params[:q])
@people = @q.result.includes(:articles).page(params[:page])
# or use `to_a.uniq` to remove duplicates (can also be done in the view):
@people = @q.result.includes(:articles).page(params[:page]).to_a.uniq
end
The two primary Ransack view helpers are search_form_for
and sort_link
,
which are defined in
Ransack::Helpers::FormHelper.
<%= search_form_for @q do |f| %>
# Search if the name field contains...
<%= f.label :name_cont %>
<%= f.search_field :name_cont %>
# Search if an associated articles.title starts with...
<%= f.label :articles_title_start %>
<%= f.search_field :articles_title_start %>
# Attributes may be chained. Search multiple attributes for one value...
<%= f.label :name_or_description_or_email_or_articles_title_cont %>
<%= f.search_field :name_or_description_or_email_or_articles_title_cont %>
<%= f.submit %>
<% end %>
cont
(contains) and start
(starts with) are just two of the available
search predicates. See
Constants
for a full list and the
wiki
for more information.
The search_form_for
answer format can be set like this:
<%= search_form_for(@q, format: :pdf) do |f| %>
<%= search_form_for(@q, format: :json) do |f| %>
<%= sort_link(@q, :name) %>
Additional options can be passed after the column attribute, like a different column title or a default sort order:
<%= sort_link(@q, :name, 'Last Name', default_order: :desc) %>
You can use a block if the link markup is hard to fit into the label parameter:
<%= sort_link(@q, :name) do %>
<strong>Player Name</strong>
<% end %>
With a polymorphic association, you may need to specify the name of the link
explicitly to avoid an uninitialized constant Model::Xxxable
error (see issue
#421):
<%= sort_link(@q, :xxxable_of_Ymodel_type_some_attribute, 'Attribute Name') %>
You can also sort on multiple fields by specifying an ordered array:
<%= sort_link(@q, :last_name, [:last_name, 'first_name asc'], 'Last Name') %>
In the example above, clicking the link will sort by last_name
and then
first_name
. Specifying the sort direction on a field in the array tells
Ransack to always sort that particular field in the specified direction.
Multiple default_order
fields may also be specified with a hash:
<%= sort_link(@q, :last_name, %i(last_name first_name),
default_order: { last_name: 'asc', first_name: 'desc' }) %>
This example toggles the sort directions of both fields, by default
initially sorting the last_name
field by ascending order, and the
first_name
field by descending order.
The sort link order indicator arrows may be globally customized by setting a
custom_arrows
option in an initializer file like
config/initializers/ransack.rb
.
You can also enable a default_arrow
which is displayed on all sortable fields
which are not currently used in the sorting. This is disabled by default so
nothing will be displayed:
Ransack.configure do |c|
c.custom_arrows = {
up_arrow: '<i class="custom-up-arrow-icon"></i>',
down_arrow: 'U+02193',
default_arrow: '<i class="default-arrow-icon"></i>'
}
end
All sort links may be displayed without the order indicator
arrows by setting hide_sort_order_indicators
to true in the initializer file.
Note that this hides the arrows even if they were customized:
Ransack.configure do |c|
c.hide_sort_order_indicators = true
end
Without setting it globally, individual sort links may be displayed without
the order indicator arrow by passing hide_indicator: true
in the sort link:
<%= sort_link(@q, :name, hide_indicator: true) %>
sort_url
has the same API as sort_link
:
<%= sort_url(@q, :name, default_order: :desc) %>
<%= sort_url(@q, :last_name, [:last_name, 'first_name asc']) %>
<%= sort_url(@q, :last_name, %i(last_name first_name),
default_order: { last_name: 'asc', first_name: 'desc' }) %>
"Advanced" searches (ab)use Rails' nested attributes functionality in order to generate complex queries with nested AND/OR groupings, etc. This takes a bit more work but can generate some pretty cool search interfaces that put a lot of power in the hands of your users. A notable drawback with these searches is that the increased size of the parameter string will typically force you to use the HTTP POST method instead of GET. :(
This means you'll need to tweak your routes...
resources :people do
collection do
match 'search' => 'people#search', via: [:get, :post], as: :search
end
end
... and add another controller action ...
def search
index
render :index
end
... and update your search_form_for
line in the view ...
<%= search_form_for @q, url: search_people_path,
html: { method: :post } do |f| %>
Once you've done so, you can make use of the helpers in Ransack::Helpers::FormBuilder to construct much more complex search forms, such as the one on the demo app (source code here).
Ransack will try to make the class method #search
available in your
models, but if #search
has already been defined elsewhere, you can always use
the default #ransack
class method. So the following are equivalent:
Article.ransack(params[:q])
Article.search(params[:q])
Users have reported issues of #search
name conflicts with other gems, so
the #search
method alias will be deprecated in the next major version of
Ransack (2.0). It's advisable to use the default #ransack
instead.
For now, if Ransack's #search
method conflicts with the name of another
method named search
in your code or another gem, you may resolve it either by
patching the extended
class_method in Ransack::Adapters::ActiveRecord::Base
to remove the line alias :search :ransack unless base.respond_to? :search
, or
by placing the following line in your Ransack initializer file at
config/initializers/ransack.rb
:
Ransack::Adapters::ActiveRecord::Base.class_eval('remove_method :search')
You can easily use Ransack to search for objects in has_many
and belongs_to
associations.
Given these associations...
class Employee < ActiveRecord::Base
belongs_to :supervisor
# has attributes first_name:string and last_name:string
end
class Department < ActiveRecord::Base
has_many :supervisors
# has attribute title:string
end
class Supervisor < ActiveRecord::Base
belongs_to :department
has_many :employees
# has attribute last_name:string
end
... and a controller...
class SupervisorsController < ApplicationController
def index
@q = Supervisor.ransack(params[:q])
@supervisors = @q.result.includes(:department, :employees)
end
end
... you might set up your form like this...
<%= search_form_for @q do |f| %>
<%= f.label :last_name_cont %>
<%= f.search_field :last_name_cont %>
<%= f.label :department_title_cont %>
<%= f.search_field :department_title_cont %>
<%= f.label :employees_first_name_or_employees_last_name_cont %>
<%= f.search_field :employees_first_name_or_employees_last_name_cont %>
<%= f.submit "search" %>
<% end %>
...
<%= content_tag :table do %>
<%= content_tag :th, sort_link(@q, :last_name) %>
<%= content_tag :th, sort_link(@q, :department_title) %>
<%= content_tag :th, sort_link(@q, :employees_last_name) %>
<% end %>
If you have trouble sorting on associations, try using an SQL string with the
pluralized table ('departments.title'
,'employees.last_name'
) instead of the
symbolized association (:department_title)
, :employees_last_name
).
You can customize the attribute names for your Ransack searches by using a
ransack_alias
. This is particularly useful for long attribute names that are
necessary when querying associations or multiple columns.
class Post < ActiveRecord::Base
belongs_to :author
# Abbreviate :author_first_name_or_author_last_name to :author
ransack_alias :author, :author_first_name_or_author_last_name
end
Now, rather than using :author_first_name_or_author_last_name_cont
in your
form, you can simply use :author_cont
. This serves to produce more expressive
query parameters in your URLs.
<%= search_form_for @q do |f| %>
<%= f.label :author_cont %>
<%= f.search_field :author_cont %>
<% end %>
List of all possible predicates
Predicate | Description | Notes |
---|---|---|
*_eq |
equal | |
*_not_eq |
not equal | |
*_matches |
matches with LIKE |
e.g. q[email_matches]=%@gmail.com |
*_does_not_match |
does not match with LIKE |
|
*_matches_any |
Matches any | |
*_matches_all |
Matches all | |
*_does_not_match_any |
Does not match any | |
*_does_not_match_all |
Does not match all | |
*_lt |
less than | |
*_lteq |
less than or equal | |
*_gt |
greater than | |
*_gteq |
greater than or equal | |
*_present |
not null and not empty | Only compatible with string columns. Example: q[name_present]=1 (SQL: col is not null AND col != '' ) |
*_blank |
is null or empty. | (SQL: col is null OR col = '' ) |
*_null |
is null | |
*_not_null |
is not null | |
*_in |
match any values in array | e.g. q[name_in][]=Alice&q[name_in][]=Bob |
*_not_in |
match none of values in array | |
*_lt_any |
Less than any | SQL: col < value1 OR col < value2 |
*_lteq_any |
Less than or equal to any | |
*_gt_any |
Greater than any | |
*_gteq_any |
Greater than or equal to any | |
*_matches_any |
*_does_not_match_any |
same as above but with LIKE |
*_lt_all |
Less than all | SQL: col < value1 AND col < value2 |
*_lteq_all |
Less than or equal to all | |
*_gt_all |
Greater than all | |
*_gteq_all |
Greater than or equal to all | |
*_matches_all |
Matches all | same as above but with LIKE |
*_does_not_match_all |
Does not match all | |
*_not_eq_all |
none of values in a set | |
*_start |
Starts with | SQL: col LIKE 'value%' |
*_not_start |
Does not start with | |
*_start_any |
Starts with any of | |
*_start_all |
Starts with all of | |
*_not_start_any |
Does not start with any of | |
*_not_start_all |
Does not start with all of | |
*_end |
Ends with | SQL: col LIKE '%value' |
*_not_end |
Does not end with | |
*_end_any |
Ends with any of | |
*_end_all |
Ends with all of | |
*_not_end_any |
||
*_not_end_all |
||
*_cont |
Contains value | uses LIKE |
*_cont_any |
Contains any of | |
*_cont_all |
Contains all of | |
*_not_cont |
Does not contain | |
*_not_cont_any |
Does not contain any of | |
*_not_cont_all |
Does not contain all of | |
*_true |
is true | |
*_false |
is false |
(See full list: https://github.com/activerecord-hackery/ransack/blob/master/lib/ransack/locale/en.yml#L15 and wiki)
The main premise behind Ransack is to provide access to
Arel predicate methods. Ransack provides special methods, called
ransackers, for creating additional search functions via Arel. More
information about ransacker
methods can be found here in the wiki.
Feel free to contribute working ransacker
code examples to the wiki!
If passed distinct: true
, result
will generate a SELECT DISTINCT
to
avoid returning duplicate rows, even if conditions on a join would otherwise
result in some. It generates the same SQL as calling uniq
on the relation.
Please note that for many databases, a sort on an associated table's columns
may result in invalid SQL with distinct: true
-- in those cases, you
will need to modify the result as needed to allow these queries to work.
For example, you could call joins and includes on the result which has the effect of adding those tables columns to the select statement, overcoming the issue, like so:
def index
@q = Person.ransack(params[:q])
@people = @q.result(distinct: true)
.includes(:articles)
.joins(:articles)
.page(params[:page])
end
If the above doesn't help, you can also use ActiveRecord's select
query
to explicitly add the columns you need, which brute force's adding the
columns you need that your SQL engine is complaining about, you need to
make sure you give all of the columns you care about, for example:
def index
@q = Person.ransack(params[:q])
@people = @q.result(distinct: true)
.select('people.*, articles.name, articles.description')
.page(params[:page])
end
Another method to approach this when using Postgresql is to use ActiveRecords's .includes
in combination with .group
instead of distinct: true
.
For example:
def index
@q = Person.ransack(params[:q])
@people = @q.result
.group('persons.id')
.includes(:articles)
.page(params[:page])
end
A final way of last resort is to call to_a.uniq
on the collection at the end
with the caveat that the de-duping is taking place in Ruby instead of in SQL,
which is potentially slower and uses more memory, and that it may display
awkwardly with pagination if the number of results is greater than the page size.
For example:
def index
@q = Person.ransack(params[:q])
@people = @q.result.includes(:articles).page(params[:page]).to_a.uniq
end
If you get the above error while using distinct: true
that means that
one of the columns that Ransack is selecting is a json
column.
PostgreSQL does not provide comparison operators for the json
type. While
it is possible to work around this, in practice it's much better to convert those
to jsonb
, as recommended by the PostgreSQL documentation.
By default, searching and sorting are authorized on any column of your model and no class methods/scopes are whitelisted.
Ransack adds four methods to ActiveRecord::Base
that you can redefine as
class methods in your models to apply selective authorization:
ransackable_attributes
, ransackable_associations
, ransackable_scopes
and
ransortable_attributes
.
Here is how these four methods are implemented in Ransack:
# `ransackable_attributes` by default returns all column names
# and any defined ransackers as an array of strings.
# For overriding with a whitelist array of strings.
#
def ransackable_attributes(auth_object = nil)
column_names + _ransackers.keys
end
# `ransackable_associations` by default returns the names
# of all associations as an array of strings.
# For overriding with a whitelist array of strings.
#
def ransackable_associations(auth_object = nil)
reflect_on_all_associations.map { |a| a.name.to_s }
end
# `ransortable_attributes` by default returns the names
# of all attributes available for sorting as an array of strings.
# For overriding with a whitelist array of strings.
#
def ransortable_attributes(auth_object = nil)
ransackable_attributes(auth_object)
end
# `ransackable_scopes` by default returns an empty array
# i.e. no class methods/scopes are authorized.
# For overriding with a whitelist array of *symbols*.
#
def ransackable_scopes(auth_object = nil)
[]
end
Any values not returned from these methods will be ignored by Ransack, i.e. they are not authorized.
All four methods can receive a single optional parameter, auth_object
. When
you call the search or ransack method on your model, you can provide a value
for an auth_object
key in the options hash which can be used by your own
overridden methods.
Here is an example that puts all this together, adapted from
this blog post by Ernie Miller.
In an Article
model, add the following ransackable_attributes
class method
(preferably private):
class Article < ActiveRecord::Base
def self.ransackable_attributes(auth_object = nil)
if auth_object == :admin
# whitelist all attributes for admin
super
else
# whitelist only the title and body attributes for other users
super & %w(title body)
end
end
private_class_method :ransackable_attributes
end
Here is example code for the articles_controller
:
class ArticlesController < ApplicationController
def index
@q = Article.ransack(params[:q], auth_object: set_ransack_auth_object)
@articles = @q.result
end
private
def set_ransack_auth_object
current_user.admin? ? :admin : nil
end
end
Trying it out in rails console
:
> Article
=> Article(id: integer, person_id: integer, title: string, body: text)
> Article.ransackable_attributes
=> ["title", "body"]
> Article.ransackable_attributes(:admin)
=> ["id", "person_id", "title", "body"]
> Article.ransack(id_eq: 1).result.to_sql
=> SELECT "articles".* FROM "articles" # Note that search param was ignored!
> Article.ransack({ id_eq: 1 }, { auth_object: nil }).result.to_sql
=> SELECT "articles".* FROM "articles" # Search param still ignored!
> Article.ransack({ id_eq: 1 }, { auth_object: :admin }).result.to_sql
=> SELECT "articles".* FROM "articles" WHERE "articles"."id" = 1
That's it! Now you know how to whitelist/blacklist various elements in Ransack.
Continuing on from the preceding section, searching by scopes requires defining
a whitelist of ransackable_scopes
on the model class. The whitelist should be
an array of symbols. By default, all class methods (e.g. scopes) are ignored.
Scopes will be applied for matching true
values, or for given values if the
scope accepts a value:
class Employee < ActiveRecord::Base
scope :activated, ->(boolean = true) { where(active: boolean) }
scope :salary_gt, ->(amount) { where('salary > ?', amount) }
# Scopes are just syntactical sugar for class methods, which may also be used:
def self.hired_since(date)
where('start_date >= ?', date)
end
def self.ransackable_scopes(auth_object = nil)
if auth_object.try(:admin?)
# allow admin users access to all three methods
%i(activated hired_since salary_gt)
else
# allow other users to search on `activated` and `hired_since` only
%i(activated hired_since)
end
end
private_class_method :ransackable_scopes
end
Employee.ransack({ activated: true, hired_since: '2013-01-01' })
Employee.ransack({ salary_gt: 100_000 }, { auth_object: current_user })
In Rails 3 and 4, if the true
value is being passed via url params or some
other mechanism that will convert it to a string, the true value may not be
passed to the ransackable scope unless you wrap it in an array
(i.e. activated: ['true']
). Ransack will take care of changing 'true' into a
boolean. This is currently resolved in Rails 5 ๐
However, perhaps you have user_id: [1]
and you do not want Ransack to convert
1 into a boolean. (Values sanitized to booleans can be found in the
constants.rb).
To turn this off globally, and handle type conversions yourself, set
sanitize_custom_scope_booleans
to false in an initializer file like
config/initializers/ransack.rb:
Ransack.configure do |c|
c.sanitize_custom_scope_booleans = false
end
To turn this off on a per-scope basis Ransack adds the following method to
ActiveRecord::Base
that you can redefine to selectively override sanitization:
ransackable_scopes_skip_sanitize_args
Add the scope you wish to bypass this behavior to ransackable_scopes_skip_sanitize_args:
def ransackable_scopes_skip_sanitize_args
[:scope_to_skip_sanitize_args]
end
Scopes are a recent addition to Ransack and currently have a few caveats: First, a scope involving child associations needs to be defined in the parent table model, not in the child model. Second, scopes with an array as an argument are not easily usable yet, because the array currently needs to be wrapped in an array to function (see this issue), which is not compatible with Ransack form helpers. For this use case, it may be better for now to use ransackers instead, where feasible. Pull requests with solutions and tests are welcome!
The default AND
grouping can be changed to OR
by adding m: 'or'
to the
query hash.
You can easily try it in your controller code by changing params[:q]
in the
index
action to params[:q].try(:merge, m: 'or')
as follows:
def index
@q = Artist.ransack(params[:q].try(:merge, m: 'or'))
@artists = @q.result
end
Normally, if you wanted users to be able to toggle between AND
and OR
query grouping, you would probably set up your search form so that m
was in
the URL params hash, but here we assigned m
manually just to try it out
quickly.
Alternatively, trying it in the Rails console:
artists = Artist.ransack(name_cont: 'foo', style_cont: 'bar', m: 'or')
=> Ransack::Search<class: Artist, base: Grouping <conditions: [
Condition <attributes: ["name"], predicate: cont, values: ["foo"]>,
Condition <attributes: ["style"], predicate: cont, values: ["bar"]>
], combinator: or>>
artists.result.to_sql
=> "SELECT \"artists\".* FROM \"artists\"
WHERE ((\"artists\".\"name\" ILIKE '%foo%'
OR \"artists\".\"style\" ILIKE '%bar%'))"
The combinator becomes or
instead of the default and
, and the SQL query
becomes WHERE...OR
instead of WHERE...AND
.
This works with associations as well. Imagine an Artist model that has many Memberships, and many Musicians through Memberships:
artists = Artist.ransack(name_cont: 'foo', musicians_email_cont: 'bar', m: 'or')
=> Ransack::Search<class: Artist, base: Grouping <conditions: [
Condition <attributes: ["name"], predicate: cont, values: ["foo"]>,
Condition <attributes: ["musicians_email"], predicate: cont, values: ["bar"]>
], combinator: or>>
artists.result.to_sql
=> "SELECT \"artists\".* FROM \"artists\"
LEFT OUTER JOIN \"memberships\"
ON \"memberships\".\"artist_id\" = \"artists\".\"id\"
LEFT OUTER JOIN \"musicians\"
ON \"musicians\".\"id\" = \"memberships\".\"musician_id\"
WHERE ((\"artists\".\"name\" ILIKE '%foo%'
OR \"musicians\".\"email\" ILIKE '%bar%'))"
If you would like to combine the Ransack and SimpleForm form builders, set the
RANSACK_FORM_BUILDER
environment variable before Rails boots up, e.g. in
config/application.rb
before require 'rails/all'
as shown below (and add
gem 'simple_form'
in your Gemfile).
require File.expand_path('../boot', __FILE__)
ENV['RANSACK_FORM_BUILDER'] = '::SimpleForm::FormBuilder'
require 'rails/all'
Ransack translation files are available in Ransack::Locale. You may also be interested in one of the many translations for Ransack available at http://www.localeapp.com/projects/2999.
Predicate and attribute translations in forms may be specified as follows (see the translation files in Ransack::Locale for more examples):
locales/en.yml:
en:
ransack:
asc: ascending
desc: descending
predicates:
cont: contains
not_cont: not contains
start: starts with
end: ends with
gt: greater than
lt: less than
models:
person: Passanger
attributes:
person:
name: Full Name
article:
title: Article Title
body: Main Content
Attribute names may also be changed globally, or under activerecord
:
en:
attributes:
model_name:
model_field1: field name1
model_field2: field name2
activerecord:
attributes:
namespace/article:
title: AR Namespaced Title
namespace_article:
title: Old Ransack Namespaced Title
Mongoid support has been moved to its own gem at ransack-mongoid.
Ransack works with Mongoid in the same way as Active Record, except that with
Mongoid, associations are not currently supported. Demo source code may be found
here. A result
method
called on a ransack
search returns a Mongoid::Criteria
object:
@q = Person.ransack(params[:q])
@people = @q.result # => Mongoid::Criteria
# or you can add more Mongoid queries
@people = @q.result.active.order_by(updated_at: -1).limit(10)
NOTE: Ransack currently works with either Active Record or Mongoid, but not
both in the same application. If both are present, Ransack will default to
Active Record only. The logic is contained in
Ransack::Adapters#instantiate_object_mapper
should you need to override it.
Ransack attempts to follow semantic versioning in the format of x.y.z
, where:
x
stands for a major version (new features that are not backward-compatible).
y
stands for a minor version (new features that are backward-compatible).
z
stands for a patch (bug fixes).
In other words: Major.Minor.Patch
.
To support the project:
- Use Ransack in your apps, and let us know if you encounter anything that's broken or missing. A failing spec to demonstrate the issue is awesome. A pull request with passing tests is even better!
- Before filing an issue or pull request, be sure to read and follow the Contributing Guide.
- Please use Stack Overflow or other sites for questions or discussion not directly related to bug reports, pull requests, or documentation improvements.
- Spread the word on Twitter, Facebook, and elsewhere if Ransack's been useful to you. The more people who are using the project, the quicker we can find and fix bugs!