ModelQuery

ModelQuery

A ModelQuery is just a subclass of Query with some added typing and convenience functions for querying the table of a specific Model.

public class ModelQuery<M: Model>: Query

Inheritance

Query

Nested Type Aliases

NestedEagerLoads

A closure for defining any nested eager loading when loading a relationship on this Model.

public typealias NestedEagerLoads<R: Model> = (ModelQuery<R>) -> ModelQuery<R>

"Eager loading" refers to loading a model at the other end of a relationship of this queried model. Nested eager loads refers to loading a model from a relationship on that other model.

Methods

allModels()

Gets all models matching this query from the database.

public func allModels() -> EventLoopFuture<[M]>

Returns

A future containing all models matching this query.

firstModel()

Get the first model matching this query from the database.

public func firstModel() -> EventLoopFuture<M?>

Returns

A future containing the first model matching this query or nil if this query has no results.

unwrapFirst(or:)

Similary to getFirst. Gets the first result of a query, but unwraps the element, throwing an error if it doesn't exist.

public func unwrapFirst(or error: Error = RuneError.notFound) -> EventLoopFuture<M>

Parameters

• error: The error to throw should no element be found. Defaults to RuneError.notFound.

Returns

A future containing the unwrapped first result of this query, or the supplied error if no result was found.

with(_:nested:)

Eager loads (loads a related Model) a Relationship on this model.

public func with<R: Relationship>(_ relationshipKeyPath: KeyPath<M, R>, nested: @escaping NestedEagerLoads<R.To.Value> = { $0 }) -> ModelQuery<M> where R.From == M

Eager loads are evaluated in a single query per eager load after the initial model query has completed.

Usage:

// Consider three types, `Pet`, `Person`, and `Plant`. They
// have the following relationships:
struct Pet: Model {
    ...

    @BelongsTo
    var owner: Person
}

struct Person: Model {
    ...

    @BelongsTo
    var favoritePlant: Plant
}

struct Plant: Model { ... }

// A `Pet` query that loads each pet's related owner _as well_
// as those owners' favorite plants would look like this:
Pet.query()
    // An eager load
    .with(\.$owner) { ownerQuery in
        // `ownerQuery` is the query that will be run when
        // fetching owner objects; we can give it its own
        // eager loads (aka nested eager loading)
        ownerQuery.with(\.$favoritePlant)
    }
    .getAll()

Parameters

• relationshipKeyPath: The KeyPath of the relationship to load. Please note that this is a KeyPath to a Relationship, not a Model, so it will likely start with a '$', such as \.$user.
• nested: A closure for any nested loading to do. See example above. Defaults to an empty closure.

Returns

A query builder for extending the query.