Ransack Simple Mode vs Advanced Mode: Key Differences and When to Use Each

Ransack's simple mode uses flat parameters for basic AND-only queries via GET requests, while advanced mode supports nested groupings with complex Boolean logic through POST requests and structured parameter hashes.

Ransack is a powerful search library for Ruby on Rails applications maintained by the activerecord-hackery organization. Understanding the differences between Ransack's simple mode and advanced mode is essential for implementing search functionality that matches your application's complexity requirements. While both modes leverage the same core Ransack::Search engine, they differ fundamentally in parameter handling, Boolean logic support, and typical request workflows.

Parameter Structure and Query Syntax

The most immediate difference between Ransack simple mode vs advanced mode lies in how search parameters are structured and transmitted.

Simple mode employs a flat parameter structure where each key follows the attribute_predicate pattern. The controller receives params[:q] containing direct mappings like name_cont or email_end. According to the source code in lib/ransack/search.rb, these parameters are assigned directly to a single root Nodes::Grouping object without creating additional nested groups.

Advanced mode utilizes nested hashes with special control keys (g for groupings, c for conditions, m for combinators) to build arbitrarily deep logical trees. As implemented in lib/ransack/nodes/grouping.rb, the parser detects these grouping keys and constructs a hierarchical tree of Grouping objects that can contain other groupings and conditions, enabling complex query construction.

Boolean Logic and Grouping Capabilities

Simple mode automatically applies AND logic between all search conditions. When you submit multiple fields through a simple form, Ransack builds a flat SQL WHERE clause connecting every condition with AND operators. This approach works well for "find users named John with .org emails" scenarios but cannot express OR relationships between fields.

Advanced mode unlocks full Boolean algebra with explicit support for mixed AND/OR logic and grouped conditions. By using the f.grouping helper or manually constructing parameter hashes like g[0][c][0][name_cont], you can create SQL with proper parenthetical grouping. This allows queries such as "(name contains 'John' OR email contains 'John') AND created_at > 1.week.ago" that would be impossible in simple mode.

HTTP Methods and Request Handling

Simple mode is optimized for GET requests because the flat query string remains compact and bookmarkable. The short parameter structure fits comfortably within URL length limits, making it ideal for shareable search results and standard index actions.

Advanced mode typically requires POST requests due to the expanded parameter payload needed to describe nested logical trees. The nested hash structure (g[0][c][0]...) can quickly generate long query strings that exceed browser URL limits. The Ransack documentation recommends routing your search action to accept both GET and POST verbs when implementing advanced mode functionality.

Source Code Implementation

The distinction between modes is encoded in two critical files within the Ransack repository:

• lib/ransack/search.rb: Serves as the entry point that detects whether incoming parameters contain simple attribute keys or advanced grouping keys (g, c, m). The build method delegates to different parsing strategies based on this detection.

• lib/ransack/nodes/grouping.rb: Implements the tree structure essential to advanced mode. This file handles the groupings= and conditions= setters that construct the hierarchical condition trees, while simple mode bypasses this complexity by writing directly to the base grouping.

The documentation files docs/docs/getting-started/simple-mode.md and docs/docs/getting-started/advanced-mode.md provide user-facing examples that correspond to these implementation differences.

Practical Implementation Examples

Simple Mode Setup (Flat Parameters)

In app/controllers/people_controller.rb:

def index
  @q = Person.ransack(params[:q])
  @people = @q.result(distinct: true)
end

In your view:

<%= search_form_for @q do |f| %>
  <%= f.label :name_cont %>
  <%= f.search_field :name_cont %>

  <%= f.label :email_end %>
  <%= f.search_field :email_end %>

  <%= f.submit %>
<% end %>

This generates SQL equivalent to:

WHERE name ILIKE '%John%' AND email ILIKE '%org'

Advanced Mode Setup (Nested Groupings)

In config/routes.rb:

resources :people do
  collection do
    match 'search' => 'people#search', via: [:get, :post], as: :search
  end
end

In app/controllers/people_controller.rb:

def search
  @q = Person.ransack(params[:q])
  @people = @q.result
  render :index
end

In your view:

<%= search_form_for @q, url: search_people_path, html: { method: :post } do |f| %>
  <%= f.grouping do |g| %>
    <%= g.condition :name_cont, params[:name] %>
    <%= g.condition :email_cont, params[:email] %>
    <%= g.combinator :or %>
  <% end %>
  <%= f.condition :created_at_gt, 1.week.ago %>
  <%= f.submit %>
<% end %>

This produces SQL with proper parenthetical grouping:

WHERE (name ILIKE '%john%' OR email ILIKE '%john%')
  AND created_at > '2026-02-16'

Summary

• Simple mode uses flat params[:q] with attribute_predicate keys, supports only implicit AND logic, and works best with GET requests for straightforward searches.
• Advanced mode uses nested hashes with g, c, and m keys, supports complex Boolean trees with explicit AND/OR combinators, and typically requires POST requests to handle the larger parameter payload.
• Both modes utilize the Ransack::Search class, but advanced mode activates the tree-building logic in lib/ransack/nodes/grouping.rb to handle grouped conditions.
• Use simple mode for single-level searches where all criteria must be met, and advanced mode when users need to combine conditions with OR logic or complex groupings.

Frequently Asked Questions

Can I use advanced mode with GET requests?

While technically possible for simple advanced queries, it is not recommended. Advanced mode generates deeply nested parameter keys (such as q[g][0][c][0][name_cont]) that can quickly exceed URL length limits in browsers. The Ransack source code and documentation suggest using POST requests for advanced mode to avoid truncation issues with complex search trees.

How does Ransack distinguish between simple and advanced mode parameters?

The Ransack::Search class in lib/ransack/search.rb inspects the keys of params[:q]. If it detects grouping keys like g (groupings), c (conditions), or m (combinators), it delegates to the advanced parser in Nodes::Grouping. Otherwise, it treats each top-level key as a direct attribute predicate and assigns it to the base grouping using simple mode logic.

Can I mix simple and advanced mode in the same search?

No, a single Ransack::Search instance operates in one mode based on the parameter structure received. If you pass flat keys alongside grouped keys, the grouped keys trigger advanced mode parsing, while the flat keys would need to be wrapped in a grouping structure to be properly processed. For hybrid interfaces, you typically need to normalize parameters before passing them to ransack().

Which mode should I use for multi-field search forms?

Use simple mode if all fields should be combined with AND logic (e.g., "find records matching ALL criteria"). Use advanced mode if your interface allows users to choose between AND/OR operators, or if you need to group certain fields together (e.g., "search name OR email AND status equals active"). The decision depends entirely on whether your users need Boolean logic beyond simple conjunction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}