Sequel中文文档-模型-关联基础

这份指南以guides.rubyonrails.org/association_basics.html为基础

为什么需要关联？

关联的存在，是使处理分开的数据表中相关行（记录）的编码工作变得简单。如果没有关联，你也许会写这样一些类：

class Artist < Sequel::Model
end
class Album < Sequel::Model
end

现在你想获取给定艺术家的所有唱片（假设每张唱片只和一个艺术家有关）：

Album.filter(:artist_id=>@artist.id).all

也许你想为给定的艺术家添加一张唱片：

Album.create(:artist_id=>@artist.id, :name=>'RF')

如果给两个模型设置关联的话，你可以简化上面的编码：

class Artist < Sequel::Model
one_to_many :albums
end
class Album < Sequel::Model
many_to_one :artist
end

获取与某一艺术家相关的唱片的代码简化成：

@artist.albums

为一个艺术家添加唱片：

@artist.add_album(:name=>'RF')

关联的类型

Sequel内建了4种不同的关联关系：

many_to_one（多对一）

one_to_many（一对多）

one_to_one（一对一）

many_to_many（多对多）

many_to_one

多对多关系用于：当前模型类包含外键，此外键引用了一个关联模型类的表的主键。这样命名是因为关联表中的任意一行能对应本表的多行：

# Database schema:
#  albums             artists
#   :id           /--> :id
#   :artist_id --/     :name
#   :name
class Album
# Uses singular form of associated model name
many_to_one :artist
end

one_to_many

一对多关系和多对一相反：关联模型类的表的一个外键引用了当前表的主键。这样命名是因为当前表的任意一行能对应关联表的多行：

# Database schema:
#  artists            albums
#   :id   <----\       :id
#   :name       \----- :artist_id
#                      :name
class Artist
# Uses plural form of associated model name
one_to_many :albums
end

one_to_one

一对一可以认为是一对多关系的子集，但只能与关联表中的0或1条记录相关联。这是四种关联关系中最常用的一种。如果你假定一个艺术家不能与多于一张的唱片相关联：

# Database schema:
#  artists            albums
#   :id   <----\       :id
#   :name       \----- :artist_id
#                      :name
class Artist
# Uses singular form of associated model name
one_to_one :album
end

many_to_many

多对多关系允许当前表中的每一行能与关联表中的多行相关联，同时也允许关联表中的每一行与当前表中的多行相关联。这需要一个联合表使两个表关联上。如果你假定一个艺术家可以有多张唱片，而每张唱片有可以同时属于多个艺术家：

# Database schema:
#  albums
#   :id   <----\
#   :name       \     albums_artists
#                \---- :album_id
#  artists       /---- :artist_id
#   :id   <-----/
#   :name
class Artist
# Uses plural form of associated model name
many_to_many :albums
end
class Album
many_to_many :artists
end

多对一和一对一的区别

如果你想给两个模型设置一对一关系，你需要在一个模型中使用many_to_one，而在另一个模型中使用one_to_one。你该如何确定哪个模型该使用哪种方法呢？
简单的做法是记住：哪个表有外键哪个表就使用many_to_one，另一个表就使用one_to_one：

# Database schema:
#  artists            albums
#   :id   <----\       :id
#   :name       \----- :artist_id
#                      :name
class Artist
one_to_one :album
end
class Album
many_to_one :artist
end

常用选项

:key

如果符号默认表示的列的不是你想使用的列，那么需要使用:key选项。举例来说：

class Album
# Assumes :key is :artist_id, based on association name of :artist
many_to_one :artist
end
class Artist
# Assumes :key is :artist_id, based on class name of Artist
one_to_many :albums
end

然而你的模式是这样的：

# Database schema:
#  artists            albums
#   :id   <----\       :id
#   :name       \----- :artistid # Note missing underscore
#                      :name

这时默认的:key是不正确的，就必须用:key选项来明确指出正确的:key：

class Album
many_to_one :artist, :key=>:artistid
end
class Artist
one_to_many :albumst, :key=>:artistid
end

对于多对多关联，:left_key和:right_key选项用来指定联合表的列名，:join_table选项则指定联合表的表名：

# Database schema:
#  albums
#   :id   <----\
#   :name       \     albumsartists
#                \---- :albumid
#  artists       /---- :artistid
#   :id   <-----/
#   :name
class Artist
# Note that :left_key refers to the foreign key pointing to the
# current table, and :right_key the foreign key pointing to the
# associated table.
many_to_many :albums, :left_key=>:artistid, :right_key=>:albumid,
:join_table=>:albumsartists
end
class Album
many_to_many :artists, :left_key=>:albumid, :right_key=>:artistid,
:join_table=>:albumsartists
end

:class

如果相关联的类的类名不能通过关联名直接猜测出来的话，你需要用:class明确指出类名。例如：在唱片表中你有两个独立的外键分别都指向了艺术家表，用来表明一个是歌手一个是作曲者。这时（因为无法直接猜测正确的类名）你就需要使用:class选项了：

# Database schema:
#  artists            albums
#   :id   <----\       :id
#   :name       \----- :vocalist_id
#                \---- :composer_id
#                      :name
class Album
many_to_one :vocalist, :class=>:Artist
many_to_one :composer, :class=>:Artist
end
class Artist
one_to_many :vocalist_albums, :class=>:Album, :key=>:vocalist_id
one_to_many :composer_albums, :class=>:Album, :key=>:composer_id
end

自引用关联

Sequel能够很容易地处理自引用关联关系。最简单的例子是树结构：

# Database schema:
#  nodes
#   :id        <--\
#   :parent_id ---/
#   :name
class Node
many_to_one :parent, :class=>self
one_to_many :children, :key=>:parent_id, :class=>self
end

在多对多关系中也是相当简单。这是一个有向图的例子：

