🔍 Object-oriented query building for ActiveRecord.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin init Nov 17, 2013
gemfiles i think this will work on CircleCI Sep 18, 2016
lib release 2.0.0 Sep 20, 2016
script i think this will work on CircleCI Sep 18, 2016
spec add appraisals and fix deprecation errors Sep 18, 2016
.gitignore update gemspec & don't check-in Gemfile.lock Mar 13, 2014
.rspec some basic specs Nov 17, 2013
.ruby-version bump ruby version Sep 18, 2016
Appraisals add appraisals and fix deprecation errors Sep 18, 2016
Gemfile i think this will work on CircleCI Sep 18, 2016
Guardfile fix guardfile Nov 25, 2014
README.md fix circleci badge url Sep 18, 2016
Rakefile re-add rakefile Dec 3, 2014
circle.yml random cleanup Dec 3, 2014
filterer.gemspec i think this will work on CircleCI Sep 18, 2016
filterer.sublime-project allow overriding per_page limit Mar 4, 2014


Filterer status coverage codeclimate gem

Filterer lets your users easily filter results from your ActiveRecord models. What does that mean? Let's imagine a page in your application that lists the results of Person.all:

Name              Email           Admin?
----              ----            ----
Adam Becker       foo@bar.com     true
Barack Obama      bo@wh.gov       false
Joe Biden         joe@biden.com   true

What if you want to let your users filter the results by name? Or email? Or whether or not the Person is an admin? Where does that logic go?

One answer could be your controller. You could progressively build up a query, like so:

@results = Person.all
@results = @results.where(name: params[:name]) if params[:name].present?
@results = @results.where(email: params[:email]) if params[:email].present?
@results = @results.where(admin: true) if params[:admin].present?

But you can see how that could get ugly fast. Especially when you add in sorting and pagination.

Another answer could be in your models. But passing a bunch of query parameters to a model isn't really a good practice either.

Enter Filterer.

Using Filterer

First, add gem 'filterer' to your Gemfile.

Next, you create a Filterer that looks like this:

# app/filterers/person_filterer.rb

class PersonFilterer < Filterer::Base
  def param_name(x)
    results.where(name: x)

  def param_email(x)
    results.where('LOWER(email) = ?', x)

  def param_admin(x)
    results.where(admin: true)

  # Optional default params
  def defaults
      direction: 'desc'

  # Optional default filters
  def apply_default_filters
    results.where('deleted_at IS NULL')

And in your controller:

class PeopleController < ApplicationController
  def index
    @people = Person.filter(params)

Now, when a user visits /people, they'll see Adam, Barack, and Joe, all three people. But when they visit /people?name=Adam%20Becker, they'll see only Adam. Or when they visit /people?admin=t, they'll see only Adam and Joe.

Specifying the Filterer class to use

Filterer includes a lightweight ActiveRecord adapter that allows us to call filter on any ActiveRecord::Relation like in the example above. By default, it will look for a class named [ModelName]Filterer. If you wish to override this, you have a couple of options:

You can pass a :filterer_class option to the call to filter:

Person.filter(params, filterer_class: 'AdvancedPersonFilterer')

Or you can bypass the ActiveRecord adapter altogether:

AdvancedPersonFilterer.filter(params, starting_query: Person.all)


Filterer relies on either Kaminari or will_paginate for pagination. You must install one of them if you want to paginate your records.

If you have either of the above gems installed, Filterer will automatically paginate your records, fetching the correct page for the ?page=X URL parameter. By default, filterer will display 20 records per page.

Overriding per_page

class PersonFilterer < Filterer::Base
  self.per_page = 30 # defaults to 20

Allowing the user to override per_page

class PersonFilterer < Filterer::Base
  self.per_page = 20
  self.allow_per_page_override = true

Now you can append ?per_page=50 to the URL.

Note: To prevent abuse, this value will still max-out at 1000 records per page.

Disabling pagination

class NoPaginationFilterer < PersonFilterer
  self.per_page = nil


Person.filter(params, skip_pagination: true)

Sorting the results

Filterer provides a slightly different DSL for sorting your results. Here's a quick overview of the different ways to use it:

class PersonFilterer < Filterer::Base
  # '?sort=name' will order by LOWER(people.name). If there is no sort parameter,
  # we'll default to this anyway.
  sort_option 'name', 'LOWER(people.name)', default: true

  # '?sort=id' will order by id. This is used as a tiebreaker, so if two records
  # have the same name, the one with the lowest id will come first.
  sort_option 'id', tiebreaker: true

  # '?sort=occupation' will order by occupation, with NULLS LAST.
  sort_option 'occupation', nulls_last: true

  # '?sort=data1', '?sort=data2', etc. will call the following proc, passing the
  # match data. It returns a string that gets passed to the ORDER BY clause.
  sort_option Regexp.new('data([0-9]+)'), -> (matches) {
    "(ratings -> '#{matches[1]}')"

Since paginating records without an explicit ORDER BY clause is a no-no, Filterer orders by [table_name].id asc if no sort options are provided.

Disabling the ordering of results

For certain queries, you might want to bypass the ordering of results:

Person.filter(params, skip_ordering: true)

Passing arbitrary data to the Filterer

class OrganizationFilterer < Filterer::Base
  def starting_query
    if opts[:is_admin]

OrganizationFilterer.filter(params, is_admin: current_user.admin?)