This document provides a high-level overview of Ransack, its architecture, and how it integrates with Ruby on Rails applications. It covers the purpose of the library, its main components, and the overall system design.
For detailed information about specific topics:
Ransack is an object-based searching library for ActiveRecord applications. It transforms user search parameters from web forms into SQL queries without requiring additional infrastructure like Elasticsearch or Solr. The library operates as a middleware layer between Rails controllers/views and the database, translating search conditions into Arel Abstract Syntax Trees that compile to SQL.
Sources: README.md8-16
| Component | Versions |
|---|---|
| Rails | 8.1, 8.0, 7.2 |
| Ruby | 3.1+ |
| Databases | PostgreSQL, MySQL, SQLite, SQL Server, PostGIS |
The library has no external dependencies beyond Rails and works entirely with standard Ruby and ActiveRecord.
Sources: README.md16 CHANGELOG.md7-12
Diagram: Main Ransack Components and File Locations
The architecture consists of four primary layers:
#ransack method on ActiveRecord models and the search_form_for view helperSearch coordinates the query, Context builds database queries, and Configuration manages global settingsCondition), logical groupings (Grouping), and sorting (Sort)Sources: lib/ransack.rb1-34 lib/ransack/search.rb lib/ransack/context.rb lib/ransack/adapters/active_record/base.rb lib/ransack/helpers/form_helper.rb
Diagram: How Ransack Extends Rails
Ransack integrates with Rails through ActiveSupport.on_load hooks that execute when Rails components are loaded:
ActiveRecord::Base with the Adapters::ActiveRecord::Base module, adding the #ransack and #ransack! methods plus security configuration methodsHelpers::FormHelper in ActionController::Base, making view helpers available in all controllers and viewsSources: lib/ransack/active_record.rb1-15 lib/ransack.rb30-33 lib/ransack/adapters/active_record/base.rb
Diagram: Search Query Processing Sequence
The request flow has two distinct phases:
Initialization Phase: The controller calls Model.ransack(params[:q]), which creates a Ransack::Search object. This parses parameters, builds the node tree (Grouping, Condition, Sort nodes), and validates all attributes against the model's ransackable_* allowlists.
Evaluation Phase: When @q.result is called, the Search delegates to Context#evaluate, which converts the node tree into an ActiveRecord::Relation. The relation is lazy-evaluated—SQL only executes when the results are enumerated in the view.
Sources: lib/ransack/search.rb lib/ransack/adapters/active_record/context.rb
Ransack implements security through explicit allowlisting at the model level. As of version 4.0.0, all searchable attributes, associations, and scopes must be explicitly declared:
| Method | Purpose | Required Since |
|---|---|---|
ransackable_attributes | Whitelist searchable columns | v4.0.0 |
ransackable_associations | Whitelist joinable relations | v4.0.0 |
ransackable_scopes | Whitelist callable scopes | Always optional |
This breaking change prevents unauthorized access to model attributes and associations. Without explicit allowlisting, attempting to search on an attribute raises Ransack::InvalidSearchError.
Sources: CHANGELOG.md59-66 README.md42-46
The main entry point lib/ransack.rb1-34 performs these initialization tasks:
active_support, polyamorous)Configuration moduleSearch, Context, Ransacker)ActiveSupport.on_loadThe predicate system is configured in lib/ransack.rb14-21 where AREL_PREDICATES and DERIVED_PREDICATES constants define all available search operators (see Predicates for details).
Sources: lib/ransack.rb1-34 lib/ransack/configuration.rb
Current version: 4.4.1 lib/ransack/version.rb2
Major version history:
Sources: lib/ransack/version.rb1-3 CHANGELOG.md1-1177
To learn more about specific aspects of Ransack:
