class Sequel::Model::Associations::AssociationReflection

  1. lib/sequel/model/associations.rb
Superclass: Hash

AssociationReflection is a Hash subclass that keeps information on Sequel::Model associations. It provides methods to reduce internal code duplication. It should not be instantiated by the user.

Included modules

  1. Sequel::Inflections

Constants

ASSOCIATION_DATASET_PROC = proc{|r| r.association_dataset_for(self)}  
FINALIZE_SETTINGS = { :associated_class=>:class, :associated_dataset=>:_dataset, :eager_limit_strategy=>:_eager_limit_strategy, :placeholder_loader=>:placeholder_loader, :predicate_key=>:predicate_key, :predicate_keys=>:predicate_keys, :reciprocal=>:reciprocal, }.freeze  

Map of methods to cache keys used for finalizing associations.

Public Instance methods

_add_method()

Name symbol for the _add internal association method

[show source] 
   # File lib/sequel/model/associations.rb
36 def _add_method
37   self[:_add_method]
38 end
_remove_all_method()

Name symbol for the _remove_all internal association method

[show source] 
   # File lib/sequel/model/associations.rb
41 def _remove_all_method
42   self[:_remove_all_method]
43 end
_remove_method()

Name symbol for the _remove internal association method

[show source] 
   # File lib/sequel/model/associations.rb
46 def _remove_method
47   self[:_remove_method]
48 end
_setter_method()

Name symbol for the _setter association method

[show source] 
   # File lib/sequel/model/associations.rb
51 def _setter_method
52   self[:_setter_method]
53 end
add_method()

Name symbol for the add association method

[show source] 
   # File lib/sequel/model/associations.rb
56 def add_method
57   self[:add_method]
58 end
apply_dataset_changes(ds)

Apply all non-instance specific changes to the given dataset and return it.

[show source] 
   # File lib/sequel/model/associations.rb
84 def apply_dataset_changes(ds)
85   ds = ds.with_extend(AssociationDatasetMethods).clone(:association_reflection => self)
86   if exts = self[:reverse_extend]
87     ds = ds.with_extend(*exts)
88   end
89   ds = ds.select(*select) if select
90   if c = self[:conditions]
91     ds = (c.is_a?(Array) && !Sequel.condition_specifier?(c)) ? ds.where(*c) : ds.where(c)
92   end
93   ds = ds.order(*self[:order]) if self[:order]
94   ds = ds.limit(*self[:limit]) if self[:limit]
95   ds = ds.limit(1).skip_limit_check if limit_to_single_row?
96   ds = ds.eager(self[:eager]) if self[:eager]
97   ds = ds.distinct if self[:distinct]
98   ds
99 end
apply_distinct_on_eager_limit_strategy(ds)

Use DISTINCT ON and ORDER BY clauses to limit the results to the first record with matching keys.

[show source] 
    # File lib/sequel/model/associations.rb
138 def apply_distinct_on_eager_limit_strategy(ds)
139   keys = predicate_key
140   ds.distinct(*keys).order_prepend(*keys)
141 end
apply_eager_dataset_changes(ds)

Apply all non-instance specific changes and the eager_block option to the given dataset and return it.

[show source] 
    # File lib/sequel/model/associations.rb
103 def apply_eager_dataset_changes(ds)
104   ds = apply_dataset_changes(ds)
105   if block = self[:eager_block]
106     ds = block.call(ds)
107   end
108   ds
109 end
apply_eager_graph_limit_strategy(strategy, ds)

Apply the eager graph limit strategy to the dataset to graph into the current dataset, or return the dataset unmodified if no SQL limit strategy is needed.

[show source] 
    # File lib/sequel/model/associations.rb
113 def apply_eager_graph_limit_strategy(strategy, ds)
114   case strategy
115   when :distinct_on
116     apply_distinct_on_eager_limit_strategy(ds.order_prepend(*self[:order]))
117   when :window_function
118     apply_window_function_eager_limit_strategy(ds.order_prepend(*self[:order])).select(*ds.columns)
119   else
120     ds
121   end
122 end
apply_eager_limit_strategy(ds, strategy=eager_limit_strategy, limit_and_offset=limit_and_offset())

Apply an eager limit strategy to the dataset, or return the dataset unmodified if it doesn’t need an eager limit strategy.

[show source] 
    # File lib/sequel/model/associations.rb
