Class: ROM::SQL::Attribute

Inherits:
Attribute
  • Object
show all
Extended by:
Dry::Core::Cache
Includes:
AttributeAliasing, AttributeWrapping
Defined in:
lib/rom/sql/attribute.rb,
lib/rom/sql/extensions/postgres/types/json.rb,
lib/rom/sql/extensions/postgres/types/array.rb,
lib/rom/sql/extensions/postgres/types/ltree.rb

Overview

Extended schema attributes tailored for SQL databases

rubocop:disable Metrics/ClassLength

Constant Summary collapse

OPERATORS = 
i[>= <= > <].freeze
NONSTANDARD_EQUALITY_VALUES = 
[true, false, nil].freeze
META_KEYS = 
i[index foreign_key target sql_expr qualified].freeze
QualifyError =

Error raised when an attribute cannot be qualified

Class.new(StandardError)

Class Method Summary collapse

Instance Method Summary collapse

Methods included from AttributeAliasing

#aliased, #aliased_projection?

Methods included from AttributeWrapping

#wrapped, #wrapped?

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(meth, *args) ⇒ Object (private)

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.

Delegate to sql expression if it responds to a given method



402
403
404
405
406
407
408
409
410
411
412
 
# File 'lib/rom/sql/attribute.rb', line 402

def method_missing(meth, *args, &)
  if OPERATORS.include?(meth)
    __cmp__(meth, args[0])
  elsif extensions.key?(meth)
    extensions[meth].(type, sql_expr, *args, &)
  elsif sql_expr.respond_to?(meth)
    meta(sql_expr: sql_expr.__send__(meth, *args, &))
  else
    super
  end
end

Class Method Details

.[](type, options = EMPTY_HASH) ⇒ Object

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. 



35
36
37
 
# File 'lib/rom/sql/attribute.rb', line 35

def [](type, options = EMPTY_HASH)
  fetch_or_store([type, options]) { new(type, **options) }
end

Instance Method Details

#! ⇒ Attribute

Negate the attribute’s sql expression

Examples:

users.where(!users[:id].is(1))

Returns:



228
229
230
 
# File 'lib/rom/sql/attribute.rb', line 228

def !
  ~self
end

#+(value) ⇒ SQL::Attribute<Types::LTree>

Concatenate two LTree values Translates to ||

Examples:

people.select {
  (ltree_tags + ROM::Types::Values::TreePath.new('Moscu')).as(:ltree_tags)
}.where { name.is('Jade Doe') }
people.select {
  (ltree_tags + 'Moscu').as(:ltree_tags)
}.where { name.is('Jade Doe') }

