Relations¶

Fluent's model API helps you create and maintain references between your models through relations. Three types of relations are supported:

Parent / Child (One-to-one)
Parent / Children (One-to-many)
Siblings (Many-to-many)

Parent¶

The @Parent relation stores a reference to another model's @ID property.

final class Planet: Model {
    // Example of a parent relation.
    @Parent(key: "star_id")
    var star: Star
}

@Parent contains a @Field named id which is used for setting and updating the relation.

// Set parent relation id
earth.$star.id = sun.id

For instance, the Planet initializer would look like:

init(name: String, starID: Star.IDValue) {
    self.name = name
    // ...
    self.$star.id = starID
}

The key parameter defines the field key to use for storing the parent's identifier. Assuming Star has a UUID identifier, this @Parent relation is compatible with the following field definition.

.field("star_id", .uuid, .required, .references("star", "id"))

Note that the .references constraint is optional. See schema for more information.

Optional Parent¶

The @OptionalParent relation stores an optional reference to another model's @ID property. It works similarly to @Parent but allows for the relation to be nil.

final class Planet: Model {
    // Example of an optional parent relation.
    @OptionalParent(key: "star_id")
    var star: Star?
}

The field definition is similar to @Parent's except that the .required constraint should be omitted.

.field("star_id", .uuid, .references("star", "id"))

Encoding and Decoding of Parents¶

One thing to watch out for when working with @Parent relations is the way that you send and receive them. For example, in JSON, a @Parent for a Planet model might look like this:

{
    "id": "A616B398-A963-4EC7-9D1D-B1AA8A6F1107",
    "star": {
        "id": "A1B2C3D4-1234-5678-90AB-CDEF12345678"
    }
}

Note how the star property is an object rather than the ID that you might expect. When sending the model as an HTTP body, it needs to match this for decoding to work. For this reason, we strongly recommend using a DTO to represent the model when sending it over the network. For example:

struct PlanetDTO: Content {
    var id: UUID?
    var name: String
    var star: Star.IDValue
}

Then you can decode the DTO and convert it into a model:

let planetData = try req.content.decode(PlanetDTO.self)
let planet = Planet(id: planetData.id, name: planetData.name, starID: planetData.star)
try await planet.create(on: req.db)

The same applies when returning the model to clients. Your clients either need to be able to handle the nested structure, or you need to convert the model into a DTO before returning it. For more information about DTOs, see the Model documentation

Optional Child¶

The @OptionalChild property creates a one-to-one relation between the two models. It does not store any values on the root model.

final class Planet: Model {
    // Example of an optional child relation.
    @OptionalChild(for: \.$planet)
    var governor: Governor?
}

The for parameter accepts a key path to a @Parent or @OptionalParent relation referencing the root model.

A new model can be added to this relation using the create method.

// Example of adding a new model to a relation.
let jane = Governor(name: "Jane Doe")
try await mars.$governor.create(jane, on: database)

This will set the parent id on the child model automatically.

Since this relation does not store any values, no database schema entry is required for the root model.

The one-to-one nature of the relation should be enforced in the child model's schema using a .unique constraint on the column referencing the parent model.

try await database.schema(Governor.schema)
    .id()
    .field("name", .string, .required)
    .field("planet_id", .uuid, .required, .references("planets", "id"))
    // Example of unique constraint
    .unique(on: "planet_id")
    .create()

Warning

Omitting the unique constraint on the parent ID field from the client's schema can lead to unpredictable results. If there is no uniqueness constraint, the child table may wind up containing more than one child row for any given parent; in this case, an @OptionalChild property will still only be able to access one child at a time, with no way of controlling which child is loaded. If you may need to store multiple child rows for any given parent, use @Children instead.

Children¶

The @Children property creates a one-to-many relation between two models. It does not store any values on the root model.

final class Star: Model {
    // Example of a children relation.
    @Children(for: \.$star)
    var planets: [Planet]
}

The for parameter accepts a key path to a @Parent or @OptionalParent relation referencing the root model. In this case, we are referencing the @Parent relation from the previous example.

New models can be added to this relation using the create method.

// Example of adding a new model to a relation.
let earth = Planet(name: "Earth")
try await sun.$planets.create(earth, on: database)

This will set the parent id on the child model automatically.

Since this relation does not store any values, no database schema entry is required.

Siblings¶

The @Siblings property creates a many-to-many relation between two models. It does this through a tertiary model called a pivot.

Let's take a look at an example of a many-to-many relation between a Planet and a Tag.

enum PlanetTagStatus: String, Codable { case accepted, pending }

// Example of a pivot model.
final class PlanetTag: Model {
    static let schema = "planet+tag"

    @ID(key: .id)
    var id: UUID?

    @Parent(key: "planet_id")
    var planet: Planet

    @Parent(key: "tag_id")
    var tag: Tag

    @OptionalField(key: "comments")
    var comments: String?

    @OptionalEnum(key: "status")
    var status: PlanetTagStatus?

    init() { }

    init(id: UUID? = nil, planet: Planet, tag: Tag, comments: String?, status: PlanetTagStatus?) throws {
        self.id = id
        self.$planet.id = try planet.requireID()
        self.$tag.id = try tag.requireID()
        self.comments = comments
        self.status = status
    }
}

Any model which includes at least two @Parent relations, one for each model to be related, can be used as a pivot. The model may contain additional properties, such as its ID, and may even contain other @Parent relations.