126 def apply_eager_limit_strategy(ds, strategy=eager_limit_strategy, limit_and_offset=limit_and_offset())
127   case strategy
128   when :distinct_on
129     apply_distinct_on_eager_limit_strategy(ds)
130   when :window_function
131     apply_window_function_eager_limit_strategy(ds, limit_and_offset)
132   else
133     ds
134   end
135 end
apply_ruby_eager_limit_strategy(rows, limit_and_offset = limit_and_offset())

If the ruby eager limit strategy is being used, slice the array using the slice range to return the object(s) at the correct offset/limit.

[show source] 
    # File lib/sequel/model/associations.rb
165 def apply_ruby_eager_limit_strategy(rows, limit_and_offset = limit_and_offset())
166   name = self[:name]
167   return unless range = slice_range(limit_and_offset)
168   if returns_array?
169     rows.each{|o| o.associations[name] = o.associations[name][range] || []}
170   else
171     offset = range.begin
172     rows.each{|o| o.associations[name] = o.associations[name][offset]}
173   end
174 end
apply_window_function_eager_limit_strategy(ds, limit_and_offset=limit_and_offset())

Use a window function to limit the results of the eager loading dataset.

[show source] 
    # File lib/sequel/model/associations.rb
144 def apply_window_function_eager_limit_strategy(ds, limit_and_offset=limit_and_offset())
145   rn = ds.row_number_column 
146   limit, offset = limit_and_offset
147   ds = ds.unordered.select_append{|o| o.row_number.function.over(:partition=>predicate_key, :order=>ds.opts[:order]).as(rn)}.from_self
148   ds = ds.order(rn) if ds.db.database_type == :mysql
149   ds = if !returns_array?
150     ds.where(rn => offset ? offset+1 : 1)
151   elsif offset
152     offset += 1
153     if limit
154       ds.where(rn => (offset...(offset+limit))) 
155     else
156       ds.where{SQL::Identifier.new(rn) >= offset} 
157     end
158   else
159     ds.where{SQL::Identifier.new(rn) <= limit} 
160   end
161 end
assign_singular?()

Whether the associations cache should use an array when storing the associated records during eager loading.

[show source] 
    # File lib/sequel/model/associations.rb
178 def assign_singular?
179   !returns_array?
180 end
associated_class()

The class associated to the current model class via this association

[show source] 
   # File lib/sequel/model/associations.rb
66 def associated_class
67   cached_fetch(:class) do
68     begin
69       constantize(self[:class_name])
70     rescue NameError => e
71       raise NameError, "#{e.message} (this happened when attempting to find the associated class for #{inspect})", e.backtrace
72     end
73   end
74 end
associated_dataset()

The dataset associated via this association, with the non-instance specific changes already applied. This will be a joined dataset if the association requires joining tables.

[show source] 
   # File lib/sequel/model/associations.rb
79 def associated_dataset
80   cached_fetch(:_dataset){apply_dataset_changes(_associated_dataset)}
81 end
association_dataset_for(object)

Return an dataset that will load the appropriate associated objects for the given object using this association.

[show source] 
    # File lib/sequel/model/associations.rb
215 def association_dataset_for(object)
216   condition = if can_have_associated_objects?(object)
217     predicate_keys.zip(predicate_key_values(object))
218   else
219     false
220   end
221 
222   associated_dataset.where(condition)
223 end
association_dataset_proc()

Proc used to create the association dataset method.

[show source] 
    # File lib/sequel/model/associations.rb
227 def association_dataset_proc
228   ASSOCIATION_DATASET_PROC
229 end
association_method()

Name symbol for association method, the same as the name of the association.

[show source] 
   # File lib/sequel/model/associations.rb
61 def association_method
62   self[:name]
63 end
can_have_associated_objects?(obj)

Whether this association can have associated objects, given the current object. Should be false if obj cannot have associated objects because the necessary key columns are NULL.

[show source] 
    # File lib/sequel/model/associations.rb
185 def can_have_associated_objects?(obj)
186   true
187 end
cloneable?(ref)

Whether you are able to clone from the given association type to the current association type, true by default only if the types match.

[show source] 
    # File lib/sequel/model/associations.rb
191 def cloneable?(ref)
192   ref[:type] == self[:type]
193 end
dataset_method()

Name symbol for the dataset association method

[show source] 
    # File lib/sequel/model/associations.rb
196 def dataset_method
197   self[:dataset_method]
198 end
dataset_need_primary_key?()

Whether the dataset needs a primary key to function, true by default.

