Query String Search

Provides an easy way to implement searching in your API endpoints.

Say you have a movies endpoint and people want to be able to search your huge collection of movie data. Each of your movies have these properties

• Rating: returns "PG", "R", etc. Can also return nil
• Year: returns the year the film was released
• Title: The movie's title
• Star Rating: returns a number 1 to 5
• Home Formats: returns an array of available home formats. ["DVD", "BD"], for example.

The API Search gem will give you the following search functionality:

Any of the above critera can be combined. Just separate criteria with commas. Records that match all the criteria will be returned. Some examples!

movie?q=year=1994,country=US,rated=none
All un-rated movies made in the US in 1994.

movie?q=home_formats=BD|DVD,rated=R|PG,star_rating>3
All movies available on BD or DVD, that are rated R or PG, and that have a star rating greater than 3

This gem fits best when you're trying to provide very flexible searching on a relatively small and flat set of data. Because it filters a data set that you provide, the speed at which it works is wholly dependent on the size of your data set.

We currently use this gem on a small (~2000 rows) data set which is cached in memory. Response times using Rails/Passenger/Apache are always under 100ms, usually under 50ms. That's plenty fast! But if your initial data set is massive, or you can't cache it, your response times will be slower. Such is life. Gems like Periscope or has_scope may be more your speed.

A downside of gems like those, though, is that you end up defining all of your filtering methods in advance. This is not the case with Query String Search. If the elements in your data set respond to a method, then the data can be filtered by the return value of that method. It is possible that this is not what you want. In which case, check out those other gems. Or, you could also wrap your object instances in a wrapper that only responds to the methods that you want to filter on.

Also, this gem is platform and persistence agnostic. Rails? Sinatra? Cuba? Redis? Postgres? Doesn't matter. You pass it objects, it filters them down based on the query string.

First, create a collection of data. With ActiveRecord or other ORMs this is straightforward:

Movie.all

Or something similar. As long as it returns a collection of objects, you should be good.

The objects must respond to the methods you want to search on. Say you want to allow a search string like this:

movies?q=year=1994

Then every object in your data collection needs to respond to year.

Second, search! In Rails you can do something like this in a Controller method.

def index
  query_string = params[:q]
  QueryStringSearch.new(Movie.all, query_string).results
  #....
end

This returns a collection of the objects that matched the search criteria.

Or you can do it not in the controller. This will work:

QueryStringSearch.new(Movie.all, "country=us").results

You get the idea. Pass in a data set and a query-stringish string and you'll get results back.

Add this line to your application's Gemfile:

gem 'query_string_search'

And then execute:

$ bundle

• Fork, branch, commit & pull.
• Tests are required.
• Don't go against our Rubocop style guidelines.

© Regents of the University of Minnesota. All rights reserved.