Adding a unique constraint to the pivot model can help prevent redundant entries. See schema for more information.

// Disallows duplicate relations.
.unique(on: "planet_id", "tag_id")

Once the pivot is created, use the @Siblings property to create the relation.

final class Planet: Model {
    // Example of a siblings relation.
    @Siblings(through: PlanetTag.self, from: \.$planet, to: \.$tag)
    public var tags: [Tag]
}

The @Siblings property requires three parameters:

through: The pivot model's type.
from: Key path from the pivot to the parent relation referencing the root model.
to: Key path from the pivot to the parent relation referencing the related model.

The inverse @Siblings property on the related model completes the relation.

final class Tag: Model {
    // Example of a siblings relation.
    @Siblings(through: PlanetTag.self, from: \.$tag, to: \.$planet)
    public var planets: [Planet]
}

Siblings Attach¶

The @Siblings property has methods adding and removing models from the relation.

Use the attach() method to add a single model or an array of models to the relation. Pivot models are created and saved automatically as needed. A callback closure may be specified to populate additional properties of each pivot created:

let earth: Planet = ...
let inhabited: Tag = ...
// Adds the model to the relation.
try await earth.$tags.attach(inhabited, on: database)
// Populate pivot attributes when establishing the relation.
try await earth.$tags.attach(inhabited, on: database) { pivot in
    pivot.comments = "This is a life-bearing planet."
    pivot.status = .accepted
}
// Add multiple models with attributes to the relation.
let volcanic: Tag = ..., oceanic: Tag = ...
try await earth.$tags.attach([volcanic, oceanic], on: database) { pivot in
    pivot.comments = "This planet has a tag named \(pivot.$tag.name)."
    pivot.status = .pending
}

When attaching a single model, you can use the method parameter to choose whether or not the relation should be checked before saving.

// Only attaches if the relation doesn't already exist.
try await earth.$tags.attach(inhabited, method: .ifNotExists, on: database)

Use the detach method to remove a model from the relation. This deletes the corresponding pivot model.

// Removes the model from the relation.
try await earth.$tags.detach(inhabited, on: database)

You can check if a model is related or not using the isAttached method.

// Checks if the models are related.
earth.$tags.isAttached(to: inhabited)

Get¶

Use the get(on:) method to fetch a relation's value.

// Fetches all of the sun's planets.
sun.$planets.get(on: database).map { planets in
    print(planets)
}

// Or

let planets = try await sun.$planets.get(on: database)
print(planets)

Use the reload parameter to choose whether or not the relation should be re-fetched from the database if it has already been already loaded.

try await sun.$planets.get(reload: true, on: database)

Query¶

Use the query(on:) method on a relation to create a query builder for the related models.

// Fetch all of the sun's planets that have a naming starting with M.
try await sun.$planets.query(on: database).filter(\.$name =~ "M").all()

See query for more information.

Eager Loading¶

Fluent's query builder allows you to preload a model's relations when it is fetched from the database. This is called eager loading and allows you to access relations synchronously without needing to call get first.

To eager load a relation, pass a key path to the relation to the with method on query builder.

// Example of eager loading.
Planet.query(on: database).with(\.$star).all().map { planets in
    for planet in planets {
        // `star` is accessible synchronously here 
        // since it has been eager loaded.
        print(planet.star.name)
    }
}

// Or

let planets = try await Planet.query(on: database).with(\.$star).all()
for planet in planets {
    // `star` is accessible synchronously here 
    // since it has been eager loaded.
    print(planet.star.name)
}

In the above example, a key path to the @Parent relation named star is passed to with. This causes the query builder to do an additional query after all of the planets are loaded to fetch all of their related stars. The stars are then accessible synchronously via the @Parent property.

Each relation eager loaded requires only one additional query, no matter how many models are returned. Eager loading is only possible with the all and first methods of query builder.

Nested Eager Load¶

The query builder's with method allows you to eager load relations on the model being queried. However, you can also eager load relations on related models.

let planets = try await Planet.query(on: database).with(\.$star) { star in
    star.with(\.$galaxy)
}.all()
for planet in planets {
    // `star.galaxy` is accessible synchronously here 
    // since it has been eager loaded.
    print(planet.star.galaxy.name)
}

The with method accepts an optional closure as a second parameter. This closure accepts an eager load builder for the chosen relation. There is no limit to how deeply eager loading can be nested.

Lazy Eager Loading¶

In case that you have already retrieved the parent model and you want to load one of it's relations, you can use the get(reload:on:) method for that purpose. This will fetch the related model from the database (or cache, if available) and allows it to be accessed as a local property.

planet.$star.get(on: database).map {
    print(planet.star.name)
}

// Or

try await planet.$star.get(on: database)
print(planet.star.name)

In case you want to ensure that the data you receive is not pulled from cache, use the reload: parameter.

try await planet.$star.get(reload: true, on: database)
print(planet.star.name)

To check whether or not a relation has been loaded, use the value property.

if planet.$star.value != nil {
    // Relation has been loaded.
    print(planet.star.name)
} else {
    // Relation has not been loaded.
    // Attempting to access planet.star will fail.
}

If you already have the related model in a variable, you can set the relation manually using the value property mentioned above.

planet.$star.value = star

This will attach the related model to the parent as if it was eager loaded or lazy loaded without an extra database query.