[show source] 
    # File lib/sequel/model/associations.rb
201 def dataset_need_primary_key?
202   true
203 end
delete_row_number_column(ds=associated_dataset)

Return the symbol used for the row number column if the window function eager limit strategy is being used, or nil otherwise.

[show source] 
    # File lib/sequel/model/associations.rb
207 def delete_row_number_column(ds=associated_dataset)
208   if eager_limit_strategy == :window_function
209     ds.row_number_column 
210   end
211 end
eager_graph_lazy_dataset?()

Whether to eagerly graph a lazy dataset, true by default. If this is false, the association won’t respect the :eager_graph option when loading the association for a single record.

[show source] 
    # File lib/sequel/model/associations.rb
354 def eager_graph_lazy_dataset?
355   true
356 end
eager_graph_limit_strategy(strategy)

The eager_graph limit strategy to use for this dataset

[show source] 
    # File lib/sequel/model/associations.rb
232 def eager_graph_limit_strategy(strategy)
233   if self[:limit] || !returns_array?
234     strategy = strategy[self[:name]] if strategy.is_a?(Hash)
235     case strategy
236     when true
237       true_eager_graph_limit_strategy
238     when Symbol
239       strategy
240     else
241       if returns_array? || offset
242         :ruby
243       end
244     end
245   end
246 end
eager_limit_strategy()

The eager limit strategy to use for this dataset.

[show source] 
    # File lib/sequel/model/associations.rb
249 def eager_limit_strategy
250   cached_fetch(:_eager_limit_strategy) do
251     if self[:limit] || !returns_array?
252       case s = cached_fetch(:eager_limit_strategy){default_eager_limit_strategy}
253       when true
254         true_eager_limit_strategy
255       else
256         s
257       end
258     end
259   end
260 end
eager_load_results(eo, &block)

Eager load the associated objects using the hash of eager options, yielding each row to the block.

[show source] 
    # File lib/sequel/model/associations.rb
264 def eager_load_results(eo, &block)
265   rows = eo[:rows]
266   unless eo[:initialize_rows] == false
267     Sequel.synchronize_with(eo[:mutex]){initialize_association_cache(rows)}
268   end
269   if eo[:id_map]
270     ids = eo[:id_map].keys
271     return ids if ids.empty?
272   end
273   strategy = eager_limit_strategy
274   cascade = eo[:associations]
275   eager_limit = nil
276 
277   if eo[:no_results]
278     no_results = true
279   elsif eo[:eager_block] || eo[:loader] == false || !use_placeholder_loader?
280     ds = eager_loading_dataset(eo)
281 
282     strategy = ds.opts[:eager_limit_strategy] || strategy
283 
284     eager_limit =
285       if el = ds.opts[:eager_limit]
286         raise Error, "The :eager_limit dataset option is not supported for associations returning a single record" unless returns_array?
287         strategy ||= true_eager_graph_limit_strategy
288         if el.is_a?(Array)
289           el
290         else
291           [el, nil]
292         end
293       else
294         limit_and_offset
295       end
296 
297     strategy = true_eager_graph_limit_strategy if strategy == :union
298     # Correlated subqueries are not supported for regular eager loading
299     strategy = :ruby if strategy == :correlated_subquery
300     strategy = nil if strategy == :ruby && assign_singular?
301     objects = apply_eager_limit_strategy(ds, strategy, eager_limit).all
302 
303     if strategy == :window_function
304       delete_rn = ds.row_number_column 
305       objects.each{|obj| obj.values.delete(delete_rn)}
306     end
307   elsif strategy == :union
308     objects = []
309     ds = associated_dataset
310     loader = union_eager_loader
311     joiner = " UNION ALL "
312     ids.each_slice(subqueries_per_union).each do |slice|
313       sql = loader.send(:sql_origin)
314       join = false
315       slice.each do |k|
316         if join
317           sql << joiner
318         else
319           join = true
320         end
321         loader.append_sql(sql, *k)
322       end
323       objects.concat(ds.with_sql(sql).to_a)
324     end
325     ds = ds.eager(cascade) if cascade
326     ds.send(:post_load, objects)
327   else
328     loader = placeholder_eager_loader
329     loader = loader.with_dataset{|dataset| dataset.eager(cascade)} if cascade
330     objects = loader.all(ids)
331   end
332 
333   Sequel.synchronize_with(eo[:mutex]){objects.each(&block)} unless no_results
334 
335   if strategy == :ruby
336     apply_ruby_eager_limit_strategy(rows, eager_limit || limit_and_offset)
337   end
338 end
eager_loader_key()

