ash v0.1.3 Ash.Resource.Relationships View Source

DSL components for declaring relationships.

Relationships are a core component of resource oriented design. Many components of Ash will use these relationships. A simple use case is side_loading (done via the side_load option, given to an api action).

Link to this section Summary

Functions

Declares a belongs_to relationship. In a relational database, the foreign key would be on the source table.

Declares a has_many relationship. There can be any number of related entities.

Declares a has_one relationship. In a relationsal database, the foreign key would be on the other table.

Declares a many_to_many relationship. Many to many relationships require a join table.

Link to this section Functions

Link to this macro

belongs_to(relationship_name, destination, opts \\ [])

View Source (macro)

Declares a belongs_to relationship. In a relational database, the foreign key would be on the source table.

This creates a field on the resource with the corresponding name, unless define_field?: false is provided.

Practically speaking, a belongs_to and a has_one are interchangable in every way.

  • :destination_field - The field on the related resource that should match the source_field on this resource. The default value is :id.

  • :source_field - The field on this resource that should match the destination_field on the related resource. Default: [relationship_name]_id

  • :primary_key? - Whether this field is, or is part of, the primary key of a resource. The default value is false.

  • :define_field? - If set to false a field is not created on the resource for this relationship, and one must be manually added in attributes. The default value is true.

  • :field_type - The field type of the automatically created field. The default value is :uuid.

  • :reverse_relationship - A requirement for side loading data. Must be the name of an inverse relationship on the destination resource.

Examples

# In a resource called `Word`
belongs_to :dictionary_entry, DictionaryEntry,
  source_field: :text,
  destination_field: :word_text
Link to this macro

has_many(relationship_name, destination, opts \\ [])

View Source (macro)

Declares a has_many relationship. There can be any number of related entities.

  • :destination_field - The field on the related resource that should match the source_field on this resource. Default: [resource.name]_id

  • :source_field - The field on this resource that should match the destination_field on the related resource. The default value is :id.

  • :reverse_relationship - A requirement for side loading data. Must be the name of an inverse relationship on the destination resource.

Examples

# In a resource called `Word`
has_many :definitions, DictionaryDefinition,
  source_field: :text,
  destination_field: :word_text
Link to this macro

has_one(relationship_name, destination, opts \\ [])

View Source (macro)

Declares a has_one relationship. In a relationsal database, the foreign key would be on the other table.

Generally speaking, a has_one also implies that the destination table is unique on that foreign key.

Practically speaking, a has_one and a belongs_to are interchangable in every way.

  • :destination_field - The field on the related resource that should match the source_field on this resource. Default: [resource.name]_id

  • :source_field - The field on this resource that should match the destination_field on the related resource. The default value is :id.

  • :reverse_relationship - A requirement for side loading data. Must be the name of an inverse relationship on the destination resource.

Examples

# In a resource called `Word`
has_one :dictionary_entry, DictionaryEntry,
  source_field: :text,
  destination_field: :word_text
Link to this macro

many_to_many(relationship_name, destination, opts \\ [])

View Source (macro)

Declares a many_to_many relationship. Many to many relationships require a join table.

A join table is typically a table who's primary key consists of one foreign key to each resource.

You can specify a join table as a string or as another resource.

  • :source_field_on_join_table - The field on the join table that should line up with source_field on this resource. Default: [resource_name]_id

  • :destination_field_on_join_table - The field on the join table that should line up with destination_field on the related resource. Default: [relationshihp_name]_id

  • :source_field - The field on this resource that should line up with source_field_on_join_table on the join table. The default value is :id.

  • :destination_field - The field on the related resource that should line up with destination_field_on_join_table on the join table. The default value is :id.

  • :through - Required. The resource to use as the join resource.

  • :reverse_relationship - A requirement for side loading data. Must be the name of an inverse relationship on the destination resource.

Examples

# In a resource called `Word`
many_to_many :books, Book,
  through: BookWord,
  source_field: :text,
  source_field_on_join_table: :word_text,
  destination_field: :id,
  destination_field_on_join_table: :book_id