activerecord-refined 0.3.2 → 0.4.0

data/examples/expressions.rb

@@ -0,0 +1,87 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'active_record'
+require 'activerecord-refined'
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Migration.verbose = false
+
+class Setup < ActiveRecord::Migration[8.1]
+  def up
+    create_table(:line_items) {|t| t.string :sku; t.string :category; t.integer :price; t.integer :quantity }
+  end
+end
+Setup.new.up
+
+class LineItem < ActiveRecord::Base
+end
+
+LineItem.create!(sku: 'A-1', category: 'tools',  price: 1200, quantity: 2)
+LineItem.create!(sku: 'A-2', category: 'tools',  price: 300,  quantity: 5)
+LineItem.create!(sku: 'B-1', category: 'paper',  price: 80,   quantity: 10)
+LineItem.create!(sku: 'C-1', category: nil,      price: 50,   quantity: 1)
+
+def show(title, relation, rows = nil)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts rows.inspect unless rows.nil?
+  puts
+end
+
+# 1. Arithmetic.  Ruby puts + - * / above the comparison operators, so an
+#    expression groups the way it reads, without parentheses.
+show('arithmetic in a condition',
+  LineItem.where { :price * :quantity > 1000 },
+  LineItem.where { :price * :quantity > 1000 }.pluck(:sku))
+
+show('arithmetic in a select list, and aggregated',
+  LineItem.select { [:sku, (:price * :quantity).as(:subtotal)] },
+  LineItem.select { [:sku, (:price * :quantity).as(:subtotal)] }.
+    map {|i| [i.sku, i.subtotal] })
+
+show('an aggregate over an expression',
+  LineItem.select { sum(:price * :quantity).as(:total) },
+  LineItem.select { sum(:price * :quantity).as(:total) }.first.total)
+
+# 2. Aggregates.  count takes :* for COUNT(*) and distinct: true for
+#    COUNT(DISTINCT ...); the rest are sum, avg, min and max.
+show('COUNT(*) and COUNT(DISTINCT ...)',
+  LineItem.select { [count(:*).as(:rows), count(:category, distinct: true).as(:categories)] },
+  LineItem.select { [count(:*).as(:rows), count(:category, distinct: true).as(:categories)] }.
+    map {|i| [i.rows, i.categories] })
+
+# 3. Functions.  Seven scalar ones have methods of their own; fn reaches
+#    anything else, emitting the name as written.
+show('built-in functions and the fn escape hatch',
+  LineItem.
+    where { length(:sku) == 3 }.
+    select { [upper(:sku).as(:sku), coalesce(:category, 'unsorted').as(:category)] },
+  LineItem.
+    where { length(:sku) == 3 }.
+    select { [upper(:sku).as(:sku), coalesce(:category, 'unsorted').as(:category)] }.
+    map {|i| [i.sku, i.category] })
+
+show('fn, for a function without a method of its own',
+  LineItem.select { fn(:hex, :price).as(:hex_price) },
+  LineItem.select { fn(:hex, :price).as(:hex_price) }.map(&:hex_price))
+
+# 4. Ordering.  asc and desc take nulls_first / nulls_last.  MySQL has no
+#    such syntax, but Arel emulates it there, so the order is the same
+#    everywhere.
+show('NULLS LAST',
+  LineItem.order { [:category.asc.nulls_last, :sku.asc] },
+  LineItem.order { [:category.asc.nulls_last, :sku.asc] }.pluck(:category, :sku))
+
+# Aggregates and expressions can be ordered by, too.
+show('grouped, aggregated and ordered by the aggregate',
+  LineItem.
+    group { :category }.
+    having { count(:*) > 1 }.
+    order { sum(:price * :quantity).desc }.
+    select { [coalesce(:category, 'unsorted').as(:category), sum(:price * :quantity).as(:total)] },
+  LineItem.
+    group { :category }.
+    having { count(:*) > 1 }.
+    order { sum(:price * :quantity).desc }.
+    select { [coalesce(:category, 'unsorted').as(:category), sum(:price * :quantity).as(:total)] }.
+    map {|i| [i.category, i.total] })

data/examples/postgresql.rb