The key to use for the key hash when eager loading

[show source] 
    # File lib/sequel/model/associations.rb
341 def eager_loader_key
342   self[:eager_loader_key]
343 end
eager_loading_use_associated_key?()

By default associations do not need to select a key in an associated table to eagerly load.

[show source] 
    # File lib/sequel/model/associations.rb
347 def eager_loading_use_associated_key?
348   false
349 end
filter_by_associations_add_conditions?()

Whether additional conditions should be added when using the filter by associations support.

[show source] 
    # File lib/sequel/model/associations.rb
360 def filter_by_associations_add_conditions?
361   self[:conditions] || self[:eager_block] || self[:limit]
362 end
filter_by_associations_conditions_expression(obj)

The expression to use for the additional conditions to be added for the filter by association support, when the association itself is filtered. Works by using a subquery to test that the objects passed also meet the association filter criteria.

[show source] 
    # File lib/sequel/model/associations.rb
368 def filter_by_associations_conditions_expression(obj)
369   ds = filter_by_associations_conditions_dataset.where(filter_by_associations_conditions_subquery_conditions(obj))
370   {filter_by_associations_conditions_key=>ds}
371 end
finalize()

Finalize the association by first attempting to populate the thread-safe cache, and then transfering the thread-safe cache value to the association itself, so that a mutex is not needed to get the value.

[show source] 
    # File lib/sequel/model/associations.rb
376 def finalize
377   return unless cache = self[:cache]
378 
379   finalizer = proc do |meth, key|
380     next if has_key?(key)
381 
382     # Allow calling private methods to make sure caching is done appropriately
383     send(meth)
384     self[key] = cache.delete(key) if cache.has_key?(key)
385   end
386 
387   finalize_settings.each(&finalizer)
388 
389   unless self[:instance_specific]
390     finalizer.call(:associated_eager_dataset, :associated_eager_dataset)
391     finalizer.call(:filter_by_associations_conditions_dataset, :filter_by_associations_conditions_dataset)
392   end
393 
394   nil
395 end
finalize_settings()
[show source] 
    # File lib/sequel/model/associations.rb
407 def finalize_settings
408   FINALIZE_SETTINGS
409 end
handle_silent_modification_failure?()

Whether to handle silent modification failure when adding/removing associated records, false by default.

[show source] 
    # File lib/sequel/model/associations.rb
413 def handle_silent_modification_failure?
414   false
415 end
initialize_association_cache(objects)

Initialize the associations cache for the current association for the given objects.

[show source] 
    # File lib/sequel/model/associations.rb
418 def initialize_association_cache(objects)
419   name = self[:name]
420   if assign_singular?
421     objects.each{|object| object.associations[name] = nil}
422   else
423     objects.each{|object| object.associations[name] = []}
424   end
425 end
inspect()

Show which type of reflection this is, and a guess at what code was used to create the association.

[show source] 
    # File lib/sequel/model/associations.rb
429 def inspect
430   o = self[:orig_opts].dup
431   o.delete(:class)
432   o.delete(:class_name)
433   o.delete(:block) unless o[:block]
434   o[:class] = self[:orig_class] if self[:orig_class]
435 
436   "#<#{self.class} #{self[:model]}.#{self[:type]} #{self[:name].inspect}#{", #{o.inspect[1...-1]}" unless o.empty?}>"
437 end
limit_and_offset()

The limit and offset for this association (returned as a two element array).

[show source] 
    # File lib/sequel/model/associations.rb
440 def limit_and_offset
441   if (v = self[:limit]).is_a?(Array)
442     v
443   else
444     [v, nil]
445   end
446 end
need_associated_primary_key?()

Whether the associated object needs a primary key to be added/removed, false by default.

[show source] 
    # File lib/sequel/model/associations.rb
450 def need_associated_primary_key?
451   false
452 end
placeholder_loader()

A placeholder literalizer that can be used to lazily load the association. If one can’t be used, returns nil.

[show source] 
    # File lib/sequel/model/associations.rb
456 def placeholder_loader
457   if use_placeholder_loader?
458     cached_fetch(:placeholder_loader) do
459       associated_dataset.placeholder_literalizer_loader do |pl, ds|
460         ds = ds.where(Sequel.&(*predicate_keys.map{|k| SQL::BooleanExpression.new(:'=', k, pl.arg)}))
461         if self[:block]
462           ds = self[:block].call(ds)
463         end
464         ds
465       end
466     end
467   end
468 end
predicate_key_values(object)

