<commit_before>= Association Basics

This guide is based on http://guides.rubyonrails.org/association_basics.html

== Why Associations?

Associations exist to simplify code that deals with related rows in separate
database tables.  Without associations, if you had classes such as:

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

And you wanted to get all of the albums for a given artist (assuming each
album was associated with only one artist):

  Album.filter(:artist_id=>@artist.id).all
  
Or maybe you want to add an album for a given artist:

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

With Associations, you can make the above code simpler, by setting up associations
between the two models:
  
  class Artist < Sequel::Model
    one_to_many :albums
  end
  
  class Album < Sequel::Model
    many_to_one :artist
  end

Then, the code to retrieve albums related to the artist is simpler:

  @artist.albums
  
As is the code to add a related album to an artist:

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

It also makes it easier to creating queries that use joins based on the association:

  Artist.association_join(:albums)
  # SELECT * FROM artists
  # INNER JOIN albums ON (albums.artist_id = artists.id)

== The Types of Associations

Sequel has five different association types built in:

* many_to_one
* one_to_many
* one_to_one
* many_to_many
* one_through_one

It ships with additional association types via plugins.

=== many_to_one

The many_to_one association is used when the table for the current class
contains a foreign key that references the primary key in the table for the
associated class.  It is named because there can be many rows in the current
table for each row in the associated table.

  # 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 and one_to_one

The one_to_many association is used when the table for the associated class
contains a foreign key that references the primary key in the table for the
current class.  It is named because for each row in the current table there
can be many rows in the associated table:

The one_to_one association can be thought of as a subset of the one_to_many association,
but where there can only be either 0 or 1 records in the associated table.  This is
useful if there is a unique constraint on the foreign key field in the associated table.
It's also useful if you want to impose an order on the association and just want the
first record returned.

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

  class Artist
    # Uses plural form of associated model name
    one_to_many :albums

    # Uses singular form of associated model name
    one_to_one :album
  end

=== many_to_many and one_through_one

The many_to_many association allows each row in the current table to be associated
to many rows in the associated table, and each row in the associated table to
many rows in the current table, by using a join table to associate the two tables.
If you assume each artist can have multiple albums and each album can have multiple
artists:

The one_through_one association can be thought of as a subset of the many_to_many
association, but where there can only be 0 or 1 records in the associated table.
This is useful if there is a unique constraint on the foreign key in the join table
that refrences the current table.  It's also useful if you want to impose an order
on the association and just want the first record returned.  The one_through_one
association is so named because it sets up a one-to-one association through a
single join table.

  # 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

    # Uses plural form of associated model name
    one_through_one :album
  end

=== Differences Between many_to_one and one_to_one

If you want to setup a 1-1 relationship between two models, where the
foreign key in one table references the associated table directly, you have to use
many_to_one in one model, and one_to_one in the other model.  How do you
know which to use in which model?

The simplest way to remember is that the model whose table has the foreign
key uses many_to_one, and the other model uses one_to_one:

  # Database schema:
  #  artists            albums
  #   :id   <----\       :id<commit_msg>Fix documentation typo (Fixes #789)<commit_after>= Association Basics

This guide is based on http://guides.rubyonrails.org/association_basics.html

== Why Associations?

Associations exist to simplify code that deals with related rows in separate
database tables.  Without associations, if you had classes such as:

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

And you wanted to get all of the albums for a given artist (assuming each
album was associated with only one artist):

  Album.filter(:artist_id=>@artist.id).all
  
Or maybe you want to add an album for a given artist:

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

With Associations, you can make the above code simpler, by setting up associations
between the two models:
  
  class Artist < Sequel::Model
    one_to_many :albums
  end
  
  class Album < Sequel::Model
    many_to_one :artist
  end

Then, the code to retrieve albums related to the artist is simpler:

  @artist.albums
  
As is the code to add a related album to an artist:

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

It also makes it easier to creating queries that use joins based on the association:

  Artist.association_join(:albums)
  # SELECT * FROM artists
  # INNER JOIN albums ON (albums.artist_id = artists.id)

== The Types of Associations

Sequel has five different association types built in:

* many_to_one
* one_to_many
* one_to_one
* many_to_many
* one_through_one

It ships with additional association types via plugins.

=== many_to_one

The many_to_one association is used when the table for the current class
contains a foreign key that references the primary key in the table for the
associated class.  It is named because there can be many rows in the current
table for each row in the associated table.

  # 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 and one_to_one

The one_to_many association is used when the table for the associated class
contains a foreign key that references the primary key in the table for the
current class.  It is named because for each row in the current table there
can be many rows in the associated table:

The one_to_one association can be thought of as a subset of the one_to_many association,
but where there can only be either 0 or 1 records in the associated table.  This is
useful if there is a unique constraint on the foreign key field in the associated table.
It's also useful if you want to impose an order on the association and just want the
first record returned.

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

  class Artist
    # Uses plural form of associated model name
    one_to_many :albums

    # Uses singular form of associated model name
    one_to_one :album
  end

=== many_to_many and one_through_one

The many_to_many association allows each row in the current table to be associated
to many rows in the associated table, and each row in the associated table to
many rows in the current table, by using a join table to associate the two tables.
If you assume each artist can have multiple albums and each album can have multiple
artists:

The one_through_one association can be thought of as a subset of the many_to_many
association, but where there can only be 0 or 1 records in the associated table.
This is useful if there is a unique constraint on the foreign key in the join table
that refrences the current table.  It's also useful if you want to impose an order
on the association and just want the first record returned.  The one_through_one
association is so named because it sets up a one-to-one association through a
single join table.

  # 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

    # Uses singular form of associated model name
    one_through_one :album
  end

=== Differences Between many_to_one and one_to_one

If you want to setup a 1-1 relationship between two models, where the
foreign key in one table references the associated table directly, you have to use
many_to_one in one model, and one_to_one in the other model.  How do you
know which to use in which model?

The simplest way to remember is that the model whose table has the foreign
key uses many_to_one, and the other model uses one_to_one:

  # Database schema:
  #  artists            albums
  #   :id   <----\       :id
{'fraction_non_alphanumeric': 0.05059710873664362, 'fraction_numerical': 0.0015713387806411063, 'mean_word_length': 3.167175905718027, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5654095', 'n_tokens_mistral': 2718, 'n_tokens_neox': 2653, 'n_words': 1333}