@@ -0,0 +1,105 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'active_record'
+require 'activerecord-refined'
+require 'etc'
+
+# The features here are PostgreSQL's, so unlike the other examples this one
+# needs a server.  It connects the way the test suite does: on 127.0.0.1 as
+# the current user with no password, overridable through DB_HOST, DB_USERNAME
+# and DB_PASSWORD.
+begin
+  ActiveRecord::Base.establish_connection(
+    adapter: 'postgresql',
+    host: ENV.fetch('DB_HOST', '127.0.0.1'),
+    username: ENV.fetch('DB_USERNAME') { Etc.getlogin },
+    password: ENV['DB_PASSWORD'],
+    database: ENV.fetch('DB_NAME', 'postgres'))
+  ActiveRecord::Base.lease_connection
+rescue StandardError => e
+  abort "needs a PostgreSQL server: #{e.message}"
+end
+
+ActiveRecord::Migration.verbose = false
+
+class Setup < ActiveRecord::Migration[8.1]
+  def up
+    create_table(:articles, force: true) do |t|
+      t.string :title
+      t.string :tags, array: true, default: []
+      t.integer :scores, array: true, default: []
+    end
+  end
+end
+Setup.new.up
+
+class Article < ActiveRecord::Base
+end
+
+Article.delete_all
+Article.create!(title: 'Refinements',  tags: %w[ruby lang],  scores: [5, 4])
+Article.create!(title: 'Rails 8',      tags: %w[ruby rails], scores: [5])
+Article.create!(title: 'Postgres CTEs', tags: %w[sql db],    scores: [3])
+Article.create!(title: '100% pure',    tags: ['100%', 'a,b'], scores: [])
+
+def show(title, relation, rows = nil)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts rows.inspect unless rows.nil?
+  puts
+end
+
+# 1. Array columns.  Each name carries the meaning of its Ruby namesake:
+#    member? is Enumerable's element test, superset? and subset? are Set's
+#    containment, and intersect? is Array's "any element in common".
+show('member? tests one element',
+  Article.where { :tags.member?('ruby') },
+  Article.where { :tags.member?('ruby') }.pluck(:title))
+
+show('superset? requires every element',
+  Article.where { :tags.superset?(%w[ruby rails]) },
+  Article.where { :tags.superset?(%w[ruby rails]) }.pluck(:title))
+
+show('subset? and intersect?',
+  Article.where { :tags.intersect?(%w[sql lang]) },
+  [
+    Article.where { :tags.subset?(%w[ruby lang extra]) }.pluck(:title),
+    Article.where { :tags.intersect?(%w[sql lang]) }.pluck(:title),
+  ])
+
+# The element is serialized into an array literal, so commas, quotes and %
+# are matched literally rather than parsed or treated as wildcards.
+show('elements are matched literally',
+  Article.where { :tags.member?('a,b') },
+  Article.where { :tags.member?('a,b') }.pluck(:title))
+
+# member? works on any element type; the literal is coerced to the column's.
+show('a numeric array',
+  Article.where { :scores.member?(4) },
+  Article.where { :scores.member?(4) }.pluck(:title))
+
+# 2. Regular expressions.  =~ and !~ become ~ and !~ here, REGEXP on MySQL.
+#    SQLite has no regexp operator, which is why this example is not one of
+#    the portable ones.
+show('=~ matches a regular expression',
+  Article.where { :title =~ '^R' },
+  Article.where { :title =~ '^R' }.pluck(:title))
+
+show('a Regexp literal works too, and !~ negates',
+  Article.where { :title !~ /s$/ },
+  Article.where { :title !~ /s$/ }.pluck(:title))
+
+# 3. Case.  like? is case-sensitive LIKE everywhere, including here, where
+#    Arel would otherwise reach for ILIKE.  ilike? is the one that asks for
+#    it, and casecmp? is case-insensitive equality.
+show('like? stays case-sensitive; ilike? does not',
+  Article.where { :title.ilike?('r%') },
+  [
+    Article.where { :title.like?('r%') }.pluck(:title),
+    Article.where { :title.ilike?('r%') }.pluck(:title),
+  ])
+
+# 4. NULL as a value.  PostgreSQL spells this IS [NOT] DISTINCT FROM.
+show('null-safe comparison',
+  Article.where { :title.not_distinct_from?('Rails 8') },
+  Article.where { :title.not_distinct_from?('Rails 8') }.pluck(:title))

data/examples/predicates.rb