# Database schema:
#  nodes              edges
#   :id   <----------- :successor_id
#   :name       \----- :predecessor_id
class Node
many_to_many :direct_successors, :left_key=>:successor_id,
:right_key=>:predecessor_id, :join_table=>:edges, :class=>self
many_to_many :direct_predecessors, :right_key=>:successor_id,
:left_key=>:predecessor_id, :join_table=>:edges, :class=>self
end

向关联中添加方法

创建了关联关系后，就需要给相关的类添加实力方法了。
在所有的关联关系中都会有一个跟关联同名的实例方法：

@artist.albums
@album.artists

多对一和一对一关联还会有一个setter方法，该方法能够修改相关联的对象：

@album.artist = Artist.create(:name=>'YJM')

多对多和一对多关联会有3个方法被添加：

add_* 为当前对象添加一个关联对象

remove_* 从当前对象上移除与另一对象的关联关系

remove_all_* 删除当前所有的关联

例如：

@artist.add_album(@album)
@artist.remove_album(@album)
@artist.remove_all_albums

缓存

当关联被取出后，它会被缓存起来：

@artist.album # Not cached - Database Query
@artist.album # Cached - No Database Query
@album.artists # Not cached - Database Query
@album.artists # Cached - No Database Query

通过给关联方法传入一个“true”，你可以忽略缓存而使用数据库请求来获得结果：

@album.artists # Not cached - Database Query
@album.artists # Cached - No Database Query
@album.artists(true) # Ignore cache - Database Query

如果你重新加载或刷新（reload/refresh）了对象，该对象的关联缓存会被自动清除：

@album.artists # Not cached - Database Query
@album.artists # Cached - No Database Query
@album.reload
@album.artists # Not Cached - Database Query

如果你想直接访问关联缓存，请使用associations实例方法：

@album.associations # {}
@album.associations[:artists] # nil
@album.artists # [<Artist ...>, ...]
@album.associations[:artists] # [<Artist ...>, ...]

数据集方法

除了上面的那些方法，关联还会添加一个以_dataset结尾的方法，该方法返回一个表示在关联表中的对象的数据集：

@album.artist_id
# 10
@album.artist_dataset
# SELECT * FROM artists WHERE (id = 10)
@artist.id
# 20
@artist.albums_dataset
# SELECT * FROM albums WHERE (artist_id = 20)

关联数据集和Sequel中的其他数据集一样，能够被进一步地过滤、排序等：

@artist.albums_dataset.
where(Sequel.like(:name, 'A%')).
order(:copies_sold).
limit(10)
# SELECT * FROM albums
# WHERE ((artist_id = 20) AND (name LIKE 'A%'))
# ORDER BY copies_sold LIMIT 10

通过_dataset方法检索的记录不会被缓存：

@album.artists_dataset.all # [<Artist ...>, ...]
@album.associations[:artists] # nil

动态修改关联

与_dataset类似，你可以给关联方法提供一个语句块来自定义想用来检索记录的数据集。你可以用以下两种方法使用过滤器：

@artist.albums_dataset.where(Sequel.like(:name, 'A%'))
@artist.albums{|ds| ds.where(Sequel.like(:name, 'A%'))}

While they both apply the same filter, using the _dataset method
does not apply any of the association callbacks or handle association reciprocals (see below for details about callbacks and reciprocals). Using a block instead handles all those things, and also caches its results in the associations cache (ignoring any previously
cached value).

通过关联过滤数据

除了使用关联方法去获得相关联的对象，你还可以将这些被关联的对象用于过滤器。例如，要获取给定的艺术家的唱片，你可能会这么做：

@artist.albums
# or @artist.albums_dataset for a dataset

也可以这样：

Album.where(:artist=>@artist).all
# or leave off the .all for a dataset

对一单个的关联关系这可能作用不大。和使用关联方法不同，使用过滤器能作用于多个关联关系中：

Album.where(:artist=>@artist, :publisher=>@publisher)

这会返回由那个发行商发行并且是那个艺术家的所有唱片，只使用关联方法是做不到的。虽然你可以使用组合方法来达到目的：

@artist.albums_dataset.where(:publisher=>@publisher)

这不仅可以应用于many_to_one关联，one_to_one、one_to_many、many_to_many同样可以：

Album.one_to_one :album_info
# The album related to that AlbumInfo instance
Album.where(:album_info=>AlbumInfo[2])
Album.one_to_many :tracks
# The album related to that Track instance
Album.where(:tracks=>Track[3])

Album.many_to_many :tags
# All albums related to that Tag instance
Album.where(:tags=>Tag[4])

注意在one_to_many和many_to_many关系中，即便只有一个对象，你也要使用复数形式。
你还可以通过关联排除某些数据：

Album.exclude(:artist=>@artist).all

这会返回所有不是那个艺术家的唱片。
还可以提供一个包含多个模型对象的数组：

Album.where(:artist=>[@artist1, @artist2]).all

和使用数字数组或字符串数组类似，这会返回所有属于这两个艺术家之一的唱片。用exclude方法能获取所有不是这两个艺术家之一的唱片：

Album.exclude(:artist=>[@artist1, @artist2]).all

如果用的是one_to_many或many_to_many关联，you
may want to return records where the records matches all of multiple records, instead of matching any of them. For example:

Album.where(:tags=>[@tag1, @tag2])

这会匹配关联于@tag1或@tag2或者两者皆关联的唱片。如果只想匹配两者皆关联的唱片，你可以使用两个独立的过滤器，像这样：

Album.where(:tags=>@tag1).where(:tags=>@tag2)

或者数组形式的条件说明符：

Album.where([[:tags, @tag1], [:tags, @tag2]])

这会返回同时关联于@tag1和@tag2的唱片。
过滤时还可以提供一个数据集：

Album.where(:artist=>Artist.where(Sequel.like(:name, 'A%'))).all

