Associations: what should they look like?

[sgrif]

Let's talk about associations. First what's in the public API today, what's in the private API today, and what they actually need to do. We can use those things to drive what the API should look like.

Public API today

Right now Table has inner_join and left_outer_join which can take any other table which implements JoinTo. This is limited to exactly one table today, due to some limitations that I think will be resolved by specialization. There also needs to be some boilerplate implementations of SelectableExpression for all the various types of query sources, which will go away when specialization (or rust-lang/rust#29864) lands and replaced with:

impl<Left, Right, ST, T> SelectableExpression<InnerJoinSource<Left, Right>, ST>
    for T where
    T: SelectableExpression<Left, ST>,
    Left: JoinTo<Right>,
{}

impl<Left, Right, ST, T> SelectableExpression<InnerJoinSource<Left, Right>, ST>
    for T where
    T: SelectableExpression<Right, ST>,
    Left: JoinTo<Right>,
{}

This will also basically allow us to implement the join methods on the various join sources as well, though we might need to do some tuple hackery.

Private API today

The annotations #[has_many] and #[belongs_to] are part of the internal API today. Both implement JoinTo automatically. belongs_to additionally implements BelongingToDsl<Parent> for the child. I wrote up some thoughts on where that is today at #86 (comment).

What do Associations actually need to do?

Ultimately we're either eager loading the children for a collection of parents, or we're loading the children for a single parent. I believe that BelongingTo sufficiently handles the latter, but it'll effectively be handled by the former.

One To Many

I'm pretty reasonably confident that associations should be non invasive (user doesn't know it has many posts). That means that the type of a user and all of its posts is (User, Vec<Post>). This can get tricky when dealing with multiple levels of nesting here. For example, the type of a user, all the posts they've written, and all the comments written by that user is (User, Vec<Post>, Vec<Comment>). By contrast, the type of a user, all of the posts they've written, and all of the comments left on each of those posts would be (User, Vec<(Post, Vec<Comment>)>).

I'd imagine the way to specify that you want to load the comments for the posts and not for the users is by writing users.left_outer_join(posts.left_outer_join(comments)) as opposed to users.left_outer_join(posts).left_outer_join(comments).

The case of a user and all of its posts would be written today as:

users.left_outer_joins(posts::table).load(&connection)
    .group_by(|(user, post)| user)
    .map(|(user, posts)| posts.into_iter().filter_map(|p| p).collect())
    .collect()

The case involving comments is effectively impossible today.

We do not need to have specific code to handle loading the children for a single record, as Post::belonging_to(&user) is sufficient.

It should also be noted that I don't want to restrict what you're able to work with. We should be able to get a user, and the title of all of their posts by doing users.left_outer_joins(posts::table).select((users.all_columns(), posts::title)).

One To One

The type of a one to one relationship is either (A, B) or (A, Option<B>). Technically only a belongs_to can be mandatory, but you can still end up with the first signature with an inner join. Regardless of if we're going child to parent or parent to child, the way this is written today is simply:

users.inner_join(profile)

And loading a single record is handled by Post::belonging_to(&user). I do not believe we need any additional code to handle this case, but we could potentially rename the join methods to have parity with whatever we come up with for one to many.

Composition

Associations should be composable. If we want to get all of the comments that have been written for any posts written by a user, we should be able to re-use our existing logic, without having to actually load the posts.

[sgrif]

@mfpiccolo @mikeastock @samphippen @mcasper Would like to get some discussion going on this.

[mfpiccolo]

Thanks for putting this together @sgrif.

One to many:
The idea here is to handle the grouping and mapping into the expected Vec

's internally correct?

Currently we have:
users.left_outer_join(posts).load(&conn).unwrap().collect() // Vec<(User, Option<Post>)>
but we want this to return: Vec<(User, Vec<Post>)>

What you have here makes sense to me as well:
users.left_outer_join(posts.left_outer_join(comments)) // Vec<(User, Vec<(Post, Vec<Comment>)>)>
users.left_outer_join(posts).left_outer_join(comments) // Vec<(User, Vec<Post>, Vec<Comment>)>

[sgrif]

I'm moving this to 0.6, as SQLite support is more immediately actionable.

[sgrif]

The first pass was released in 0.7, but I'm leaving this open as I think there's still more work to be done.

[beefsack]

Have been using the current iteration of associations and has been working really well in my testing.

One case I'm not sure the current implementation covers is as below; having multiple belongs_to for through different fields to the same table.

#[derive(Debug, PartialEq, Clone, Queryable, Identifiable, Associations)]
#[belongs_to(User, foreign_key="source_user_id")]
#[belongs_to(User, foreign_key="target_user_id")]
pub struct Friend {
    pub id: Uuid,
    pub created_at: NaiveDateTime,
    pub updated_at: NaiveDateTime,
    pub source_user_id: Uuid,
    pub target_user_id: Uuid,
    pub has_accepted: Option<bool>,
}

The error is:

file: 'file:///...%3CBelongsTo%20macros%3E'
severity: 'Error'
message: 'conflicting implementations of trait `diesel::associations::BelongsTo<db::models::User>` for type `db::models::Friend`:
conflicting implementation for `db::models::Friend`'
at: '37,1'
source: 'rustc'

I'm not seeing these sorts of relationships defined in the issue description so thought I would bring it up.