Declare a many-to-one association (the parent holds the foreign key); put receives at most one child. related is a thunk (see has_many).

Writable: put_assoc/cast_assoc insert the referenced row first, then set the parent’s foreign_key to the referenced row’s child_key. Pass a 0- or 1-element list ([] sets the foreign key to NULL).

Default column values applied to newly-inserted children (overridden by the child changeset’s own changes).

Declare a one-to-many association; put receives every matched child.

related is a thunk (fn() -> Schema(child)), not a Schema, so that mutually-referential schemas don’t recurse forever while being constructed — the related schema is built only when the association is used.

Declare a has-many-through association: reach leaf rows via an intermediate mid (Ecto’s has_many :x, through: [:mid, :leaf]). Two-hop, read-only.

parent_key/mid_owner_key join the parent to the mid (the mid’s via_foreign_key column equals the parent’s key); mid_key/leaf_owner_key join the mid to the leaf (the leaf’s to_foreign_key column equals the mid’s key). put attaches the collected leaves to the parent.

Declare a one-to-one association owned by the parent; put receives at most one child. related is a thunk (see has_many).

Add a JOIN derived from a declared association (Ecto’s join: c in assoc(p, :comments)): the child table and the ON child.fk = parent.<key> come from the association on schema, which is the query’s from binding (binding 0). Use it to filter or select by a joined table without spelling the join condition by hand — the joined child sits at the next binding (1 for the first join), so reference its columns with expr.Col(1, "..."):

use q <- result.try( query.from(“posts”, “p”) |> association.join(post_schema(), “comments”, query.InnerJoin, “c”), ) query.where(q, expr.is_nil(expr.Col(1, “deleted_at”)))

Error if the association isn’t joinable: an unknown name, a belongs_to without owner_column, or many_to_many/through (use repo.query_raw).

Map a database constraint violation on the many_to_many join table to a field-level changeset error (Ecto’s unique_constraint declared on the join schema). name is the constraint’s database name exactly as the engine reports it; when inserting a new link violates it, repo.insert/repo.update roll the whole write back and return Error(ChangesetInvalid(..)) with one error keyed on the association (e.g. "tags"), carrying message plus constraint/constraint_kind metadata (like changeset.unique_constraint row mapping) and association/join_child_key metadata (like join_row_checked rejections) identifying which child’s link collided. A violation of an undeclared constraint still propagates as the raw ConstraintError.

Engines report names differently, so declare one per engine you run on (calls accumulate):

• Postgres reports the constraint/index name — UNIQUE (post_id, tag_id) on posts_tags auto-names it "posts_tags_post_id_tag_id_key".

• SQLite reports the violated columns as "<table>.<column>" joined by ", " — e.g. "posts_tags.post_id, posts_tags.tag_id".

  association.options() |> association.join_constraint( name: “posts_tags_post_id_tag_id_key”, // Postgres message: “has already been taken”, ) |> association.join_constraint( name: “posts_tags.post_id, posts_tags.tag_id”, // SQLite message: “has already been taken”, )

Matching is by name, so any constraint the database enforces on the join table (unique, foreign-key, check) can be declared; the violated kind is reported in constraint_kind metadata. Unlike join_row_checked (which checks every link before any row is written), the database reports the first offending insert, so one link’s error is returned per attempt — the transaction rollback still leaves no partial rows.

Extra column values written on each inserted many_to_many join-table row — for a join table with more than the two foreign keys (Ecto’s :join_through with a schema). Columns with a database default can be omitted (the database fills them); supply the rest here. Static values only — use join_row for per-link computed columns, or join_row_checked when a link can be rejected with field errors.

Compute extra many_to_many join-table columns per link, from the parent and the specific child being linked (Ecto’s :join_through with a schema, where the join row carries its own data). The returned columns are merged over join_defaults (so a computed value overrides a static one). Use it for per-membership data — a role, a position, an app-computed timestamp. Only applied to newly-inserted links. Declaring both join_row and join_row_checked keeps whichever was applied last.

association.options() |> association.join_row(with: fn(team: Team, user: User) { [#(“role”, value.VString(default_role(team, user)))] })

Like join_row, but the per-link computation can reject the link with field-level errors (Ecto’s join-through-a-schema changeset). Return Ok(columns) to accept — merged over join_defaults exactly like join_row — or Error([#("column", FieldError(..))]) to reject. Every new link is checked before any join row is inserted; if any link is rejected the whole repo.insert/repo.update transaction rolls back and the caller gets Error(ChangesetInvalid(errors)), each error keyed "<assoc>.<column>" (e.g. "tags.role") with association and join_child_key metadata identifying which child’s link failed. Invalid child changesets are reported with the same key shape, tagged child_index instead of join_child_key (see changeset.put_assoc). Declaring both join_row and join_row_checked keeps whichever was applied last. For constraints the database enforces on the join table (e.g. a unique (owner, related) index), declare join_constraint instead.

association.options() |> association.join_row_checked(with: fn(team: Team, user: User) { case role_for(team, user) { Ok(role) -> Ok([#(“role”, value.VString(role))]) Error(_) -> Error([ #(“role”, error.FieldError(“is invalid”, [#(“validation”, “inclusion”)])), ]) } })

Declare a many-to-many association through a join table (Ecto’s many_to_many :x, join_through: "..."). Writable.

join_owner_key/join_related_key are the join-table column names that reference the parent and the child respectively; owner_key reads the parent’s key (matched against join_owner_key); child_key reads the child’s key (matched against join_related_key).

put_assoc/cast_assoc upsert the children, then add/remove join rows to match (honoring on_replace); on_delete(DeleteAll) removes this owner’s join rows when the parent is deleted (the children themselves are untouched). A database constraint violated by a new join row maps to a field error on the association when declared with join_constraint; otherwise it surfaces as the raw ConstraintError.

Set the on_delete policy (has_many/has_one cascade on repo.delete).

Set the on_replace policy (has_many/has_one writes).

Default options: no extra filter, no ordering, ReplaceRaise, DeleteNothing, no defaults, no explicit join column.

The parent-side column the join preload matches on (preload.join). Only needed for belongs_to, where the join keys off the parent’s foreign key (owner_column("author_id") to pair with owner_key: row.author_id); has_many/has_one default to the parent’s primary key. Without it, a belongs_to is not join-preloadable and preload.join falls back to an error pointing at preload.one.

Order the preloaded children.

Apply a list of named preloads to parents, resolving each against the schema’s registered associations. Used by repo.preload.

Run one or more preload.joins through a single combined query. Each association’s contributor appends its JOIN(s) and prefixed child columns to a shared query — binding ranges allocate sequentially because every contributor reads query.last_binding of the query so far — so N join preloads become one query with N (or more) joins. The query runs once, the parents are deduplicated by primary key, and each association’s collector splits its own children out of the shared rows (deduping the cartesian repetition the sibling joins produce) and attaches them. With a single join preload this is the same one-join query as before.

The hop columns for a has_many :through join preload, when the hops don’t go via primary keys. parent_column is the parent column the intermediate’s via_foreign_key references (default: the parent’s primary key); mid_column is the intermediate column the leaf’s to_foreign_key references (default: the intermediate’s primary key). The batched through loader already keys off the value extractors, so this only affects the JOIN’s ON clauses. Pass the actual hop columns (a primary key is fine).

Add an extra filter applied when preloading this association. The expression references the child source at binding 0.