这会返回那些名字以“A”开头的艺术家的唱片。和其他形式一样，这也可以取其补集：

Album.exclude(:artist=>Artist.where(Sequel.like(:name, 'A%'))).all

这返回那些名字不以“A”开头的艺术家的唱片
注意通过关联来过滤数据只会正确工作在使用简单关联的时候，也就是那些不带条件表达式的关联。

命名冲突

关联会创建实例方法，因此当你有一个跟关联方法同名的实例方法时，这很可能会重写你的实例方法。比如values和associations就不是很好的命名。

数据库模式

创建关联并不会改变数据库的模式。Sequel假设你的关联反映了已经存在于数据库中的模式。如果不是的话，那你应该在创建关联之前改变你的数据库模式。

many_to_one/one_to_many

例如下面的模型的代码：

class Album
many_to_one :artist
end
class Artist
one_to_many :albums
end

或许你想要的是下面的数据库模式：

#  albums             artists
#   :id           /--> :id
#   :artist_id --/     :name
#   :name

用下面的Sequel代码可以创建它：

DB.create_table(:artists) do
# Primary key must be set explicitly
primary_key :id
String :name
end
DB.create_table(:albums) do
primary_key :id
# Table that foreign key references needs to be set explicitly
# for a database foreign key reference to be created.
foreign_key :artist_id, :artists
String :name
end

而此时你的模式是这样的：

# Database schema:
#  albums             artists
#   :id                :id
#   :name              :name

这时你就要像其中添加一列了：

DB.alter_table(:albums) do
add_foreign_key :artist_id, :artists
end

many_to_many

对于many_to_many关联，默认情况下关联表会使用两个模型的类名按字母排序后以下划线相连的字符串作为表名，例如下面的两个模型：

class Album
many_to_many :artists
end
class Artist
many_to_many :albums
end

默认的链接表的表名是albums_artists而不是artists_albums，因为：

["artists", "albums"].sort.join('_')
# "albums_artists"

假如你已经创建了albums和artists表，现在只是想再添加一个albums_artists连接表来完成如下的模式：

# Database schema:
#  albums
#   :id   <----\
#   :name       \     albums_artists
#                \---- :album_id
#  artists       /---- :artist_id
#   :id   <-----/
#   :name

你可以用下面的Sequel代码：

DB.create_join_table(:album_id=>:albums, :artist_id=>:artists)
# or
DB.create_table(:albums_artists) do
foreign_key :album_id, :albums
foreign_key :artist_id, :artists
end

关联的作用域

如果把Sequel::Model类嵌套到了模块中，这时你要清楚默认情况下Sequel的关联的可见性只存在于相同的模块中。因此下面的代码能够很好的运行：

module App
class Artist < Sequel::Model
one_to_many :albums
end
class Album < Sequel::Model
many_to_one :artist
end
end

然而，如果你把模型封装到了两个不同的模块里，默认情况下这是不会工作的：

module App1
class Artist < Sequel::Model
one_to_many :albums
end
end
module App2
class Album < Sequel::Model
many_to_one :artist
end
end

要解决这个问题你需要使用:class选项指出模型类的全名：

module App1
class Artist < Sequel::Model
one_to_many :albums, :class=>"App2::Album"
end
end
module App2
class Album < Sequel::Model
many_to_one :artist, :class=>"App1::Artist"
end
end

如果两个类在同一个模块，而默认名不对，也要用:class选项指出类的全名：

module App1
class AlbumArtist < Sequel::Model
one_to_many :albums
end
class Album < Sequel::Model
many_to_one :artist, :class=>"App1::AlbumArtist"
end
end

方法的详细信息

下面的这些方法，association会被你传给关联方法的符号替代。

association(reload = false) (e.g. albums)

对于many_to_one和one_to_one关联，association方法返回相关联的一个对象，或者nil（没找到关联对象）。

@artist = @album.artist

对于one_to_many和many_to_many关联，association方法以数组形式返回关联对象，没有对象是则返回空数组。

@albums = @artist.albums

association=(object_to_associate) (e.g. artist=) [many_to_one and one_to_one]

association=方法method sets up an association of the passed object to the current object. For many_to_one associations,
this sets the foreign key for the current object to point to the associated object's primary key.

@album.artist = @artist

For one_to_one associations, this sets the foreign key
of the associated object to the primary key value of the current object.
For many_to_one associations, this does not save the current
object. For one_to_one associations, this does save the associated object.

add_association(object_to_associate) (e.g. add_album) [one_to_many and many_to_many]

The add_association method associates the passed object to the current object. For one_to_many associations,
it sets the foreign key of the associated object to the primary key value of the current object, and saves the associated object. For many_to_many associations,
this inserts a row into the join table with the foreign keys set to the primary key values of the current and associated objects. Note that the singular form of the association name is used in this method.

@artist.add_album(@album)

In addition to passing an actual associated object, you can pass a hash, and a new associated object will be created from them:

@artist.add_album(:name=>'RF') # creates Album object

The add_association method returns the now associated object:

@album = @artist.add_album(:name=>'RF')

remove_association(object_to_disassociate) (e.g. remove_album) [one_to_many and many_to_many]

The remove_association method disassociates the the passed object from the current object. For one_to_many associations,
it sets the foreign key of the associated object to NULL, and saves the associated object. For many_to_many associations,
this deletes the matching row in the join table. Similar to the add_association method, the singular form of the association name is used in this method.

@artist.remove_album(@album)

Note that this does not delete @album from the database,
it only disassociates it from the @artist. To delete @album from
the database:

@album.destroy

The add_association and remove_association methods should be thought of as adding and removing from the association, not from the database.
In addition to passing the object directly to remove_association, you can also pass the associated object's primary key:

@artist.remove_album(10)

This will look up the associated object using the key, and remove that album.
The remove_association method returns the now disassociated object:

