Ransack Aliases

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 %>

You can also use ransack_alias for sorting.

class Post < ActiveRecord::Base
  belongs_to :author

  # Abbreviate :author_first_name to :author
  ransack_alias :author, :author_first_name
end

Now, you can use :author instead of :author_first_name in a sort_link.

<%= sort_link(@q, :author) %>

Note that using :author_first_name_or_author_last_name_cont would produce an invalid sql query. In those cases, Ransack ignores the sorting clause.

Aliases through associations and in compounds

An alias is resolved wherever its name appears: on its own, as a segment of an _or_ / _and_ name, and after an association path when it is defined on the associated model.

class Author < ActiveRecord::Base
  ransack_alias :name, :first_name_or_last_name
end

class Post < ActiveRecord::Base
  belongs_to :author
  ransack_alias :text, :title_or_body
end

Post.ransack(author_name_cont: 'a')        # first_name OR last_name on authors
Post.ransack(text_or_author_name_cont: 'a') # title OR body OR first_name OR last_name

An alias that expands to a compound joins with its own combinator, so combine it with the same one: text_and_author_name_cont would mix _or_ and _and_, which a strict search rejects (see Simple Mode).

The alias name itself does not need to be in ransackable_attributes; the attributes it expands to do. An alias whose target is not a searchable attribute is ignored, or raises Ransack::InvalidSearchError under ransack!, like any other unknown attribute.

Before Ransack 6.0 an alias was only resolved on the searched model and only as the whole name: author_name_cont and text_or_author_name_cont produced SQL referring to columns that do not exist.

Problem with DISTINCT selects

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

Problem with Globalized Attributes and Sorting

When using internationalization gems like Globalize, you may encounter issues when trying to sort on translated attributes of associations while also having pre-existing joins to translation tables.

Problem scenario:

# This may fail to generate proper joins:
Book.joins(:translations).ransack({ s: ['category_translations_name asc'] }).result

Solution: The simplest and most effective approach is to use the sort_link helper directly with the translation attribute:

<!-- This works perfectly for sorting on translated attributes -->
<%= sort_link @search, :translations_name %>
<%= sort_link @search, :category_translations_name %>

For programmatic sorting, let Ransack establish the sorting joins first, then add your additional joins:

# Let Ransack handle the sorting joins first
search = Book.ransack({ s: ['category_translations_name asc'] })
results = search.result.joins(:translations)

# Or use includes for complex scenarios
search = Book.ransack({ s: ['category_translations_name asc'] })
results = search.result.includes(:translations, category: :translations)

This ensures that Ransack properly handles the join dependencies between your main model’s translations and the associated model’s translations.

PG::UndefinedFunction: ERROR: could not identify an equality operator for type json

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.

Authorization (allowlisting/denylisting)

By default, searching and sorting are not authorized on any column of your model and no class methods/scopes are allowlisted.

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
• ransortable_attributes

Here is how these four methods could be implemented in your application:

  # `ransackable_attributes` returns searchable column names
  # and any defined ransackers as an array of strings.
  #
  def ransackable_attributes(auth_object = nil)
    %w(title body) + _ransackers.keys
  end

  # `ransackable_associations` returns the names
  # of searchable associations as an array of strings.
  #
  def ransackable_associations(auth_object = nil)
    %w[author]
  end

  # `ransortable_attributes` by default returns the names
  # of all attributes available for sorting as an 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 an allowlist, return an 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.

Searching everything

Ransack also defines authorizable_ransackable_attributes and authorizable_ransackable_associations, which return every column, ransacker and alias, and every association. To restore the pre-4.0 behaviour where everything is searchable, delegate to them once in the base class:

class ApplicationRecord < ActiveRecord::Base
  primary_abstract_class

  def self.ransackable_attributes(auth_object = nil)
    authorizable_ransackable_attributes
  end

  def self.ransackable_associations(auth_object = nil)
    authorizable_ransackable_associations
  end
end

Think before doing this in an application that exposes search params to users: it makes encrypted_password, reset_token and every other column searchable. They are also a convenient base for an exclusion list: authorizable_ransackable_attributes - %w[encrypted_password].

For models that inherit from ActiveRecord::Base directly (some gems define their own), put the two methods in a module and extend every model with it from an initializer: ActiveSupport.on_load(:active_record) { extend TheModule }.

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
      # allow all attributes for admin
      column_names + _ransackers.keys
    else
      # allow only the title and body attributes for other users
      %w(title body)
    end
  end

  private_class_method :ransackable_attributes
