annotated(withRequired:)

For example:

// SELECT player.*, team.color
// FROM player JOIN team ...
let teamColor = Player.team.select(Column("color"))
let request = Player.all().annotated(withRequired: teamColor)

This method performs the exact same SQL request as including(required:). The difference is in the record type that can decode such a request: the columns of the associated record must be decoded at the same level as the main record. For example:

struct PlayerWithTeamColor: FetchableRecord, Decodable {
    var player: Player
    var color: String
}
try dbQueue.read { db in
    let players = try request
        .asRequest(of: PlayerWithTeamColor.self)
        .fetchAll(db)
}

This method is a convenience. You can build the same request with TableAlias, annotated(with:), and joining(required:):

let teamAlias = TableAlias()
let request = Player.all()
    .annotated(with: teamAlias[Column("color")])
    .joining(required: Player.team.aliased(teamAlias))