@album = @artist.remove_album(10)

remove_all_association (e.g. remove_all_albums) [one_to_many and many_to_many]

The remove_all_association method disassociates all currently associated objects. For one_to_many associations,
it sets the foreign key of all associated objects to NULL in a single query. For many_to_many associations,
this deletes all matching rows in the join table. Unlike the add_association and remove_association method, the plural form of the association name is used in this method. The remove_all_association method returns the number of rows
updated for one_to_many associations and the number of rows deleted formany_to_many associations:

@rows_modified = @artist.remove_all_albums

association_dataset (e.g. albums_dataset)

The association_dataset method returns a dataset that represents all associated objects. This dataset is like any other Sequel dataset,
in that it can be filtered, ordered, etc.:

ds = @artist.albums_dataset.where(Sequel.like(:name, 'A%')).order(:copies_sold)

Unlike most other Sequel datasets, association datasets have a couple of added methods:

ds.model_object # @artist
ds.association_reflection # same as Artist.association_reflection(:albums)

For a more info on Sequel's reflection capabilities see the Reflection page.

重写方法Overriding Method Behavior

Sequel is designed to be very flexible. If the default behavior of the association modification methods isn't what you desire, you can
override the methods in your classes. However, you should be aware that for each of the association modification methods described, there is a private method that is preceeded by an underscore that does the actual modification. The public method without the
underscore handles caching and callbacks, and shouldn't be overridden by the user.

_association=

Let's say you want to set a specific field whenever associating an object using the association setter method. For example, let's say you have a file_under column for each album to tell you where to file it. If the album is associated
with an artist, it should be filed under the artist's name and the album's name, otherwise it should just use the album's name.

class Album < Sequel::Model
many_to_one :artist
private

def _artist=(artist)
if artist
self.artist_id = artist.id
self.file_under = "#{artist.name}-#{name}"
else
self.artist_id = nil
self.file_under = name
end
end
end

The above example is contrived, as you would generally use a before_save model hook to handle such a modification. However, if you only modify the album's artist using the artist= method, this approach may perform better.

_add_association

Continuing with the same example, here's how would you handle the same case if you also wanted to handle the Artist#add_album method:

class Artist < Sequel::Model
one_to_many :albums
private

def _add_album(album)
album.update(:artist_id => id, :file_under=>"#{name}-#{album.name}")
end
end

_remove_association

Continuing with the same example, here's how would you handle the same case if you also wanted to handle the Artist#remove_album method:

class Artist < Sequel::Model
one_to_many :albums
private

def _remove_album(album)
album.update(:artist_id => nil, :file_under=>album.name)
end
end

_remove_all_association

Continuing with the same example, here's how would you handle the same case if you also wanted to handle the Artist#remove_all_albums method:

class Artist < Sequel::Model
one_to_many :albums
private

def _remove_all_albums
# This is Dataset#update, not Model#update, so the :file_under=>:name
# ends up being "SET file_under = name" in SQL.
albums_dataset.update(:artist_id => nil, :file_under=>:name)
end
end

关联的选项

大多数Sequel的关联都有相同的选项。为了便于理解，这里将它们单独成段。

修改关联的数据集的选项

block

All association defining methods take a block that is passed the default dataset and should return a modified copy of the dataset to use for the association. For example, if you wanted an association that returns all albums of an
artist that went gold (sold at least 500,000 copies):

Artist.one_to_many :gold_albums, :class=>:Album do |ds|
ds.where{copies_sold > 500000}
end

:class

This is the class of the associated objects that will be used. It's one of the most commonly used options. If it is not given, it guesses based on the name of the association. If a *_to_many association is used, uses the singular
form of the association name. For example:

Album.many_to_one :artist # guesses Artist
Artist.one_to_many :albums # guesses Album

However, for more complex associations, especially ones that add additional filters beyond the foreign/primary key relationships, the default class guessed will be wrong:

# guesses GoldAlbum
Artist.one_to_many :gold_albums do |ds|
ds.where{copies_sold > 500000}
end

You can specify the :class option using the class itself, a Symbol, or a String:

Album.many_to_one :artist, :class=>Artist # Class
Album.many_to_one :artist, :class=>:Artist # Symbol
Album.many_to_one :artist, :class=>"Artist" # String

:key

For many_to_one associations, is the foreign_key in current
model's table that references associated model's primary key, as a symbol. Defaults to :association_id. Can use an array of symbols for a composite key association.

Album.many_to_one :artist # :key=>:artist_id

For one_to_one and one_to_many associations,
is the foreign key in associated model's table that references current model's primary key, as a symbol. Defaults to :"#{self.name.underscore}_id".

Artist.one_to_many :albums # :key=>:artist_id

In both cases an array of symbols can be used for a composite key association:

Apartment.many_to_one :building # :key=>[:city, :address]

:conditions

The conditions to use to filter the association, can be any argument passed to where.
If you use a hash or an array of two element arrays, this will also be used as a filter when using eager_graph to load the association.

Artist.one_to_many :good_albums, :class=>:Album, :conditions=>{:good=>true}
@artist.good_albums
# SELECT * FROM albums WHERE ((artist_id = 1) AND (good IS TRUE))

:order

The column(s) by which to order the association dataset. Can be a singular column or an array.

Artist.one_to_many :albums_by_name, :class=>:Album,
:order=>:name
Artist.one_to_many :albums_by_num_tracks, :class=>:Album,
:order=>[:num_tracks, :name]

:select

The columns to SELECT when loading the association. For most associations, it defaults to nil, so * is used. For many_to_many associations,
it defaults to the associated class's table_name.*, which means it doesn't include the columns from the join table. This is to prevent the common issue where the join table includes columns with the same name as columns in the associated table, in which case
the joined table's columns would usually end up clobbering the values in the associated table. If you want to include the join table attributes, you can use this option, but beware that the join table columns can clash with columns from the associated table,
so you should alias any columns that have the same name in both the join table and the associated table. Example:

