A long-lived project that still receives updates
Scoped search makes it easy to search your ActiveRecord-based models. It will create a named scope :search_for that can be called with a query string. It will build an SQL query using the provided query string and a definition that specifies on what fields to search. Because the functionality is built on named_scope, the result of the search_for call can be used like any other named_scope, so it can be chained with another scope or combined with will_paginate. Because it uses standard SQL, it does not require any setup, indexers or daemons. This makes scoped_search suitable to quickly add basic search functionality to your application with little hassle. On the other hand, it may not be the best choice if it is going to be used on very large datasets or by a large user base.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
 Project Readme

Scoped search ¶ ↑

The scoped_search gem makes it easy to search your ActiveRecord models. Searching is performed using a query string, which should be passed to the named_scope search_for. Based on a definition in what fields to look, it will build query conditions and return those as a named scope.

Scoped search is great if you want to offer a simple yet powerful search box to your users and build a query based on the search string they enter. It comes with a built-in search syntax auto-completer and a value auto-completer. It also comes with a set of helpers that makes it easy to create a clean web UI with sorting and an ajax auto-completer.

Preview¶ ↑

A demo application using the scoped search can be found here: github.com/abenari/scoped_search_demo_app A running version of the demo application can be found here: scope-search-demo.heroku.com A Rails 3.2 demo with assets pipeline and twitter bootstrap: theme github.com/abenari/search-demo2

Installing¶ ↑

Add the following line in your Gemfile, and run bundle install:

gem "scoped_search"

Scoped search 4.x supports Rails 4.2 to 5.0, with Ruby 2.0.0 or higher. Use previous versions, e.g. 3.x to support older versions of Rails or Ruby.

Usage¶ ↑

Scoped search requires you to define the fields you want to search in:

class User < ActiveRecord::Base
  scoped_search on: [:first_name, :last_name]
end

For more information about options and using fields from relations, see the project wiki on search definitions: github.com/wvanbergen/scoped_search/wiki/search-definition

Now, the search_for scope is available for queries. You should pass a query string to the scope. This can be empty or nil, in which case all no search conditions are set (and all records will be returned).

User.search_for('my search string').each { |user| ... }

The result is returned as named_scope. Because of this, you can actually chain the call with other scopes, or with will_paginate. An example:

class Project < ActiveRecord::Base
  scoped_search on: [:name, :description]
  named_scope :public, conditions: { public: true }
end

# using chained named_scopes and will_paginate in your controller
Project.public.search_for(params[:q]).paginate(page: params[:page], include: :tasks)

Search profiles¶ ↑

If you include a :profile option to the scoped_search call, the fields specified will only be searched when you include this :profile into the search_for command as well:

class User < ActiveRecord::Base
  scoped_search on: :public_information
  scoped_search on: :private_information, profile: :members
end

This will only search the :public_information column:

User.search_for('blah blah blah')

And this will only search the :private_information column:

User.search_for('blah blah blah', profile: :members)

More information¶ ↑

More information about usage can be found in the project wiki: github.com/wvanbergen/scoped_search/wiki/usage

Query language¶ ↑

The search query language is simple, but supports several constructs to support more complex queries:

words

require every word to be present, e.g.: some search keywords

phrases

use quotes for multi-word phrases, e.g. "police car"

negation

look for “everything but”, e.g. police -uniform, -"police car", police NOT car

logical keywords

make logical constructs using AND, OR, &&, ||, &, | operators, e.g. uniform OR car, scoped && search

parentheses

to structure logic e.g. "police AND (uniform OR car)"

comparison operators

to search in numerical or temporal fields, e.g. > 22, < 2009-01-01

explicit fields

search only in the given field. e.g. username = root, created_at > 2009-01-01

NULL checks

using the set? and null? operator with a field name, e.g. null? graduated_at, set? parent_id

A complex query example to look for Ruby on Rails programmers without cobol experience, over 18 years old, with a recently updated record and a non-lame nickname:

("Ruby" OR "Rails") -cobol, age >= 18, updated_at > 2009-01-01 && nickname !~ l33t

For more info, see the the project wiki: github.com/wvanbergen/scoped_search/wiki/query-language

Additional resources¶ ↑

License¶ ↑

This plugin is released under the MIT license (see LICENSE).

This plugin was originally developed for Floorplanner.com by Willem van Bergen (github.com/wvanbergen) with help from Wes Hays (github.com/weshays). The current maintainer is Amos Benari (github.com/abenari).