Method: Sequel::Model::Associations::DatasetMethods#eager

Defined in:

lib/sequel/model/associations.rb

#eager(*associations) ⇒ Object

The preferred eager loading method. Loads all associated records using one query for each association.

The basic idea for how it works is that the dataset is first loaded normally. Then it goes through all associations that have been specified via eager. It loads each of those associations separately, then associates them back to the original dataset via primary/foreign keys. Due to the necessity of all objects being present, you need to use all to use eager loading, as it can’t work with each.

This implementation avoids the complexity of extracting an object graph out of a single dataset, by building the object graph out of multiple datasets, one for each association. By using a separate dataset for each association, it avoids problems such as aliasing conflicts and creating cartesian product result sets if multiple one_to_many or many_to_many eager associations are requested.

One limitation of using this method is that you cannot filter the current dataset based on values of columns in an associated table, since the associations are loaded in separate queries. To do that you need to load all associations in the same query, and extract an object graph from the results of that query. If you need to filter based on columns in associated tables, look at eager_graph or join the tables you need to filter on manually.

Each association’s order, if defined, is respected. If the association uses a block or has an :eager_block argument, it is used.

To modify the associated dataset that will be used for the eager load, you should use a hash for the association, with the key being the association name symbol, and the value being a callable object that is called with the associated dataset and should return a modified dataset. If that association also has dependent associations, instead of a callable object, use a hash with the callable object being the key, and the dependent association(s) as the value.

Examples:

# For each album, eager load the artist
Album.eager(:artist).all
# SELECT * FROM albums
# SELECT * FROM artists WHERE (id IN (...))

# For each album, eager load the artist and genre
Album.eager(:artist, :genre).all
Album.eager(:artist).eager(:genre).all
# SELECT * FROM albums
# SELECT * FROM artists WHERE (id IN (...))
# SELECT * FROM genres WHERE (id IN (...))

# For each artist, eager load albums and tracks for each album
Artist.eager(albums: :tracks).all
# SELECT * FROM artists
# SELECT * FROM albums WHERE (artist_id IN (...))
# SELECT * FROM tracks WHERE (album_id IN (...))

# For each artist, eager load albums, tracks for each album, and genre for each track
Artist.eager(albums: {tracks: :genre}).all
# SELECT * FROM artists
# SELECT * FROM albums WHERE (artist_id IN (...))
# SELECT * FROM tracks WHERE (album_id IN (...))
# SELECT * FROM genre WHERE (id IN (...))

# For each artist, eager load albums with year > 1990
Artist.eager(albums: proc{|ds| ds.where{year > 1990}}).all
# SELECT * FROM artists
# SELECT * FROM albums WHERE ((year > 1990) AND (artist_id IN (...)))

# For each artist, eager load albums and tracks 1-10 for each album
Artist.eager(albums: {tracks: proc{|ds| ds.where(number: 1..10)}}).all
# SELECT * FROM artists
# SELECT * FROM albums WHERE (artist_id IN (...))
# SELECT * FROM tracks WHERE ((number >= 1) AND (number <= 10) AND (album_id IN (...)))

# For each artist, eager load albums with year > 1990, and tracks for those albums
Artist.eager(albums: {proc{|ds| ds.where{year > 1990}}=>:tracks}).all
# SELECT * FROM artists
# SELECT * FROM albums WHERE ((year > 1990) AND (artist_id IN (...)))
# SELECT * FROM albums WHERE (artist_id IN (...))

# File 'lib/sequel/model/associations.rb', line 3181

def eager(*associations)
  opts = @opts[:eager]
  association_opts = eager_options_for_associations(associations)
  opts = opts ? opts.merge(association_opts) : association_opts
  clone(:eager=>opts.freeze)
end