Artist.one_to_many :albums, :select=>[:id, :name]
Album.many_to_many :tags, :select=>[Sequel.expr(:tags).*, :albums_tags__number]

:limit

Limit the number of records to the provided value:

Artist.one_to_many :best_selling_albums, :class=>:Album,
:order=>:copies_sold, :limit=>5 # LIMIT 5

Use an array with two arguments for the value to specify a limit and an offset.

Artist.one_to_many :next_best_selling_albums, :class=>:Album,
:order=>:copies_sold, :limit=>[10, 5] # LIMIT 10 OFFSET 5

This probably doesn't make a lot of sense for *_to_one associations, though you could use it to specify an offset.

:join_table [many_to_many]

Name of table that includes the foreign keys to both the current model and the associated model, as a symbol. Defaults to the name of current model and name of associated model, pluralized, underscored, sorted, and joined with '_'.
Here's an example of the defaults:

Artist.many_to_many :albums # :join_table=>:albums_artists
Album.many_to_many :artists # :join_table=>:albums_artists
Person.many_to_many :colleges # :join_table=>:colleges_people

:left_key [many_to_many]

Foreign key in join table that points to current model's primary key, as a symbol. Defaults to :"#{model_name.underscore}_id".

Album.many_to_many :tags # :left_key=>:album_id

Can use an array of symbols for a composite key association.

:right_key [many_to_many]

Foreign key in join table that points to associated model's primary key, as a symbol. Defaults to :"#{association_name.singularize}_id".

Album.many_to_many :tags # :right_key=>:tag_id

Can use an array of symbols for a composite key association.

:distinct

Use the DISTINCT clause when selecting associating object, both when lazy loading and eager loading via eager (but not when using eager_graph).
This is most useful for many_to_many associations that use join tables that contain more than just the foreign keys, where you are storing additional information. For example, if you have a database of people, degree types, and colleges,
and you want to return all people from a given college, you may want to use :distinct so that if a person has two separate degrees from the same college, they won't show up twice.

:clone

The :clone option clones an existing association, taking the options you specified for that association, and making a copy of them for this association. Other options provided by this association are then merged into the cloned options.
This is commonly used if you have a bunch of similar associations that you want to DRY up:

one_to_many :english_verses, :class=>:LyricVerse, :key=>:lyricsongid,
:order=>:number, :conditions=>{:languageid=>1}
one_to_many :romaji_verses, :clone=>:english_verses, :conditions=>{:languageid=>2}
one_to_many :japanese_verses, :clone=>:english_verses, :conditions=>{:languageid=>3}

Note that for the final two asociations, you didn't have to specify the :class, :key, or :order options, as they were copied by the :clone option. By specifying the :conditions option for the final two associations, it overrides
the :conditions option of the first association, it doesn't attempt to merge them.
In addition to the options hash, the :clone option will copy a block argument from the existing situation. If you want a cloned association to not have the same block as the association you are cloning from, specify the :block=>nil
option in additon to the :clone option.

:dataset

This is generally only specified for custom associations that aren't based on primary/foreign key relationships. It should be a proc that is instance evaled to get the base dataset to use before the other options are applied.
Here's an example of an association of songs to artists through lyrics, where the artist can perform any one of four tasks for the lyric:

Album.one_to_many :songs, :dataset=>(proc do
Song.select_all(:songs).
join(Lyric, :id=>:lyricid,
id=>[:composer_id, :arranger_id, :vocalist_id, :lyricist_id])
end)
Artist.first.songs_dataset
# SELECT songs.* FROM songs
# INNER JOIN lyrics ON
#  lyrics.id = songs.lyric_id AND
#  1 IN (composer_id, arranger_id, vocalist_id, lyricist_id)

:extend

A module or array of modules to extend the dataset with. These are used to set up association extensions. For more information , please see the Advanced
Associations page.

:primary_key

The column that the :key option references, as a symbol. For many_to_one associations,
this column is in the associated table. For one_to_one and one_to_many associations,
this column is in the current table. In both cases, it defaults to the primary key of the table. Can use an array of symbols for a composite key association.

Artist.set_primary_key :arid
Artist.one_to_many :albums # :primary_key=>:arid
Album.one_to_many :artist # :primary_key=>:arid

:left_primary_key [many_to_many]

Column in current table that :left_key option points to, as a symbol. Defaults to primary key of current table.

Album.set_primary_key :alid
Album.many_to_many :tags # :left_primary_key=>:alid

Can use an array of symbols for a composite key association.

:right_primary_key [many_to_many]

Column in associated table that :right_key points to, as a symbol. Defaults to primary key of the associated table.

Tag.set_primary_key :tid
Album.many_to_many :tags # :right_primary_key=>:tid

Can use an array of symbols for a composite key association.

:join_table_block [many_to_many]

A proc that can be used to modify the dataset used in the add/remove/remove_all methods. It's separate from the association block, as that is called on a join of the join table and the associated table, whereas this option just applies
to the join table. It can be used to make sure additional columns are used when inserting, or that filters are used when deleting.

Artist.many_to_many :lead_guitar_albums, :join_table_block=>proc do |ds|
ds.where(:instrument_id=>5).set_overrides(:instrument_id=>5)
end

回调选项

All callbacks can be specified as a Symbol, Proc, or array of both/either specifying a callback to call. Symbols are interpreted as instance methods that are called with the associated object. Procs are called with the receiver as
the first argument and the associated object as the second argument. If an array is given, all of them are called in order.
Before callbacks are often used to check preconditions, they can return false to signal Sequel to abort the modification. If any before
callback returns false, the remaining before callbacks are not called and modification is aborted. Before callbacks are also commonly used to modify the current object or the associated object.
After callbacks are often used for notification (logging, email) after a successful modification has been made.