@@ -0,0 +1,93 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'active_record'
+require 'activerecord-refined'
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Migration.verbose = false
+
+class Setup < ActiveRecord::Migration[8.1]
+  def up
+    create_table(:accounts) {|t| t.string :login; t.string :country; t.integer :age }
+  end
+end
+Setup.new.up
+
+class Account < ActiveRecord::Base
+end
+
+Account.create!(login: 'matz',       country: 'JP', age: 60)
+Account.create!(login: 'nobu',       country: 'JP', age: 50)
+Account.create!(login: 'tenderlove', country: 'US', age: 45)
+Account.create!(login: '100%_pure',  country: nil,  age: 30)
+Account.create!(login: '1002000',    country: 'US', age: 25)
+
+def show(title, relation, rows)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts rows.inspect
+  puts
+end
+
+# 1. Ranges and sets.  in? is one name for "belongs to this set": a Range
+#    becomes BETWEEN, an endless Range a bare comparison, a list an IN.
+show('in? with a Range becomes BETWEEN',
+  Account.where { :age.in?(40..55) },
+  Account.where { :age.in?(40..55) }.pluck(:login))
+
+show('endless range and IN',
+  Account.where { :age.in?(50..) | :country.in?(%w[US]) },
+  Account.where { :age.in?(50..) | :country.in?(%w[US]) }.pluck(:login))
+
+# 2. NULL.  = NULL is never true in SQL, so == nil raises and the test is
+#    spelled null?.  not_distinct_from? is the null-safe equality, which is
+#    what to reach for when the value may or may not be nil.
+show('null? and its negation',
+  Account.where { :country.null? },
+  Account.where { :country.null? }.pluck(:login))
+
+wanted = nil
+show('not_distinct_from? matches NULL to nil',
+  Account.where { :country.not_distinct_from?(wanted) },
+  Account.where { :country.not_distinct_from?(wanted) }.pluck(:login))
+
+# Unlike !=, distinct_from? keeps the NULL row.
+show('distinct_from? keeps NULLs, != drops them',
+  Account.where { :country.distinct_from?('JP') },
+  [
+    Account.where { :country.distinct_from?('JP') }.pluck(:login),
+    Account.where { :country != 'JP' }.pluck(:login),
+  ])
+
+# 3. Text.  like? takes a pattern; start_with?, end_with? and include? take
+#    literals, so % and _ in them are escaped rather than matched as
+#    wildcards.  Note the last row matches only the literal-minded one.
+show('like? takes a pattern',
+  Account.where { :login.like?('%love') },
+  Account.where { :login.like?('%love') }.pluck(:login))
+
+show('start_with? takes any number of literals, like String#start_with?',
+  Account.where { :login.start_with?('ma', 'no') },
+  Account.where { :login.start_with?('ma', 'no') }.pluck(:login))
+
+# The % in the argument is escaped, so only the account whose login really
+# contains "100%" matches; the same pattern spelled with like? treats it as a
+# wildcard and catches 1002000 as well.
+show('include? escapes wildcards; like? does not',
+  Account.where { :login.include?('100%') },
+  [
+    Account.where { :login.include?('100%') }.pluck(:login),
+    Account.where { :login.like?('%100%%') }.pluck(:login),
+  ])
+
+# casecmp? folds both sides rather than trusting the collation, so it means
+# the same thing on every adapter.
+show('casecmp? is case-insensitive equality',
+  Account.where { :login.casecmp?('MaTz') },
+  Account.where { :login.casecmp?('MaTz') }.pluck(:login))
+
+# 4. Combining.  & | ! build the tree; Ruby's precedence puts & and | above
+#    the comparison operators, hence the parentheses around each comparison.
+show('compound conditions',
+  Account.where { (:age >= 40) & (:country.in?(%w[JP US]) | :country.null?) },
+  Account.where { (:age >= 40) & (:country.in?(%w[JP US]) | :country.null?) }.pluck(:login))

data/examples/subqueries.rb

@@ -0,0 +1,67 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'active_record'
+require 'activerecord-refined'
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+ActiveRecord::Migration.verbose = false
+
+class Setup < ActiveRecord::Migration[8.1]
+  def up
+    create_table(:authors) {|t| t.string :name }
+    create_table(:posts)   {|t| t.string :title; t.integer :author_id; t.integer :likes; t.boolean :published }
+  end
+end
+Setup.new.up
+
+class Author < ActiveRecord::Base
+  has_many :posts
+end
+
+class Post < ActiveRecord::Base
+  belongs_to :author
+
+  def self.published = where { :published == true }
+end
+
+matz  = Author.create!(name: 'matz')
+nobu  = Author.create!(name: 'nobu')
+quiet = Author.create!(name: 'quiet')
+
+Post.create!(title: 'refinements', author_id: matz.id, likes: 100, published: true)
+Post.create!(title: 'parser',      author_id: matz.id, likes: 40,  published: true)
+Post.create!(title: 'draft',       author_id: nobu.id, likes: 5,   published: false)
+
+def show(title, relation)
+  puts "--- #{title} ---"
+  puts relation.to_sql
+  puts relation.pluck(relation.model.table_name == 'authors' ? :name : :title).inspect
+  puts
+end
+
+# 1. in? takes a relation as a subquery.  With an explicit select list the
+#    subquery selects that column; without one it selects the primary key,
+#    the same way ActiveRecord's own where(id: relation) does.
+show('in? with a subquery',
+  Author.where { :id.in?(Post.published.select(:author_id)) })
+
+# 2. exists? asks whether the subquery returns a row.  Correlate it with the
+#    outer table through qualified columns; the inner where block is the same
+#    DSL as the outer one.
+show('exists?',
+  Author.where { exists?(Post.published.where { :posts[:author_id] == :authors[:id] }) })
+
+show('!exists? finds what has nothing to show',
+  Author.where { !exists?(Post.where { :posts[:author_id] == :authors[:id] }) })
+
+# 3. A relation on the right of a comparison is a scalar subquery.  It has to
+#    yield a single value, so unlike in? there is no default select list and
+#    one is required.
+show('a scalar subquery on the right of a comparison',
+  Post.where { :likes >= Post.select { avg(:likes) } })
+
+# The three compose like any other predicate.
+show('combined with the rest of the vocabulary',
+  Author.
+    where { exists?(Post.where { :posts[:author_id] == :authors[:id] }) }.
+    where { !:id.in?(Post.where { :published == false }.select(:author_id)) })