left_join_arel_example.rb

# Here's a contrived example of a LEFT JOIN using ARel. This is an example of
# the mechanics, not a real-world use case.

# == DEFINITIONS
# - A Taxi is a car for hire. A taxi has_many :passengers.
# - A Passenger records one person riding in one taxi one time. It belongs_to :taxi.

class Taxi < ActiveRecord::Base
  # This scope LEFT JOINs the Passenger table. You might use this if you wanted
  # to select taxis by a set of taxi and passenger IDs (as with the
  # SQL "taxis.id IN () OR passengers.id IN ()").
  def left_join_passengers
    taxis = Taxi.arel_table
    passengers = Passenger.arel_table

    # The key here is providing the join type (Arel::Nodes::OuterJoin) and
    # grabbing the ARel join object itself from Arel::SelectManager#join_sources
    # to feed to ActiveRecord's #joins method.
    # SQL equivalent: "LEFT OUTER JOIN passengers ON taxis.id = passengers.taxi_id"
    taxi_passengers = taxis.join(passengers, Arel::Nodes::OuterJoin).
                            on(taxis[:id].eq(passengers[:taxi_id])).
                            join_sources
    joins(taxi_passengers)
  end
end

# Sources that almost documented this:
# http://blog.donwilson.net/2011/11/constructing-a-less-than-simple-query-with-rails-and-arel/