The values that predicate_keys should match for objects to be associated.

[show source] 
    # File lib/sequel/model/associations.rb
476 def predicate_key_values(object)
477   predicate_key_methods.map{|k| object.get_column_value(k)}
478 end
predicate_keys()

The keys to use for loading of the regular dataset, as an array.

[show source] 
    # File lib/sequel/model/associations.rb
471 def predicate_keys
472   cached_fetch(:predicate_keys){Array(predicate_key)}
473 end
qualify(table, col)

Qualify col with the given table name.

[show source] 
    # File lib/sequel/model/associations.rb
481 def qualify(table, col)
482   transform(col) do |k|
483     case k
484     when Symbol, SQL::Identifier
485       SQL::QualifiedIdentifier.new(table, k)
486     else
487       Sequel::Qualifier.new(table).transform(k)
488     end
489   end
490 end
qualify_assoc(col)

Qualify col with the associated model’s table name.

[show source] 
    # File lib/sequel/model/associations.rb
493 def qualify_assoc(col)
494   qualify(associated_class.table_name, col)
495 end
qualify_cur(col)

Qualify col with the current model’s table name.

[show source] 
    # File lib/sequel/model/associations.rb
498 def qualify_cur(col)
499   qualify(self[:model].table_name, col)
500 end
reciprocal()

Returns the reciprocal association variable, if one exists. The reciprocal association is the association in the associated class that is the opposite of the current association. For example, Album.many_to_one :artist and Artist.one_to_many :albums are reciprocal associations. This information is to populate reciprocal associations. For example, when you do this_artist.add_album(album) it sets album.artist to this_artist.

[show source] 
    # File lib/sequel/model/associations.rb
508 def reciprocal
509   cached_fetch(:reciprocal) do
510     possible_recips = []
511 
512     associated_class.all_association_reflections.each do |assoc_reflect|
513       if reciprocal_association?(assoc_reflect)
514         possible_recips << assoc_reflect
515       end
516     end
517 
518     if possible_recips.length == 1
519       cached_set(:reciprocal_type, possible_recips.first[:type]) if ambiguous_reciprocal_type?
520       possible_recips.first[:name]
521     end
522   end
523 end
reciprocal_array?()

Whether the reciprocal of this association returns an array of objects instead of a single object, true by default.

[show source] 
    # File lib/sequel/model/associations.rb
527 def reciprocal_array?
528   true
529 end
remove_all_method()

Name symbol for the remove_all_ association method

[show source] 
    # File lib/sequel/model/associations.rb
532 def remove_all_method
533   self[:remove_all_method]
534 end
remove_before_destroy?()

Whether associated objects need to be removed from the association before being destroyed in order to preserve referential integrity.

[show source] 
    # File lib/sequel/model/associations.rb
538 def remove_before_destroy?
539   true
540 end
remove_method()

Name symbol for the remove_ association method

[show source] 
    # File lib/sequel/model/associations.rb
543 def remove_method
544   self[:remove_method]
545 end
remove_should_check_existing?()

Whether to check that an object to be disassociated is already associated to this object, false by default.

[show source] 
    # File lib/sequel/model/associations.rb
548 def remove_should_check_existing?
549   false
550 end
returns_array?()

Whether this association returns an array of objects instead of a single object, true by default.

[show source] 
    # File lib/sequel/model/associations.rb
554 def returns_array?
555   true
556 end
select()

The columns to select when loading the association.

[show source] 
    # File lib/sequel/model/associations.rb
559 def select
560   self[:select]
561 end
set_reciprocal_to_self?()

Whether to set the reciprocal association to self when loading associated records, false by default.

[show source] 
    # File lib/sequel/model/associations.rb
565 def set_reciprocal_to_self?
566   false
567 end
setter_method()

Name symbol for the setter association method

[show source] 
    # File lib/sequel/model/associations.rb
570 def setter_method
571   self[:setter_method]
572 end
slice_range(limit_and_offset = limit_and_offset())

The range used for slicing when using the :ruby eager limit strategy.

[show source] 
    # File lib/sequel/model/associations.rb
575 def slice_range(limit_and_offset = limit_and_offset())
576   limit, offset = limit_and_offset
577   if limit || offset
578     (offset||0)..(limit ? (offset||0)+limit-1 : -1)
579   end
580 end