:before_add [one_to_many, many_to_many]

Called before adding an object to the association:

class Artist
# Don't allow adding an album to an artist if it has no tracks
one_to_many :albums, :before_add=>proc{|ar, al| false if al.num_tracks == 0}
end

:after_add [one_to_many, many_to_many]

Called after adding an object to the association:

class Artist
# Log all associations of albums to an audit logging table
one_to_many :albums, :after_add=>:log_add_album
private

def log_add_album(album)
DB[:audit_logs].insert(:log=>"Album #{album.inspect} associated to #{inspect}")
end
end

:before_remove [one_to_many, many_to_many]

Called before removing an object from the association:

class Artist
# Don't allow removing a self-titled album
one_to_many :albums, :before_remove=>proc{|ar, al| false if al.name == ar.name}
end

:after_remove [one_to_many, many_to_many]

Called after removing an object from the association:

class Artist
# Log all disassociations of albums to an audit logging table
one_to_many :albums, :after_remove=>:log_remove_album
private

def log_remove_album(album)
DB[:audit_logs].insert(:log=>"Album #{album.inspect} disassociated from #{inspect}")
end
end

:before_set [many_to_one, one_to_one]

Called before the _association= method is called to modify the objects:

class Album
# Don't associate the album with an artist if the year the album was
# released is less than the year the artist/band started.
many_to_one :artist, :before_set=>proc{|al, ar| false if al.year < ar.year_started}
end

:after_set [many_to_one, one_to_one]

Called after the _association= method is called to modify the objects:

class Album
# Log all disassociations of albums to an audit logging table
many_to_one :artist, :after_set=>:log_artist_set
private

def log_artist_set(artist)
DB[:audit_logs].insert(:log=>"Artist for album #{inspect} set to #{artist.inspect}")
end
end

:after_load

Called after retrieving the associated records from the database.

class Artist
# Cache all album names to a single string when retrieving the
# albums.
one_to_many :albums, :after_load=>:cache_album_names
attr_reader :album_names

private

def cache_album_names(albums)
@album_names = albums.map{|x| x.name}.join(", ")
end
end

Generally used if you know you will always want a certain action done when retrieving the association.
For one_to_many and many_to_many associations,
both the argument to symbol callbacks and the second argument to proc callbacks will be an array of associated objects instead of a single object.

:uniq [many_to_many]

Adds a after_load callback that makes the array of objects unique. In many cases, using the :distinct option is a better approach.

Eager Loading via eager (query per association) Options

:eager

The associations to eagerly load via eager when loading the associated object(s). This is useful for example if you always want to eagerly load dependent associations when loading this association.
For example, if you know that any time that you want to load an artist's albums, you are also going to want access to the album's tracks as well:

# Eager load tracks when loading the albums
Artist.one_to_many :albums, :eager=>:tracks

You can also use a hash or array to specify multiple dependent associations to eagerly load:

# Eager load the albums' tracks and the tracks' tags when loading the albums
Artist.one_to_many :albums, :eager=>{:tracks=>:tags}
# Eager load the albums' tags and tracks when loading the albums
Artist.one_to_many :albums, :eager=>[:tags, :tracks]
# Eager load the albums' tags, tracks, and tracks' tags when loading the albums
Artist.one_to_many :albums, :eager=>[:tags, {:tracks=>:tags}]

:eager_loader

A custom loader to use when eagerly load associated objects via eager. For many details and examples of custom eager loaders, please see the Advanced
Associations guide.

:eager_loader_key

A symbol for the key column to use to populate the key hash for the eager loader. Generally does not need to be set manually, defaults to the key method used. Can be set to nil to not populate the key hash (better for performance
if a custom eager loader does not use the key_hash).

:eager_block

If given, should be a proc to use instead of the association method block when eagerly loading. To not use a block when eager loading when one is used normally, should to nil. It's very uncommon to need this option.

Eager Loading via eager_graph (one query with joins) Options

:eager_graph

The associations to eagerly load via eager_graph when loading the associated object(s). This is useful for example if you always want to eagerly load dependent associations when loading this association, but you want to filter or
order the association based on dependent associations:

Artist.one_to_many :albums_with_short_tracks, :class=>:Album,
:eager_graph=>:tracks do |ds|
ds.where{tracks__seconds < 120}
end
Artist.one_to_many :albums_by_track_name, :class=>:Album,
:eager_graph=>:tracks do |ds|
ds.order(:tracks__name)
end

You can also use a hash or array of arguments for :eager_graph, similar to what the :eager option accepts.

:graph_conditions

The additional conditions to use on the SQL join when eagerly loading the association via eager_graph. Should be a hash or an array of two element arrays. If not specified, the :conditions option is used if it is a hash or array
of two element arrays.

Artist.one_to_many :active_albums, :class=>:Album,
:graph_conditions=>{:active=>true}

Note that these conditions on the association are in addition to the default conditions specified by the foreign/primary keys. If you want to replace the conditions specified by the foreign/primary keys, you need the :graph_only_conditions
options.

:graph_block

The block to pass to Dataset#join_table when eagerly loading the association via eager_graph. This is useful to specify conditions that can't be specified in a hash or array of two element arrays.

Artist.one_to_many :gold_albums, :class=>:Album,
:graph_block=>proc{|j,lj,js| Sequel.qualify(j, :copies_sold) > 500000}

:graph_join_type

The type of SQL join to use when eagerly loading the association via eager_graph. Defaults to :left_outer. This is useful if you want to ensure that only artists that have albums are returned:

Artist.one_to_many :albums, :graph_join_type=>:inner
# Will exclude artists without an album
Artist.eager_graph(:albums).all

:graph_select

