How to implement Query Object pattern in Ruby on Rails?

In simple terms, Query Object allows you to encapsulate complex database queries.

Why do we need it and what problems can this pattern solve?

Sometimes we have very complex queries that are used directly in the business logic. For example, the following query can be used many times in different controllers and service objects:

def index
  seasons = Season.joins(league: :country).where("countries.name = 'England'")

  render json: seasons
end

What problem does this create for us?

• It's impossible to test separately from the controller.
• It's very difficult to stub/mock db request
• It's not DRY
• It's not clear, hard to read and understand what's going on.

So what can we do to fix it?

• We can try to move this logic to the model level.
• We can try to create a Query Object and move that logic there.

If we decide to choose the first option and use a model, there are 2 ways to implement this:

Class methods

# frozen_string_literal: true

class Season < ApplicationRecord

  def self.by_league(league)
    where(league: league)
  end

  def self.by_status(status)
    where(status: status)
  end

end

Season.by_league(league)
Season.by_status(status)

Scope

class Season < ApplicationRecord

  scope :by_league, -> (league) { where(league: league) }
  scope :by_status, -> (status) { where(status: status) }

end

Season.by_league(league)
Season.by_status(status)

The interface looks good, but we still have some problems. The most important one is the violation of Single responsibility principle. The model becomes too big and fat. We can get more than 100 methods in a year. So it will be very difficult to read, change, and maintain. It would be nice to have the same interface, but move that logic into a separate class.

How can we do that?

The Query Object pattern was created to solve this problem.

Let's start with the simplest Query Object.

# app/units/queries/season.rb

module Queries
  class Season

    class << self
      def by_league(league)
        ::Season.where(league: league)
      end

      def by_status(status)
        ::Season.where(status: status)
      end
    end

  end
end

Queries::Season.by_league(league)
Queries::Season.by_status(status)

Interface looks fine, but there's one important problem - methods are not chainable and we have to repeat ::Season prefix every time. For example, if you want to write something like this Queries::Season.by_league(league).by_status(status), it won't work.

So, how can we fix it?

Rails has an interesting method - extending. This method allows you to add any methods on the model and chain them. For example, the following works fine.

module Scopes
  def by_league(league)
    where(league: league)
  end

  def by_status(status)
    where(status: status)
  end
end

query = Season.all.extending(Scopes)
query.by_league(league).by_status(status)

So now we need to somehow delegate methods from Queries::Season to Season.all.extending(Scopes). How can we do this?
Rails provides a method delegate_missing_to
So we can simply delegate all methods to be called on Queries::Season to Season.all.extending(Scopes).

# frozen_string_literal: true

module Queries
  class Season

    module Scopes
      def by_league(league)
        where(league: league)
      end

      def by_status(status)
        where(status: status)
      end
    end

    class << self
      delegate_missing_to :relation

      def relation
        ::Season.all.extending(Scopes)
      end
    end

  end
end

Queries::Season.by_league(league).by_status(status)

So now all methods are chainable. The last problem we can solve is that the code is NOT DRY, and we don't want to repeat the following every time:

class << self
  delegate_missing_to :relation

  def relation
    ::Season.all.extending(Scopes)
  end
end

Let's create a parent class Query and move the common logic there.

# lib/query.rb

class Query

  class << self

    attr_reader :model

    def set_model(model)
      @model = model
    end

    delegate_missing_to :relation

    private

    def relation
      model.all.extending(self::Scopes)
    end

  end

end

And let's inherit from this class:

# app/units/queries/season.rb

module Queries
  class Season < Query

    set_model ::Season

    module Scopes
      def by_league(league)
        where(league: league)
      end

      def by_status(status)
        where(status: status)
      end
    end

  end
end

Queries::Season.by_league(league).by_status(status)

So the final solution may look as follows:

def index
  seasons = Queries::Season.by_country('England')

  render json: seasons
end

Conclusion:

• Query Object can be easily tested separately from the controller
• Query Object can be easily stub/mocked

allow(Queries::Season).to receive(:by_country).with('England').and_return(...)

• Query Object is DRY and reusable
• The code is clear, easy to read and understand
• Query Object is separated from the model and allows us to avoid FAT model