Class: ROM::SQL::Relation

Inherits:
Relation
  • Object
show all
Extended by:
ClassMethods
Includes:
Associations, Inspection
Defined in:
lib/rom/sql/relation.rb,
lib/rom/sql/relation/inspection.rb,
lib/rom/sql/relation/associations.rb,
lib/rom/sql/relation/class_methods.rb

Overview

Sequel-specific relation extensions

Defined Under Namespace

Modules: Associations, ClassMethods, Inspection

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ClassMethods

finalize, inherited, many_to_many, many_to_one, one_to_many

Methods included from Associations

#association_join, #association_left_join, #graph, #graph_join

Methods included from Inspection

#model, #primary_key

Constructor Details

#initialize(dataset, registry = {}) ⇒ Relation

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Relation.



28
29
30
31
 
# File 'lib/rom/sql/relation.rb', line 28

def initialize(dataset, registry = {})
  super
  @table = dataset.opts[:from].first
end

Instance Attribute Details

#header ⇒ Header (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return a header for this relation

Returns:



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

def header
  @header
end

#table ⇒ Object (readonly)

Name of the table used in FROM clause



25
26
27
 
# File 'lib/rom/sql/relation.rb', line 25

def table
  @table
end

Instance Method Details

#columns ⇒ Array<Symbol>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return raw column names

Returns:

  • (Array<Symbol>) 


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

def columns
  dataset.columns
end

#count ⇒ Relation

Return relation count

Examples:

users.count # => 12

Returns:



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

def count
  dataset.count
end

#delete(*args, &block) ⇒ Relation

Delete tuples from the relation

Examples:

users.delete # deletes all
users.where(name: 'Jane').delete # delete tuples
                                   from restricted relation

Returns:



374
375
376
 
# File 'lib/rom/sql/relation.rb', line 374

def delete(*args, &block)
  dataset.delete(*args, &block)
end

#distinct(*args, &block) ⇒ Relation

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

Examples:

users.distinct(:country)

Returns:



174
175
176
 
# File 'lib/rom/sql/relation.rb', line 174

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')

Returns:



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

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

#first ⇒ Relation

Get first tuple from the relation

Examples:

users.first

Returns:



114
115
116
 
# File 'lib/rom/sql/relation.rb', line 114

def first
  dataset.first
end

#group(*args, &block) ⇒ Relation

Group by specific columns

Examples:

tasks.group(:user_id)

Returns:



307
308
309
 
# File 'lib/rom/sql/relation.rb', line 307

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 }]

Returns:



320
321
322
 
# File 'lib/rom/sql/relation.rb', line 320

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

#inner_join(*args, &block) ⇒ Relation

Join other relation using inner join

Parameters:

  • relation (Symbol) —

    name

  • join (Hash) —

    keys

Returns:



283
284
285
 
# File 'lib/rom/sql/relation.rb', line 283

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

#insert(*args, &block) ⇒ Relation

Insert tuple into relation

Examples:

users.insert(name: 'Jane')

Parameters:

  • tuple (Hash)

Returns:



347
348
349
 
# File 'lib/rom/sql/relation.rb', line 347

def insert(*args, &block)
  dataset.insert(*args, &block)
end

#invert(*args, &block) ⇒ Relation

Inverts a request

Examples:

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

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

Returns:



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

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

#last ⇒ Relation

Get last tuple from the relation

Examples:

users.last

Returns:



126
127
128
 
# File 'lib/rom/sql/relation.rb', line 126

def last
  dataset.last
end

#left_join(*args, &block) ⇒ Relation

Join other relation using left outer join

Parameters:

  • relation (Symbol) —

    name

  • join (Hash) —

    keys

Returns:



295
296
297
 
# File 'lib/rom/sql/relation.rb', line 295

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)

Returns:



249
250
251
 
# File 'lib/rom/sql/relation.rb', line 249

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

#map(&block) ⇒ Object

Map tuples from the relation

Examples:

users.map { |user| ... }



271
272
273
 
# File 'lib/rom/sql/relation.rb', line 271

def map(&block)
  to_enum.map(&block)
end

#offset(*args, &block) ⇒ Relation

Set offset for the relation

Examples:

users.limit(10).offset(2)

Returns:



261
262
263
 
# File 'lib/rom/sql/relation.rb', line 261

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

#order(*args, &block) ⇒ Relation

Set order for the relation

Examples:

users.order(:name)

Returns:



225
226
227
 
# File 'lib/rom/sql/relation.rb', line 225

def order(*args, &block)
  __new__(dataset.__send__(__method__, *args, &block))
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:

rom.relation(:users) { |r| r.prefix(:user) }

Parameters:

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

    The prefix

Returns:



77
78
79
 
# File 'lib/rom/sql/relation.rb', line 77

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:

rom.relation(:users) { |r| r.project(:id, :name) }

Parameters:

  • names (Symbol) —

    A list of symbol column names

Returns:



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

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:

rom.relation(:users) { |r| r.qualified }

Returns:



91
92
93
 
# File 'lib/rom/sql/relation.rb', line 91

def qualified
  select(*qualified_columns)
end

#qualified_columns ⇒ Relation

Return a list of qualified column names

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

Returns:



102
103
104
 
# File 'lib/rom/sql/relation.rb', line 102

def qualified_columns
  header.qualified.to_a
end

#rename(options) ⇒ Relation

Rename columns in a relation

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

Examples:

rom.relation(:users) { |r| r.rename(name: :user_name) }

Parameters:

  • options (Hash) —

    A name => new_name map

Returns:



61
62
63
 
# File 'lib/rom/sql/relation.rb', line 61

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

#reverse(*args, &block) ⇒ Relation

Reverse the order of the relation

Examples:

users.order(:name).reverse

Returns:



237
238
239
 
# File 'lib/rom/sql/relation.rb', line 237

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)

Returns:



150
151
152
 
# File 'lib/rom/sql/relation.rb', line 150

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)

Returns:



162
163
164
 
# File 'lib/rom/sql/relation.rb', line 162

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 }]

Returns:



333
334
335
 
# File 'lib/rom/sql/relation.rb', line 333

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

#unique?(criteria) ⇒ Relation

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) —

    hash for the where clause

Returns:



392
393
394
 
# File 'lib/rom/sql/relation.rb', line 392

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

#update(*args, &block) ⇒ Relation

Update tuples in the relation

Examples:

users.update(name: 'Jane')
users.where(name: 'Jane').update(name: 'Jane Doe')

Returns:



360
361
362
 
# File 'lib/rom/sql/relation.rb', line 360

def update(*args, &block)
  dataset.update(*args, &block)
end

#where(*args, &block) ⇒ Relation

Restrict a relation to match criteria

Examples:

users.where(name: 'Jane')

Returns:



186
187
188
 
# File 'lib/rom/sql/relation.rb', line 186

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