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

> Understand Ransack simple mode vs advanced mode. Learn how flat parameters and GET requests differ from nested queries and POST requests to optimize your search functionality.

- Repository: [ActiveRecord Hackery/ransack](https://github.com/activerecord-hackery/ransack)
- Tags: deep-dive
- Published: 2026-02-23

---

**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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/docs/docs/getting-started/simple-mode.md) and [`docs/docs/getting-started/advanced-mode.md`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/app/controllers/people_controller.rb):

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

```

In your view:

```erb
<%= 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:

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

```

### Advanced Mode Setup (Nested Groupings)

In [`config/routes.rb`](https://github.com/activerecord-hackery/ransack/blob/main/config/routes.rb):

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

```

In [`app/controllers/people_controller.rb`](https://github.com/activerecord-hackery/ransack/blob/main/app/controllers/people_controller.rb):

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

```

In your view:

```erb
<%= 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:

```sql
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`](https://github.com/activerecord-hackery/ransack/blob/main/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`](https://github.com/activerecord-hackery/ransack/blob/main/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.