Merge pull request rails#42061 from kddnewton/ar-in-order-of

Add `ActiveRecord::QueryMethods#in_order_of`.

Author: kaspth

activerecord/CHANGELOG.md

@@ -1,3 +1,29 @@
+*   Add `ActiveRecord::QueryMethods#in_order_of`.
+
+    This allows you to specify an explicit order that you'd like records
+    returned in based on a SQL expression. By default, this will be accomplished
+    using a case statement, as in:
+
+    ```ruby
+    Post.in_order_of(:id, [3, 5, 1])
+    ```
+
+    will generate the SQL:
+
+    ```sql
+    SELECT "posts".* FROM "posts" ORDER BY CASE "posts"."id" WHEN 3 THEN 1 WHEN 5 THEN 2 WHEN 1 THEN 3 ELSE 4 END ASC
+    ```
+
+    However, because this functionality is built into MySQL in the form of the
+    `FIELD` function, that connection adapter will generate the following SQL
+    instead:
+
+    ```sql
+    SELECT "posts".* FROM "posts" ORDER BY FIELD("posts"."id", 1, 5, 3) DESC
+    ```
+
+    *Kevin Newton*
+
 *   Fix `eager_loading?` when ordering with `Symbol`
 
     `eager_loading?` is triggered correctly when using `order` with symbols.
@@ -34,7 +60,7 @@
 
     *Luis Vasconcellos*, *Eileen M. Uchitelle*
 
-*   Fix `eager_loading?` when ordering with `Hash` syntax.
+*   Fix `eager_loading?` when ordering with `Hash` syntax
 
     `eager_loading?` is triggered correctly when using `order` with hash syntax
     on an outer table.

activerecord/lib/active_record/connection_adapters/abstract_adapter.rb

@@ -632,6 +632,15 @@ def database_version # :nodoc:
       def check_version # :nodoc:
       end
 
+      def field_ordered_value(column, values)
+        node = Arel::Nodes::Case.new(column)
+        values.each.with_index(1) do |value, order|
+          node.when(value).then(order)
+        end
+
+        Arel::Nodes::Ascending.new(node.else(values.length + 1))
+      end
+
       class << self
         private
           def initialize_type_map(m)

activerecord/lib/active_record/connection_adapters/abstract_mysql_adapter.rb

@@ -137,6 +137,11 @@ def supports_insert_on_duplicate_update?
         true
       end
 
+      def field_ordered_value(column, values)
+        field = Arel::Nodes::NamedFunction.new("FIELD", [column, values.reverse])
+        Arel::Nodes::Descending.new(field)
+      end
+
       def get_advisory_lock(lock_name, timeout = 0) # :nodoc:
         query_value("SELECT GET_LOCK(#{quote(lock_name.to_s)}, #{timeout})") == 1
       end

activerecord/lib/active_record/querying.rb

@@ -12,7 +12,7 @@ module Querying
       :create_or_find_by, :create_or_find_by!,
       :destroy_all, :delete_all, :update_all, :touch_all, :destroy_by, :delete_by,
       :find_each, :find_in_batches, :in_batches,
-      :select, :reselect, :order, :reorder, :group, :limit, :offset, :joins, :left_joins, :left_outer_joins,
+      :select, :reselect, :order, :in_order_of, :reorder, :group, :limit, :offset, :joins, :left_joins, :left_outer_joins,
       :where, :rewhere, :invert_where, :preload, :extract_associated, :eager_load, :includes, :from, :lock, :readonly,
       :and, :or, :annotate, :optimizer_hints, :extending,
       :having, :create_with, :distinct, :references, :none, :unscope, :merge, :except, :only,

activerecord/lib/active_record/relation/query_methods.rb

@@ -387,6 +387,23 @@ def order!(*args) # :nodoc:
       self
     end
 
+    # Allows to specify an order by a specific set of values. Depending on your
+    # adapter this will either use a CASE statement or a built-in function.
+    #
+    #   User.in_order_of(:id, [1, 5, 3])
+    #   # SELECT "users".* FROM "users" ORDER BY FIELD("users"."id", 1, 5, 3)
+    #
+    def in_order_of(column, values)
+      klass.disallow_raw_sql!([column], permit: connection.column_name_with_order_matcher)
+
+      references = column_references([column])
+      self.references_values |= references unless references.empty?
+
+      column = order_column(column.to_s) if column.is_a?(Symbol)
+
+      spawn.order!(connection.field_ordered_value(column, values))
+    end
+
     # Replaces any existing order defined on the relation with the specified order.
     #
     #   User.order('email DESC').reorder('id ASC') # generated SQL has 'ORDER BY id ASC'

activerecord/test/cases/relation/field_ordered_values_test.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "cases/helper"
+require "models/post"
+
+class FieldOrderedValuesTest < ActiveRecord::TestCase
+  fixtures :posts
+
+  def test_in_order_of
+    order = [3, 4, 1]
+    posts = Post.in_order_of(:id, order).limit(3)
+
+    assert_equal(order, posts.map(&:id))
+  end
+
+  def test_in_order_of_expression
+    order = [3, 4, 1]
+    posts = Post.in_order_of(Arel.sql("id * 2"), order.map { |id| id * 2 }).limit(3)
+
+    assert_equal(order, posts.map(&:id))
+  end
+
+  def test_in_order_of_after_regular_order
+    order = [3, 4, 1]
+    posts = Post.where(type: "Post").order(:type).in_order_of(:id, order).limit(3)
+
+    assert_equal(order, posts.map(&:id))
+  end
+end