end

The allowlists may be given as strings or as symbols — %w[title body] and %i[title body] behave identically.

Before Ransack 5.0 a symbol allowlist was compared against strings without normalising, so %i[title body] matched nothing and every search on those attributes was silently ignored. See #1538. 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 allow/block various elements in Ransack.

Searching Action Text

A rich text attribute is an ordinary has_one association to ActionText::RichText, so it is searched like any association once both sides are allowlisted:

# config/initializers/ransack.rb
ActiveSupport.on_load(:action_text_rich_text) do
  def self.ransackable_attributes(auth_object = nil)
    %w[body]
  end
end

class Post < ApplicationRecord
  has_rich_text :content

  def self.ransackable_associations(auth_object = nil)
    %w[rich_text_content]
  end
end

Post.ransack(rich_text_content_body_cont: 'hello')

The body is stored as HTML, so tag names and attributes match too. Keep a plain-text column alongside if that matters.

Encrypted attributes

A column declared with encrypts :email, deterministic: true can be searched with the equality predicates (eq, not_eq, in, not_in): Ransack casts the value through the attribute type, so Active Record encrypts it before the comparison. The LIKE predicates (cont, start, end and the i_ forms) cannot match part of a ciphertext, and a non-deterministic column cannot be searched at all. Neither is something Ransack can change.

Handling unknown predicates or attributes

By default, Ransack will ignore any unknown predicates or attributes:

Article.ransack(unknown_attr_eq: 'Ernie').result.to_sql
=> SELECT "articles".* FROM "articles"

Ransack may be configured to raise an error if passed an unknown predicate or attributes, by setting the ignore_unknown_conditions option to false in your Ransack initializer file at config/initializers/ransack.rb:

Ransack.configure do |c|
  # Raise errors if a query contains an unknown predicate or attribute.
  # Default is true (do not raise error on unknown conditions).
  c.ignore_unknown_conditions = false
end

Article.ransack(unknown_attr_eq: 'Ernie')
# Ransack::InvalidSearchError (Invalid search term unknown_attr_eq)

As an alternative to setting a global configuration option, the .ransack! class method also raises an error if passed an unknown condition:

Article.ransack!(unknown_attr_eq: 'Ernie')
# Ransack::InvalidSearchError: Invalid search term unknown_attr_eq

This is equivalent to the ignore_unknown_conditions configuration option, except it may be applied on a case-by-case basis.

Using Scopes/Class Methods

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
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 :smiley:

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 self.ransackable_scopes_skip_sanitize_args
  [:scope_to_skip_sanitize_args]
end

Scopes and false

A bare false (or '0' / 'false', which are sanitized to false) is taken to mean “this checkbox was not ticked”, and the scope is not applied at all. That is right for a scope with no argument, but wrong for a scope such as activated(boolean) driven by a yes / no / any select, which needs to receive false. List that scope in ransackable_scopes_skip_sanitize_args: it then receives every value as given, including false, and can cast for itself:

class Employee < ActiveRecord::Base
  # `true` is passed as a bare call, so the argument needs a default.
  scope :activated, ->(value = true) { where(active: ActiveModel::Type::Boolean.new.cast(value)) }

  def self.ransackable_scopes(auth_object = nil)
    %i(activated)
  end

  def self.ransackable_scopes_skip_sanitize_args
    %i(activated)
  end
end

Employee.ransack(activated: false).result   # WHERE "employees"."active" = FALSE
Employee.ransack(activated: '0').result     # the same, from a form

Wrapping the value in an array (activated: [false]) has always passed it through and still does.

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!

Scopes are always ANDed

A scope is applied by chaining it onto the relation, outside the condition tree that m: 'or' and groupings govern, so it is always ANDed with the rest of the search:

Person.ransack(active: true, name_cont: 'foo', m: 'or').result.to_sql
# ... WHERE (active = 1) AND "people"."name" LIKE '%foo%' ESCAPE '\'

For something that must take part in an OR, use a ransacker or a custom predicate instead of a scope.

Grouping queries by OR instead of AND

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\" LIKE '%foo%'
    OR \"artists\".\"style\" LIKE '%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\" LIKE '%foo%'
    OR \"musicians\".\"email\" LIKE '%bar%'))"

Using SimpleForm

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'