Parameters:

  • keys (LTree, String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 113

#=~(other) ⇒ Attribute

Return a new attribute with an equality expression

Examples:

users.where { email =~ 1 }

Returns:



202
203
204
 
# File 'lib/rom/sql/attribute.rb', line 202

def =~(other)
  meta(sql_expr: sql_expr =~ binary_operation_arg(other))
end

#any(value) ⇒ SQL::Attribute<Types::Bool>

Check whether the array includes a value Translates to the ANY operator

Parameters:

  • value (Object)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/array.rb', line 21

#ascendant(value) ⇒ SQL::Attribute<Types::Bool>

Check whether the LTree is a ascendant of the LTree value Translates to the @> operator

Examples:

people.select(:name).where { ltree_tags.ascendant('Bottom.Cities') }

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 91

#canonical ⇒ Object

Return a new attribute in its canonical form



43
44
45
46
47
48
49
 
# File 'lib/rom/sql/attribute.rb', line 43

def canonical
  if aliased?
    with(alias: nil).meta(sql_expr: nil)
  else
    self
  end
end

#case(mapping) ⇒ SQL::Attribute

Build a case expression based on attribute. See SQL::Function#case when you don’t have a specific expression after the CASE keyword. Pass the :else keyword to provide the catch-all case, it’s mandatory because of the Sequel’s API used underneath.

Examples:

users.select_append { id.case(1 => `'first'`, else: `'other'`).as(:first_or_not) }

Parameters:

  • mapping (Hash) —

    mapping between SQL expressions

Returns:



370
371
372
373
374
375
376
377
378
379
 
# File 'lib/rom/sql/attribute.rb', line 370

def case(mapping)
  mapping = mapping.dup
  otherwise = mapping.delete(:else) do
    raise ArgumentError, 'provide the default case using the :else keyword'
  end

  type = mapping.values[0].type

  Attribute[type].meta(sql_expr: ::Sequel.case(mapping, otherwise, self))
end

#concat(other, sep = ' ') ⇒ SQL::Function

Create a CONCAT function from the attribute

Examples:

with default separator (‘ ’)

users[:id].concat(users[:name])

with custom separator

users[:id].concat(users[:name], '-')

Parameters:

Returns:



287
288
289
 
# File 'lib/rom/sql/attribute.rb', line 287

def concat(other, sep = ' ')
  Function.new(type).concat(self, sep, other)
end

#contain(other) ⇒ SQL::Attribute<Types::Bool>

Check whether the array includes another array Translates to the @> operator

Parameters:

  • other (Array)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 2

#contain_ancestor(value) ⇒ SQL::Attribute<Types::PG::Bool>

Does LTree array contain an ancestor of ltree Translates to @>

Examples:

people.select(:name).where {
  parents_tags.contain_ancestor('Top.Building.EmpireState.381')
}

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 135

#contain_any_ltextquery(value) ⇒ SQL::Attribute<Types::Bool>

Does LTree array contain any path matching ltxtquery Translates to @

Examples:

people.select(:name).where { parents_tags.contain_any_ltextquery('Parks')}

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 122

#contain_ascendant(value) ⇒ SQL::Attribute<Types::Bool>

Check whether the LTree is a ascendant of the LTree values Translates to the @> operator

Examples:

people.select(:name).where { ltree_tags.contain_ascendant(['Bottom.Cities']) }
people.select(:name).where {
  ltree_tags.contain_ascendant('Bottom.Cities, Bottom.Parks')
}

Parameters:

  • value (Array<String>, String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 75

#contain_descendant(value) ⇒ SQL::Attribute<Types::PG::Bool>

Does LTree array contain an descendant of ltree Translates to <@

Examples:

people.select(:name).where {
  parents_tags.contain_descendant('Top.Building.EmpireState.381')
}

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 46

#contained_by(other) ⇒ SQL::Attribute<Types::Bool>

Check whether the array is contained by another array Translates to the <@ operator

Parameters:

  • other (Array)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 17

#delete(*path) ⇒ SQL::Attribute<Types::PG::JSONB>

Deletes the specified value by key, index, or path Translates to - or #- depending on the number of arguments

Examples:

people.select { data.delete('age').as(:data_without_age) }
people.select { fields.delete(0).as(:fields_without_first) }
people.select { fields.delete(-1).as(:fields_without_last) }
people.select { data.delete('deeply', 'nested', 'value').as(:data) }
people.select { fields.delete('0', 'name').as(:data) }

Parameters:

  • path (Array<String>)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 118

#descendant(value) ⇒ SQL::Attribute<Types::Bool>

Check whether the LTree is a descendant of the LTree value Translates to the <@ operator

Examples:

people.select(:name).where { ltree_tags.descendant('Bottom.Cities') }

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 62

#find_ancestor(value) ⇒ SQL::Attribute<Types::PG::LTree>

Return first LTree array entry that is an ancestor of ltree, NULL if none Translates to ?@>

Examples:

people.select(:name).where {
  parents_tags.find_ancestor('Left.Parks').not(nil)
}

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 165

#find_descendant(value) ⇒ SQL::Attribute<Types::PG::LTree>

Return first LTree array entry that is an descendant of ltree, NULL if none Translates to ?<@

Examples:

people.select(:name).where {
  parents_tags.find_descendant('Left.Parks').not(nil)
}

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 180

#foreign_key ⇒ SQL::Attribute

Return a new attribute marked as a FK

Returns:



145
146
147
 
# File 'lib/rom/sql/attribute.rb', line 145

def foreign_key
  meta(foreign_key: true)
end

#func ⇒ SQL::Function

Create a function DSL from the attribute

Examples:

users[:id].func { integer::count(id).as(:count) }

Returns:



270
271
272
 
# File 'lib/rom/sql/attribute.rb', line 270

def func(&)
  ProjectionDSL.new(name => self).call(&).first
end

#get(idx) ⇒ SQL::Attribute

Get element by index (PG uses 1-based indexing)

Parameters:

  • idx (Integer)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 30

#get_text(*path) ⇒ SQL::Attribute<Types::String>

Extract the JSON value as text using at the specified path Translates to ->> or #>> depending on the number of arguments

Examples:

people.select { data.get('age').as(:person_age) }
people.select { fields.get(0).as(:first_field) }
people.select { fields.get('0', 'value').as(:first_field_value) }

Parameters:

  • path (Array<Integer>, Array<String>) —

    Path to extract

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 45

#has_all_keys(*keys) ⇒ SQL::Attribute<Types::Bool>

Does the JSON value have all the specified top-level keys Translates to ?&

Examples:

people.where { data.has_all_keys('age', 'height') }

Parameters:

  • keys (Array<String>)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 86

#has_any_key(*keys) ⇒ SQL::Attribute<Types::Bool>

Does the JSON value have any of the specified top-level keys Translates to ?|

Examples:

people.where { data.has_any_key('age', 'height') }

Parameters:

  • keys (Array<String>)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 73

#has_key(key) ⇒ SQL::Attribute<Types::Bool>

Does the JSON value have the specified top-level key Translates to ?

Examples:

people.where { data.has_key('age') }

Parameters:

  • key (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 60

#in(*args) ⇒ Object

Return a boolean expression with an inclusion test

If the single argument passed to the method is a Range object then the resulting expression will restrict the attribute value with range’s bounds. Upper bound condition will be inclusive/non-inclusive depending on the range type.

If more than one argument is passed to the method or the first argument is not Range then the result will be a simple IN check.

Examples:

users.where { id.in(1..100) | created_at(((Time.now - 86400)..Time.now)) }
users.where { id.in(1, 2, 3) }
users.where(users[:id].in(1, 2, 3))

Parameters:

  • args (Array<Object>) —

    A range or a list of values for an inclusion check



250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/rom/sql/attribute.rb', line 250

def in(*args)
  if args.first.is_a?(Range)
    range = args.first
    lower_cond = __cmp__(:>=, range.begin)
    upper_cond = __cmp__(range.exclude_end? ? :< : :<=, range.end)

    Sequel::SQL::BooleanExpression.new(:AND, lower_cond, upper_cond)
  else
    __cmp__(:IN, args)
  end
end

#indexed ⇒ Object

Returns a new attribute marked as indexed



326
327
328
 
# File 'lib/rom/sql/attribute.rb', line 326

def indexed
  meta(index: true)
end

#indexed? ⇒ Boolean

Returns:

  • (Boolean) 


319
320
321
 
# File 'lib/rom/sql/attribute.rb', line 319

def indexed?
  meta[:index].equal?(true)
end

#is(other) ⇒ Object

Return a boolean expression with an equality operator

Examples:

users.where { id.is(1) }

users.where(users[:id].is(1))

Parameters:

  • other (Object) —

    Any SQL-compatible object type



190
191
192
 
# File 'lib/rom/sql/attribute.rb', line 190

def is(other)
  self =~ other
end

#join(delimiter, null_repr) ⇒ SQL::Attribute<Types::String>

Convert the array to a string by joining values with a delimiter (empty stirng by default) and optional filler for NULL values Translates to an ‘array_to_string` call

Parameters:

  • delimiter (Object)
  • null_repr (Object)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/array.rb', line 67

#joined ⇒ SQL::Attribute

Return a new attribute marked as joined

Whenever you join two schemas, the right schema’s attribute will be marked as joined using this method

Returns:



97
98
99
 
# File 'lib/rom/sql/attribute.rb', line 97

def joined
  meta(joined: true)
end

#joined? ⇒ Boolean

Return if an attribute was used in a join

Examples:

schema = users.schema.join(tasks.schema)

schema[:id, :tasks].joined?
# => true

Returns:

  • (Boolean) 


112
113
114
 
# File 'lib/rom/sql/attribute.rb', line 112

def joined?
  meta[:joined].equal?(true)
end

#length ⇒ SQL::Attribute<Types::Integer>

Return array size

Returns:




# File 'lib/rom/sql/extensions/postgres/types/array.rb', line 41

#match(value) ⇒ SQL::Attribute<Types::Bool>

Check whether the LTree match a lquery value Translates to the ~ operator

Examples:

people.select(:name).where { ltree_tags.match('Bottom.Cities') }

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 2

#match_any(value) ⇒ SQL::Attribute<Types::Bool>

Check whether the LTree match any of the lquery values Translates to the ? operator

Examples:

people.select(:name).where {
  ltree_tags.match_any(['Bottom', 'Bottom.Cities.*'])
}
people.select(:name).where {
  ltree_tags.match_any('Bottom,Bottom.Cities.*')
}

Parameters:

  • value (Array, String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 15

#match_any_lquery(value) ⇒ SQL::Attribute<Types::PG::LTree>

Return first LTree array entry that matches lquery, NULL if none Translates to ?~

Examples:

people.select(:name).where {
  parents_tags.match_any_lquery('Right.*').not(nil)
}

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 195

#match_any_ltextquery(value) ⇒ SQL::Attribute<Types::PG::LTree>

Return first LTree array entry that matches ltextquery, NULL if none Translates to ?@

Examples:

people.select(:name).where {
  parents_tags.match_any_ltextquery('EmpireState').not(nil)
}

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 210

#match_ltextquery(value) ⇒ SQL::Attribute<Types::Bool>

Check whether the LTree match a ltextquery Translates to the @ operator

Examples:

people.select(:name).where { ltree_tags.match_ltextquery('Countries & Brasil') }

Parameters:

  • value (String)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/ltree.rb', line 33

#merge(value) ⇒ SQL::Attribute<Types::PG::JSONB>

Concatenate two JSON values Translates to ||

Examples:

people.select { data.merge(fetched_at: Time.now).as(:data) }
people.select { (fields + [name: 'height', value: 165]).as(:fields) }

Parameters:

  • value (Hash, Array)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/json.rb', line 99

#meta_options_ast ⇒ Object

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. 



331
332
333
334
335
 
# File 'lib/rom/sql/attribute.rb', line 331

def meta_options_ast
  meta = super
  meta[:index] = true if indexed?
  meta
end

#not(other) ⇒ Object

Return a boolean expression with a negated equality operator

Examples:

users.where { id.not(1) }

users.where(users[:id].not(1))

Parameters:

  • other (Object) —

    Any SQL-compatible object type



216
217
218
 
# File 'lib/rom/sql/attribute.rb', line 216

def not(other)
  !is(other)
end

#overlaps(other) ⇒ SQL::Attribute<Types::Bool>

Check whether the arrays have common values Translates to &&

Parameters:

  • other (Array)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/array.rb', line 48

#qualifiable? ⇒ Boolean

Return if an attribute is qualifiable

Returns:

  • (Boolean) 


136
137
138
 
# File 'lib/rom/sql/attribute.rb', line 136

def qualifiable?
  !source.nil?
end

#qualified(table_alias = nil) ⇒ SQL::Attribute

Return a new attribute marked as qualified

Examples:

users[:id].aliased(:user_id)

Returns:



59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/rom/sql/attribute.rb', line 59

def qualified(table_alias = nil)
  return self if qualified? && table_alias.nil?
  return meta(qualified: false) unless qualifiable?

  case sql_expr
  when ::Sequel::SQL::AliasedExpression,
       ::Sequel::SQL::Identifier,
       ::Sequel::SQL::QualifiedIdentifier
    attr = meta(qualified: table_alias || true)
    attr.meta(sql_expr: attr.to_sql_name)
  else
    raise QualifyError, "can't qualify #{name.inspect} (#{sql_expr.inspect})"
  end
end

#qualified? ⇒ Boolean

Return if an attribute type is qualified

Examples:

id = users[:id].qualify

id.qualified?
# => true

Returns:

  • (Boolean) 


127
128
129
 
# File 'lib/rom/sql/attribute.rb', line 127

def qualified?
  meta[:qualified].equal?(true) || meta[:qualified].is_a?(Symbol)
end

#qualified_projection(table_alias = nil) ⇒ SQL::Attribute

Return a new attribute that is aliased and marked as qualified

Intended to be used when passing attributes to ‘dataset#select`

Returns:



81
82
83
84
85
86
87
 
# File 'lib/rom/sql/attribute.rb', line 81

def qualified_projection(table_alias = nil)
  if aliased?
    qualified(table_alias).aliased(self.alias)
  else
    qualified(table_alias)
  end
end

#remove_value(value) ⇒ SQL::Attribute<Types::PG::Array>

Remove elements by value

Parameters:

  • value (Object)

Returns:




# File 'lib/rom/sql/extensions/postgres/types/array.rb', line 58

#sql_literal(ds) ⇒ Object

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.

Sequel calls this method to coerce an attribute into SQL string

Parameters:

  • ds (Sequel::Dataset) 


296
297
298
 
# File 'lib/rom/sql/attribute.rb', line 296

def sql_literal(ds)
  ds.literal(sql_expr)
end

#to_sql_name ⇒ Sequel::SQL::AliasedExpression, Sequel::SQL::Identifier

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.

Sequel column representation

Returns:

  • (Sequel::SQL::AliasedExpression, Sequel::SQL::Identifier) 


305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/rom/sql/attribute.rb', line 305

def to_sql_name
  @_to_sql_name ||=
    if qualified? && aliased_projection?
      Sequel.qualify(table_name, name).as(self.alias)
    elsif qualified?
      Sequel.qualify(table_name, name)
    elsif aliased_projection?
      Sequel.as(name, self.alias)
    else
      Sequel[name]
    end
end

#to_sym ⇒ Symbol

Return symbol representation of an attribute

This uses convention from sequel where double underscore in the name is used for qualifying, and triple underscore means aliasing

Examples:

users[:id].qualified.to_sym
# => :users__id

users[:id].as(:user_id).to_sym
# => :id___user_id

users[:id].qualified.as(:user_id).to_sym
# => :users__id___user_id

Returns:

  • (Symbol) 


167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/rom/sql/attribute.rb', line 167

def to_sym
  @_to_sym ||=
    if qualified? && aliased?
      :"#{table_name}__#{name}___#{meta[:alias]}"
    elsif qualified?
      :"#{table_name}__#{name}"
    elsif aliased?
      :"#{name}___#{meta[:alias]}"
    else
      name
    end
end

#unwrap ⇒ Object

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.

Removes metadata from the type



340
341
342
343
344
345
 
# File 'lib/rom/sql/attribute.rb', line 340

def unwrap
  cleaned_meta = meta.except(*META_KEYS)
  type = optional? ? right : self.type

  self.class.new(type.with(meta: cleaned_meta), **options)
end

#value(value) ⇒ SQL::Attribute

Wrap a value with the type, it allows using attribute and type specific methods on literals and things like this

Parameters:

  • value (Object) —

    any SQL-serializable value

Returns:



354
355
356
 
# File 'lib/rom/sql/attribute.rb', line 354

def value(value)
  meta(sql_expr: Sequel[value])
end