Ruby
Need help with order_as_specified?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.
panorama-ed

Description

Add arbitrary ordering to ActiveRecord queries.

213 Stars 22 Forks MIT License 81 Commits 0 Opened issues

Services available

Need anything else?

Code Coverage Build Status Inline docs Gem Version

OrderAsSpecified

OrderAsSpecified
adds the ability to query an
ActiveRecord
class for results from the database in an arbitrary order, without having to store anything extra in the database.

It's as easy as:

class TestObject
  extend OrderAsSpecified
end

TestObject.order_as_specified(language: ["es", "en", "fr"]) => #<:relation id: language:>, #, #, # ]> </:relation>

Is this like ranked-model?

Other gems like

ranked-model
,
acts_as_sortable
, etc. assume you want the same ordering each time, and store data to keep track of this in the database. They're great at what they do, but if you want to change the ordering, or if you don't always want an ordering, this gem is your friend.

Installation

Add this line to your application's Gemfile:

gem 'order_as_specified'

And then execute:

$ bundle

Or install it yourself as:

$ gem install order_as_specified

Usage

Basic usage is simple:

class TestObject
  extend OrderAsSpecified
end

TestObject.order_as_specified(language: ["es", "en", "fr"]) => #<:relation id: language:>, #, #, # ]> </:relation>

This returns all

TestObject
s in the given language order. Note that this ordering is not possible with a simple
ORDER BY
. Magic!

Like any other

ActiveRecord
relation, it can be chained:
TestObject.
  where(language: ["es", "en", "fr"]).
  order_as_specified(language: ["es", "en", "fr"]).
  limit(3)
=> #<:relation id: language:>,
     #,
     #
   ]>

We can use chaining in this way to order by multiple attributes as well:

TestObject.
  order_as_specified(language: ["es", "en"]).
  order_as_specified(id: [4, 3, 5]).
  order(:updated_at)
=> #<:relation first is language id: language: updated_at:>,

# Within the language, we order by :updated_at...
 #<testobject id: language: updated_at:>,

Then language "en"...

 #<testobject id: language: updated_at:>,

# Within the language, we order by :updated_at...
 #<testobject id: language: updated_at:>,

Then id 4...

 #<testobject id: language: updated_at:>,

Then id 3...

 #<testobject id: language: updated_at:>,

Then id 5...

 #<testobject id: language: updated_at:>,

Then we order by :updated_at...

 #<testobject id: language: updated_at:>,
 #<testobject id: language: updated_at:>,

]> </:relation>

We can also use this when we want to sort by an attribute in another model:

TestObject.
  joins(:other_object).
  order_as_specified(other_objects: { id: [other1.id, other3.id, other2.id] })

Neat, huh?

In all cases, results with attribute values not in the given list will be sorted as though the attribute is

NULL
in a typical
ORDER BY
:
TestObject.order_as_specified(language: ["fr", "es"])
=> #<:relation id: language:>,
     #,
     #,
     #
   ]>

Note that if a

nil
value is passed in the ordering an error is raised, because databases do not have good or consistent support for ordering with
NULL
values in an arbitrary order, so we don't permit this behavior instead of allowing an unexpected result.

distinct_on

In databases that support it (such as PostgreSQL), you can also use an option to add a

DISTINCT ON
to your query when you would otherwise have duplicates:
TestObject.order_as_specified(distinct_on: true, language: ["fr", "en"])
=> #<:relation id: language:>,
     #,
     #
   ]>

case_insensitive

If you want objects to come back in an order that is case-insensitive, you can pass the

case_insensitive: true
value to the
order_as_specified
call, as in:
TestObject.order_as_specified(case_insensitive: true, language: ["fr", "en"])
=> #<:relation language:>
     #
     #
     #
   ]>

Limitations

Databases may have limitations on the underlying number of fields you can have in an

ORDER BY
clause. For example, in PostgreSQL if you pass in more than 1664 list elements you'll receive this error:
PG::ProgramLimitExceeded: ERROR: target lists can have at most 1664 entries

That's a database limitation that this gem cannot avoid, unfortunately.

Documentation

We have documentation on RubyDoc.

Contributing

  1. Fork it (https://github.com/panorama-ed/orderasspecified/fork)
  2. Create your feature branch (
    git checkout -b my-new-feature
    )
  3. Commit your changes (
    git commit -am 'Add some feature'
    )
  4. Push to the branch (
    git push origin my-new-feature
    )
  5. Create a new Pull Request

Make sure your changes have appropriate tests (

bundle exec rspec
) and conform to the Rubocop style specified.

License

OrderAsSpecified
is released under the MIT License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.