A column or array of columns to select from the associated table when eagerly loading the association via eager_graph. Defaults to all columns in the associated table.

:graph_only_conditions

The conditions to use on the SQL join when eagerly loading the association via eager_graph, instead of the default conditions specified by the foreign/primary keys. This option causes the :graph_conditions option to be ignored. This
can be useful if the keys you are using are strings and you want to do a case insensitive comparison. For example, let's say that instead of integer keys, you used string keys based on the album or artist name, and that the album was associated to the artist
by name. However, you weren't enforcing case sensitivity between the keys, so you still want to return albums where the artist's name differs in case:

Artist.one_to_many :albums, :key=>:artist_name,
:graph_only_conditions=>nil,
:graph_block=>proc{|j,lj,js| {Sequel.function(:lower, Sequel.qualify(j, :artist_name))=>
Sequel.function(:lower, Sequel.qualify(lj, :name))}}

Note how :graph_only_conditions is set to nil to ignore any existing conditions, and :graph_block is used to set up the case insensitive comparison.
Another case where :graph_only_conditions may be used is if you want to use a JOIN USING or NATURAL JOIN for the graph:

# JOIN USING
Artist.one_to_many :albums, :key=>:artist_name,
:graph_only_conditions=>[:artist_name]
# NATURAL JOIN
Artist.one_to_many :albums, :key=>:artist_name,
:graph_only_conditions=>nil, :graph_join_type=>:natural

:graph_alias_base

The base name to use for the table alias when eager graphing. Defaults to the name of the association. If the alias name has already been used in the query, Sequel will
create a unique alias by appending a numeric suffix (e.g. alias_0, alias_1, ...) until the alias is unique.
This is mostly useful if you have associations with the same name in many models, and you want to be able to easily tell which table alias corresponds to which association when eagerly graphing multiple associations with the same
name.
You can override this option on a per-graph basis by specifying the association as an SQL::AliasedExpression instead of a symbol:

Album.eager_graph(Sequel.as(:artist, :a))

:eager_grapher

Sets up a custom grapher to use when eager loading the objects via eager_graph. This is the eager_graph analogue to the :eager_loader option. This isn't generally needed, as one of the other eager_graph related association options
is usually sufficient.
If specified, should be a proc that accepts a single hash argument, which will contain at least the following keys:

:self	The dataset that is doing the eager loading
:table_alias	An alias to use for the table to graph for this association.
:implicit_qualifier	The alias that was used for the current table (since you can cascade associations).
:callback	A callback proc used to dynamically modify the dataset to graph into the current dataset, before such graphing is done. This is nil if no callback proc is used.

Example:

Artist.one_to_many :self_title_albums, :class=>:Album,
:eager_grapher=>(proc do |eo|
eo[:self].graph(Album, {:artist_id=>:id, :name=>:name},
:table_alias=>eo[:table_alias], :implicit_qualifier=>eo[:implicit_qualifier])
end)

:order_eager_graph

Whether to add the order to the dataset's order when graphing via eager_graph. Defaults to true, so set to false to disable.
Sequel has to do some guess work when attempting to add the association's order to an eager_graphed dataset. In most cases it does so
correctly, but if it has problems, you'll probably want to set this option to false.

:graph_join_table_conditions [many_to_many]

The additional conditions to use on the SQL join for the join table when eagerly loading the association via eager_graph. Should be a hash or an array of two element arrays.
Let's say you have a database of people, colleges, and a table called degrees_received that includes a string field specifying the name of the degree, and you want to eager load all colleges for people where the person has received
a specific degree:

Person.many_to_many :bs_degree_colleges, :class=>:College,
:join_table=>:degrees_received,
:graph_join_table_conditions=>{:degree=>'BS'}

:graph_join_table_block [many_to_many]

The block to pass to join_table for the join table when eagerly loading the association via eager_graph. This is used for similar reasons as :graph_block, but is only used formany_to_many associations
when graphing the join table into the dataset. It's used in the same place as :graph_join_table_conditions but like :graph_block, is needed for situations where the conditions can't be specified as a hash or array of two element arrays.
Let's say you have a database of people, colleges, and a table called degrees_received that includes a string field specifying the name of the degree, and you want to eager load all colleges for people where the person has received
a bachelor's degree (degree starting with B):

Person.many_to_many :bachelor_degree_colleges, :class=>:College,
:join_table=>:degrees_received,
:graph_join_table_block=>proc{|j,lj,js| Sequel.qualify(j, :degree).like('B%')}

This should be done when graphing the join table, instead of when graphing the final table, as :degree is a column of the join table.

:graph_join_table_join_type [many_to_many]

The type of SQL join to use for the join table when eagerly loading the association via eager_graph. Defaults to the :graph_join_type option or :left_outer. This exists mainly for consistency in the unlikely case that you want to
use a different join type when JOINing to the join table then you want to use for JOINing to the final table

:graph_join_table_only_conditions [many_to_many]

The conditions to use on the SQL join for the join table when eagerly loading the association via eager_graph, instead of the default conditions specified by the foreign/primary keys. This option causes the :graph_join_table_conditions
option to be ignored. This is only useful if you want to replace the default foreign/primary key conditions that Sequel would use when eagerly graphing.

Column Naming Conflict Options

Sequel's association support historically called methods on model objects to get primary key or foreign key values instead of accessing the column values directly, in order to allow advanced features such as associations based on
virtual column keys. Unfortunately, that causes issues if columns are used with names that clash with existing method names, which can happen if you want to name the association the same name as an existing column, or if the column has the same name as an
already defined method such as object_id.
Sequel has added the following options that allow you to work around the issue by either specifying the column name symbol or the method
name symbol to use. In most cases, these methods are designed to be used with column aliases defined with Model.def_column_alias:

