Module: ROM::SQL::Relation::Reading

Included in:
ROM::SQL::Relation
Defined in:
lib/rom/sql/relation/reading.rb

Overview

Query API for SQL::Relation

Instance Method Summary collapse

Instance Method Details

#avg(*args) ⇒ Object

Returns a result of SQL AVG clause.

Examples:

users.avg(:age)

Parameters:

  • *args (Array<Symbol>) —

    A list with column names

Returns:

  • Number



269
270
271
 
# File 'lib/rom/sql/relation/reading.rb', line 269

def avg(*args)
  dataset.__send__(__method__, *args)
end

#count ⇒ Relation

Return relation count

Examples:

users.count
# => 12

Returns:



32
33
34
 
# File 'lib/rom/sql/relation/reading.rb', line 32

def count
  dataset.count
end

#distinct(*args, &block) ⇒ Relation

Returns a copy of the relation with a SQL DISTINCT clause.

Examples:

users.distinct(:country)

Parameters:

  • *args (Array<Symbol>) —

    A list with column names

Returns:



213
214
215
 
# File 'lib/rom/sql/relation/reading.rb', line 213

def distinct(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#exclude(*args, &block) ⇒ Relation

Restrict a relation to not match criteria

Examples:

users.exclude(name: 'Jane')

Parameters:

  • *args (Hash) —

    A hash with conditions for exclusion

Returns:



304
305
306
 
# File 'lib/rom/sql/relation/reading.rb', line 304

def exclude(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#fetch(pk) ⇒ Relation

Fetch a tuple identified by the pk

Examples:

users.fetch(1)
# {:id => 1, name: "Jane"}

Returns:

Raises:

  • (ROM::TupleCountMismatchError) —

    When 0 or more than 1 tuples were found



19
20
21
 
# File 'lib/rom/sql/relation/reading.rb', line 19

def fetch(pk)
  by_pk(pk).one!
end

#first ⇒ Hash

Get first tuple from the relation

Examples:

users.first
# {:id => 1, :name => "Jane"}

Returns:

  • (Hash) 


45
46
47
 
# File 'lib/rom/sql/relation/reading.rb', line 45

def first
  dataset.first
end

#group(*args, &block) ⇒ Relation

Group by specific columns

Examples:

tasks.group(:user_id)

Parameters:

  • *args (Array<Symbol>) —

    A list of column names

Returns:



439
440
441
 
# File 'lib/rom/sql/relation/reading.rb', line 439

def group(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#group_and_count(*args, &block) ⇒ Relation

Group by specific columns and count by group

Examples:

tasks.group_and_count(:user_id)
# => [{ user_id: 1, count: 2 }, { user_id: 2, count: 3 }]

Parameters:

  • *args (Array<Symbol>) —

    A list of column names

Returns:



454
455
456
 
# File 'lib/rom/sql/relation/reading.rb', line 454

def group_and_count(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#having(*args, &block) ⇒ Relation

Restrict a relation to match grouping criteria

Examples:

users.with_task_count.having( task_count: 2 )

users.with_task_count.having { task_count > 3 }

Parameters:

  • *args (Hash) —

    An optional hash with conditions for HAVING clause

Returns:

See Also:



322
323
324
 
# File 'lib/rom/sql/relation/reading.rb', line 322

def having(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#inner_join(*args, &block) ⇒ Relation

Join with another relation using INNER JOIN

Examples:

users.inner_join(:tasks, id: :user_id)

Parameters:

  • relation (Symbol) —

    name

  • join (Hash) —

    keys

Returns:



410
411
412
 
# File 'lib/rom/sql/relation/reading.rb', line 410

def inner_join(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#invert ⇒ Relation

Inverts the current WHERE and HAVING clauses. If there is neither a WHERE or HAVING clause, adds a WHERE clause that is always false.

Examples:

users.exclude(name: 'Jane').invert

# this is the same as:
users.where(name: 'Jane')

Returns:



338
339
340
 
# File 'lib/rom/sql/relation/reading.rb', line 338

def invert
  __new__(dataset.invert)
end

#last ⇒ Hash

Get last tuple from the relation

Examples:

users.last
# {:id => 2, :name => "Joe"}

Returns:

  • (Hash) 


58
59
60
 
# File 'lib/rom/sql/relation/reading.rb', line 58

def last
  dataset.last
end

#left_join(*args, &block) ⇒ Relation

Join other relation using LEFT OUTER JOIN

Examples:

users.left_join(:tasks, id: :user_id)

Parameters:

  • relation (Symbol) —

    name

  • join (Hash) —

    keys

Returns:



425
426
427
 
# File 'lib/rom/sql/relation/reading.rb', line 425

def left_join(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#limit(*args, &block) ⇒ Relation

Limit a relation to a specific number of tuples

Examples:

users.limit(1)

users.limit(10, 2)

Parameters:

  • limit (Integer) —

    The limit value

  • offset (Integer) —

    An optional offset

Returns:



381
382
383
 
# File 'lib/rom/sql/relation/reading.rb', line 381

def limit(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#map(key = nil, &block) ⇒ Object

Map tuples from the relation

Examples:

users.map { |user| user[:id] }
# [1, 2, 3]

users.map(:id).to_a
# [1, 2, 3]

Parameters:

  • key (Symbol) (defaults to: nil) —

    An optional name of the key for extracting values from tuples



121
122
123
124
125
126
127
 
# File 'lib/rom/sql/relation/reading.rb', line 121

def map(key = nil, &block)
  if key
    dataset.map(key, &block)
  else
    dataset.map(&block)
  end
end

#max(*args) ⇒ Object

Returns a result of SQL MAX clause.

Examples:

users.max(:age)

Parameters:

  • *args (Array<Symbol>) —

    A list with column names

Returns:

  • Number



255
256
257
 
# File 'lib/rom/sql/relation/reading.rb', line 255

def max(*args)
  dataset.__send__(__method__, *args)
end

#min(*args) ⇒ Object

Returns a result of SQL MIN clause.

Examples:

users.min(:age)

Parameters:

  • *args (Array<Symbol>) —

    A list with column names

Returns:

  • Number



241
242
243
 
# File 'lib/rom/sql/relation/reading.rb', line 241

def min(*args)
  dataset.__send__(__method__, *args)
end

#offset(*args, &block) ⇒ Relation

Set offset for the relation

Examples:

users.limit(10).offset(2)

Parameters:

  • num (Integer) —

    The offset value

Returns:



395
396
397
 
# File 'lib/rom/sql/relation/reading.rb', line 395

def offset(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#order(*args, &block) ⇒ Relation

Set order for the relation

Examples:

users.order(:name)

Parameters:

  • *args (Array<Symbol>) —

    A list with column names

Returns:



352
353
354
 
# File 'lib/rom/sql/relation/reading.rb', line 352

def order(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#pluck(name) ⇒ Array

Pluck values from a specific column

Examples:

users.pluck(:id)
# [1, 2, 3]

Returns:

  • (Array) 


138
139
140
 
# File 'lib/rom/sql/relation/reading.rb', line 138

def pluck(name)
  map(name)
end

#prefix(name = Inflector.singularize(table)) ⇒ Relation

Prefix all columns in a relation

This method is intended to be used internally within a relation object

Examples:

users.prefix(:user).to_a
# {:user_id => 1, :user_name => "Jane"}

Parameters:

  • name (Symbol) (defaults to: Inflector.singularize(table)) —

    The prefix

Returns:



75
76
77
 
# File 'lib/rom/sql/relation/reading.rb', line 75

def prefix(name = Inflector.singularize(table))
  rename(header.prefix(name).to_h)
end

#project(*names) ⇒ Relation

Project a relation

This method is intended to be used internally within a relation object

Examples:

users.project(:id, :name) }

Parameters:

  • *names (Symbol) —

    A list of symbol column names

Returns:



154
155
156
 
# File 'lib/rom/sql/relation/reading.rb', line 154

def project(*names)
  select(*header.project(*names))
end

#qualified ⇒ Relation

Qualifies all columns in a relation

This method is intended to be used internally within a relation object

Examples:

users.qualified

Returns:



89
90
91
 
# File 'lib/rom/sql/relation/reading.rb', line 89

def qualified
  select(*qualified_columns)
end

#qualified_columns ⇒ Array<Symbol>

Return a list of qualified column names

This method is intended to be used internally within a relation object

Examples:

users.qualified_columns
# [:users__id, :users__name]

Returns:

  • (Array<Symbol>) 


104
105
106
 
# File 'lib/rom/sql/relation/reading.rb', line 104

def qualified_columns
  header.qualified.to_a
end

#read(sql) ⇒ SQL::Relation

Return a new relation from a raw SQL string

Examples:

users.read('SELECT name FROM users')

Parameters:

  • sql (String) —

    The SQL string

Returns:



521
522
523
 
# File 'lib/rom/sql/relation/reading.rb', line 521

def read(sql)
  __new__(dataset.db[sql])
end

#rename(options) ⇒ Relation

Rename columns in a relation

This method is intended to be used internally within a relation object

Examples:

users.rename(name: :user_name).first
# {:id => 1, :user_name => "Jane" }

Parameters:

  • options (Hash<Symbol=>Symbol>) —

    A name => new_name map

Returns:



171
172
173
 
# File 'lib/rom/sql/relation/reading.rb', line 171

def rename(options)
  select(*header.rename(options))
end

#reverse(*args, &block) ⇒ Relation

Reverse the order of the relation

Examples:

users.order(:name).reverse

Returns:



364
365
366
 
# File 'lib/rom/sql/relation/reading.rb', line 364

def reverse(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#select(*args, &block) ⇒ Relation

Select specific columns for select clause

Examples:

users.select(:id, :name).first
# {:id => 1, :name => "Jane" }

Returns:



184
185
186
 
# File 'lib/rom/sql/relation/reading.rb', line 184

def select(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#select_append(*args, &block) ⇒ Relation

Append specific columns to select clause

Examples:

users.select(:id, :name).select_append(:email)
# {:id => 1, :name => "Jane", :email => "[email protected]"}

Parameters:

  • *args (Array<Symbol>) —

    A list with column names

Returns:



199
200
201
 
# File 'lib/rom/sql/relation/reading.rb', line 199

def select_append(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#select_group(*args, &block) ⇒ Relation

Select and group by specific columns

Examples:

tasks.select_group(:user_id)
# => [{ user_id: 1 }, { user_id: 2 }]

Parameters:

  • *args (Array<Symbol>) —

    A list of column names

Returns:



469
470
471
 
# File 'lib/rom/sql/relation/reading.rb', line 469

def select_group(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end

#sum(*args) ⇒ Integer

Returns a result of SQL SUM clause.

Examples:

users.sum(:age)

Parameters:

  • *args (Array<Symbol>) —

    A list with column names

Returns:

  • (Integer) 


227
228
229
 
# File 'lib/rom/sql/relation/reading.rb', line 227

def sum(*args)
  dataset.__send__(__method__, *args)
end

#union(relation, options = EMPTY_HASH, &block) ⇒ Relation

Adds a UNION clause for relation dataset using second relation dataset

Examples:

users.where(id: 1).union(users.where(id: 2))
# => [{ id: 1, name: 'Piotr' }, { id: 2, name: 'Jane' }]

Parameters:

  • relation (Relation) —

    Another relation

  • options (Hash) (defaults to: EMPTY_HASH) —

    Options for union

Options Hash (options):

  • :alias (Symbol) —

    Use the given value as the #from_self alias

  • :all (TrueClass, FalseClass) —

    Set to true to use UNION ALL instead of UNION, so duplicate rows can occur

  • :from_self (TrueClass, FalseClass) —

    Set to false to not wrap the returned dataset in a #from_self, use with care.

Returns:



489
490
491
 
# File 'lib/rom/sql/relation/reading.rb', line 489

def union(relation, options = EMPTY_HASH, &block)
  __new__(dataset.__send__(__method__, relation.dataset, options, &block))
end

#unique?(criteria) ⇒ TrueClass, FalseClass

Return if a restricted relation has 0 tuples

Examples:

users.unique?(email: '[email protected]') # true

users.insert(email: '[email protected]')

users.unique?(email: '[email protected]') # false

Parameters:

  • criteria (Hash) —

    The condition hash for WHERE clause

Returns:

  • (TrueClass, FalseClass) 


507
508
509
 
# File 'lib/rom/sql/relation/reading.rb', line 507

def unique?(criteria)
  where(criteria).count.zero?
end

#where(*args, &block) ⇒ Relation

Restrict a relation to match criteria

If block is passed it’ll be executed in the context of a condition builder object.

Examples:

users.where(name: 'Jane')

users.where { age >= 18 }

Parameters:

  • *args (Hash) —

    An optional hash with conditions for WHERE clause

Returns:

See Also:



290
291
292
 
# File 'lib/rom/sql/relation/reading.rb', line 290

def where(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
end