# Example schema:
#  albums           artists
#   :id        /-->  :id
#   :artist --/      :name
#   :name
class Album < Sequel::Model
def_column_alias(:artist_id, :artist)
many_to_one :artist, :key=>:artist_id, :key_column=>:artist
end
# Example schema:
#  things              objs
#   :id           /-->  :id
#   :object_id --/      :name
#   :name
class Thing < Sequel::Model
def_column_alias(:obj_id, :object_id)
end
class Obj < Sequel::Model
one_to_many :things, :key=>:object_id, :key_method=>:obj_id
end

:key_column [many_to_one]

Like the :key option, but :key references the method name, while :key_column references the underlying column.

:primary_key_method [many_to_one]

Like the :primary_key option, but :primary_key references the column name, while :primary_key_method references the method name.

:primary_key_column [one_to_many, one_to_one]

Like the :primary_key option, but :primary_key references the method name, while :primary_key_column references the underlying column.

:key_method [one_to_many, one_to_one]

Like the :key option, but :key references the column name, while :key_method references the method name.

:left_primary_key_column [many_to_many]

Like the :left_primary_key option, but :left_primary_key references the method name, while :left_primary_key_column references the underlying column.

:right_primary_key_method [many_to_many]

Like the :right_primary_key option, but :right_primary_key references the column name, while :right_primary_key_method references the method name.

高级选项

:reciprocal

The symbol name of the reciprocal association, if it exists. By default, Sequel will try to determine it by looking at the associated
model's assocations for a association that matches the current association's key(s). Set to nil to not use a reciprocal.
Reciprocals are used in Sequel to modify the matching cached associations in associated objects when calling association methods on
the current object. For example, when you retrieve objects in a one_to_many association, it'll automatically set the matching many_to_one association in the associated objects. The result of this is that code that does this:

@artist.albums.each{|album| album.artist.name}

only does one database query, because when the @artist's albums are retrieved, the cached artist association for each album is set to @artist.
In addition to the one_to_many retrieval case, the association modification methods affect the reciprocals as well:

# Sets the cached artist association for @album to @artist
@artist.add_album(@album)
# Sets the cached artist association for @album to nil
@artist.remove_album(@album)

# Sets the cached artist association to nil for the @artist's
# cached albums association
@artist.remove_all_albums

# Remove @album from the artist1's cached albums association, and add @album
# to @artist2's cached albums association.
@album.artist # @artist1
@album.artist = @artist2

Sequel can usually guess the correct reciprocal, but if you have multiple associations to the same associated class that use the same
keys, you may want to specify the :reciprocal option manually to ensure the correct one is used.

:read_only

For many_to_one and one_to_one associations,
do not add a setter method. For one_to_many and many_to_many,
do not add the add_association, remove_association, or remove_all_association methods.
If the default modification methods would not do what you want, and you don't plan on overriding the internal modification methods to do what you want, it may be best to set this option to true.

:validate

Set to false to not validate when implicitly saving any associated object. When using the one_to_many association
modification methods, the one_to_one setter method, or creating a new object by passing
a hash to the add_association method, Sequel will automatically save the object. If you don't want to validate objects when these implicit saves are done,
the validate option should be set to false.

:allow_eager

If set to false, you cannot load the association eagerly via eager or eager_graph.

Artist.one_to_many :albums, :allow_eager=>false
Artist.eager(:albums) # Raises Sequel::Error

This is usually used if the association dataset depends on specific values in model instance that would not be valid when eager loading for multiple instances.

:cartesian_product_number

The number of joins completed by this association that could cause more than one row for each row in the current table (default: 0 for *_to_one associations, 1 for *_to_many associations).
This should only be modified in specific cases. For example, if you have a one_to_one association that can actually return more than one row (where the default association method will just return the first), or a many_to_many association
where there is a unique index in the join table so that you know only one object will ever be associated through the association.

:methods_module

The module that the methods created by the association will be placed into. Defaults to the module containing the model's columns. This is not included in the model's class, so you are responsible for doing that manually.
This is only useful in rare cases, such as when a plugin that adds associations depends on another plugin that defines instance methods of the same name. In that case, the instance methods of the dependent plugin would override the
association methods created by the main plugin.

:eager_limit_strategy

This setting determines what strategy to use for loading the associations that use the :limit setting to limit the number of returned records. You can't use LIMIT directly, since you want a limit for each associated record, not a
LIMIT on the number of records returned by the dataset.
By default, no strategy is used for one_to_one associations, and the :ruby strategy is used for *_many associations, which does a simple array slice after loading the associated records. That doesn't provide a performance advantage,
since all records are still loaded from the database, but it at least makes sure the cached records are accurately limited as they would be in the lazy load case.
The reason no strategy is used by default for one_to_one associations is that none is needed for a true one_to_one association (since there is only one associated record per current record). However, if you are using a one_to_one
association where the relationship is really one_to_many, and using an order to pick the first matching row, then if you don't specify an :eager_limit_strategy option, you'll be loading all related rows just to have Sequel ignore
all rows after the first. By using a strategy to change the query to only return one associated record per current record, you can get much better database performance.
You can set a value of true for this option to have Sequel select
what it thinks is the best way of limiting the records for your database. You can also specify a symbol to manually choose a strategy. The available strategies are:

:distinct_on	Uses DISTINCT ON to ensure only the first matching record is loaded (one_to_one associations only). This is used by default on PostgreSQL.
:window_function	Uses window functions if the database supports it. This is used by default on databases that support window functions.
:correlated_subquery	Uses a correlated subquery to get the information. This is never used by default as if you aren't careful, it can result in pathologically long running times. This will not work correctly for associations where the associated table has a composite primary key if the database doesn't support using IN with multiple columns. This will also not work on MySQL because MySQL has problems using IN with a correlated subquery that contains a limit.
:ruby	Uses ruby array slicing to emulate database limiting (*_many associations only). This is the default if the database doesn't support window functions.