Skip to content

Commit 814146c

Browse files
grouegroue
committed
DocC
1 parent fedcdef commit 814146c

File tree

9 files changed

+122
-62
lines changed

9 files changed

+122
-62
lines changed

‎Documentation/AssociationsBasics.md‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1784,11 +1784,7 @@ That is because the "deathDate" column has been used for filtering books, when i
17841784
To fix this error, we need a **table alias**:
17851785

17861786
```swift
1787-
// Swift 6.1 (recommended)
17881787
let authorAlias = TableAlias<Author>()
1789-
1790-
// Swift 6.0
1791-
let authorAlias = TableAlias()
17921788
```
17931789

17941790
We modify the `Book.author` association so that it uses this table alias, and we use the table alias to qualify author columns where needed:
@@ -1812,10 +1808,10 @@ let request = Book
18121808
// > WHERE book.publishDate >= person.deathDate
18131809
let request = Book
18141810
.joining(required: Book.author.aliased(authorAlias))
1815-
.filter { $0.publishDate >= authorAlias.deathDate }
1811+
.filter { $0.publishDate >= authorAlias[Author.Columns.deathDate] }
18161812
```
18171813

1818-
From now on, we will only give examples in Swift 6.1.
1814+
Note that Swift 6.1 is required for the short syntac `alias.column`. From now on, we will only give examples in Swift 6.1.
18191815

18201816
**Table aliases** can also improve control over the ordering of request results. In the example below, we override the [default ordering](#sorting-associations) of associated records by sorting on author names first:
18211817

‎GRDB/QueryInterface/Request/Association/Association.swift‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -305,20 +305,25 @@ extension AssociationToOne {
305305
///
306306
/// ### Building Association Aggregates
307307
///
308-
/// - ``average(_:)-4bbk9``
309308
/// - ``average(_:)-1rl6m``
310309
/// - ``count``
311310
/// - ``isEmpty``
312-
/// - ``max(_:)-4g5ut``
313311
/// - ``max(_:)-32xmj``
314-
/// - ``min(_:)-6al4w``
315312
/// - ``min(_:)-ulrg``
316-
/// - ``sum(_:)-6ge96``
317313
/// - ``sum(_:)-8jd26``
318-
/// - ``total(_:)-56v8i``
319314
/// - ``total(_:)-9ae2u``
320315
///
321316
/// - ``AssociationAggregate``
317+
///
318+
/// ### Legacy APIs
319+
///
320+
/// It is recommended to prefer the closure-based apis defined above.
321+
///
322+
/// - ``average(_:)-4bbk9``
323+
/// - ``max(_:)-4g5ut``
324+
/// - ``min(_:)-6al4w``
325+
/// - ``sum(_:)-6ge96``
326+
/// - ``total(_:)-56v8i``
322327
public protocol AssociationToMany: Association { }
323328

324329
extension AssociationToMany {

‎GRDB/QueryInterface/Request/QueryInterfaceRequest.swift‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,6 @@
5757
/// ### Changing The Type of Fetched Results
5858
///
5959
/// - ``asRequest(of:)``
60-
/// - ``select(_:as:)-282xc``
61-
/// - ``select(_:as:)-3o8qw``
6260
/// - ``select(_:as:)-58954``
6361
/// - ``select(literal:as:)``
6462
/// - ``select(sql:arguments:as:)``
@@ -73,23 +71,30 @@
7371
/// - ``deleteAndFetchAll(_:)``
7472
/// - ``deleteAndFetchSet(_:)``
7573
/// - ``deleteAndFetchStatement(_:select:)``
76-
/// - ``deleteAndFetchStatement(_:selection:)``
7774
///
7875
/// ### Batch Update
7976
///
8077
/// - ``updateAll(_:onConflict:assignment:)``
8178
/// - ``updateAll(_:onConflict:assignments:)``
79+
/// - ``updateAndFetchCursor(_:onConflict:assignments:)``
80+
/// - ``updateAndFetchAll(_:onConflict:assignments:)``
81+
/// - ``updateAndFetchSet(_:onConflict:assignments:)``
82+
/// - ``updateAndFetchStatement(_:onConflict:assignments:select:)``
83+
/// - ``ColumnAssignment``
84+
///
85+
/// ### Legacy APIs
86+
///
87+
/// It is recommended to prefer the closure-based apis defined above.
88+
///
89+
/// - ``deleteAndFetchStatement(_:selection:)``
90+
/// - ``select(_:as:)-282xc``
91+
/// - ``select(_:as:)-3o8qw``
8292
/// - ``updateAll(_:onConflict:_:)-9r4v``
8393
/// - ``updateAll(_:onConflict:_:)-49qg8``
84-
/// - ``updateAndFetchCursor(_:onConflict:assignments:)``
8594
/// - ``updateAndFetchCursor(_:onConflict:_:)``
86-
/// - ``updateAndFetchAll(_:onConflict:assignments:)``
8795
/// - ``updateAndFetchAll(_:onConflict:_:)``
88-
/// - ``updateAndFetchSet(_:onConflict:assignments:)``
8996
/// - ``updateAndFetchSet(_:onConflict:_:)``
90-
/// - ``updateAndFetchStatement(_:onConflict:assignments:select:)``
9197
/// - ``updateAndFetchStatement(_:onConflict:_:selection:)``
92-
/// - ``ColumnAssignment``
9398
public struct QueryInterfaceRequest<RowDecoder> {
9499
var relation: SQLRelation
95100
}

‎GRDB/QueryInterface/Request/RequestProtocols.swift‎

Lines changed: 59 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -22,18 +22,23 @@ public protocol TypedRequest<RowDecoder> {
2222
///
2323
/// ### The SELECT Clause
2424
///
25-
/// - ``annotated(with:)-4qcem``
26-
/// - ``annotated(with:)-6ehs4``
2725
/// - ``annotated(with:)-1satx``
2826
/// - ``annotated(with:)-6q3b``
2927
/// - ``annotatedWhenConnected(with:)``
30-
/// - ``select(_:)-30yzl``
31-
/// - ``select(_:)-7e2y5``
3228
/// - ``select(_:)-ruzy``
3329
/// - ``select(_:)-37j4h``
3430
/// - ``select(literal:)``
3531
/// - ``select(sql:arguments:)``
3632
/// - ``selectWhenConnected(_:)``
33+
///
34+
/// ### Legacy APIs
35+
///
36+
/// It is recommended to prefer the closure-based apis defined above.
37+
///
38+
/// - ``annotated(with:)-4qcem``
39+
/// - ``annotated(with:)-6ehs4``
40+
/// - ``select(_:)-30yzl``
41+
/// - ``select(_:)-7e2y5``
3742
public protocol SelectionRequest {
3843
/// Defines the result columns.
3944
///
@@ -347,12 +352,17 @@ extension SelectionRequest {
347352
/// ### The WHERE and JOIN ON Clauses
348353
///
349354
/// - ``all()``
350-
/// - ``filter(_:)-48a4t``
351355
/// - ``filter(_:)-6xr3d``
352356
/// - ``filter(literal:)``
353357
/// - ``filter(sql:arguments:)``
354358
/// - ``filterWhenConnected(_:)``
355359
/// - ``none()``
360+
///
361+
/// ### Legacy APIs
362+
///
363+
/// It is recommended to prefer the closure-based apis defined above.
364+
///
365+
/// - ``filter(_:)-48a4t``
356366
public protocol FilteredRequest {
357367
/// Filters the fetched rows with a boolean SQL expression.
358368
///
@@ -478,7 +488,6 @@ extension FilteredRequest {
478488
/// ### Instance Methods
479489
///
480490
/// - ``aliased(_:)-3k5h4``
481-
/// - ``aliased(_:)-772vb``
482491
/// - ``TableAlias``
483492
///
484493
/// ### The WHERE Clause
@@ -499,6 +508,12 @@ extension FilteredRequest {
499508
/// ### The ORDER BY Clause
500509
///
501510
/// - ``orderByPrimaryKey()``
511+
///
512+
/// ### Legacy APIs
513+
///
514+
/// It is recommended to prefer record aliases over anonymous aliases.
515+
///
516+
/// - ``aliased(_:)-772vb``
502517
public protocol TableRequest {
503518
/// The name of the database table
504519
var databaseTableName: String { get }
@@ -508,7 +523,8 @@ public protocol TableRequest {
508523
}
509524

510525
extension TableRequest where Self: TypedRequest {
511-
/// Returns a request that can be referred to with the provided alias.
526+
/// Returns a request that can be referred to with the provided
527+
/// anonymous alias.
512528
///
513529
/// Use this method when you need to refer to this request from
514530
/// another request.
@@ -567,7 +583,8 @@ extension TableRequest where Self: TypedRequest {
567583
self._aliased(alias)
568584
}
569585

570-
/// Returns a request that can be referred to with the provided alias.
586+
/// Returns a request that can be referred to with the provided
587+
/// record alias.
571588
///
572589
/// Use this method when you need to refer to this request from
573590
/// another request.
@@ -622,8 +639,8 @@ extension TableRequest where Self: TypedRequest {
622639
/// // JOIN author a ON a.id = b.authorId
623640
/// // AND a.countryCode = 'FR'
624641
/// // WHERE b.publishDate >= a.deathDate
625-
/// let bookAlias = TableAlias(name: "b")
626-
/// let authorAlias = TableAlias(name: "a")
642+
/// let bookAlias = TableAlias<Book>(name: "b")
643+
/// let authorAlias = TableAlias<Author>(name: "a")
627644
/// let posthumousFrenchBooks = try Book.aliased(bookAlias)
628645
/// .joining(required: Book.author.aliased(authorAlias)
629646
/// .filter(sql: "a.countryCode = ?", arguments: ["FR"]))
@@ -953,8 +970,6 @@ extension TableRequest where Self: AggregatingRequest {
953970
///
954971
/// ### The GROUP BY Clause
955972
///
956-
/// - ``group(_:)-edak``
957-
/// - ``group(_:)-4216o``
958973
/// - ``group(_:)-2g7br``
959974
/// - ``group(_:)-s6lb``
960975
/// - ``group(literal:)``
@@ -963,11 +978,18 @@ extension TableRequest where Self: AggregatingRequest {
963978
///
964979
/// ### The HAVING Clause
965980
///
966-
/// - ``having(_:)-2ssg9``
967981
/// - ``having(_:)-2oggh``
968982
/// - ``having(literal:)``
969983
/// - ``having(sql:arguments:)``
970984
/// - ``havingWhenConnected(_:)``
985+
///
986+
/// ### Legacy APIs
987+
///
988+
/// It is recommended to prefer the closure-based apis defined above.
989+
///
990+
/// - ``group(_:)-edak``
991+
/// - ``group(_:)-4216o``
992+
/// - ``having(_:)-2ssg9``
971993
public protocol AggregatingRequest {
972994
/// Returns an aggregate request grouped on the given SQL expressions.
973995
///
@@ -1235,8 +1257,6 @@ extension AggregatingRequest {
12351257
///
12361258
/// ### The ORDER BY Clause
12371259
///
1238-
/// - ``order(_:)-63rzl``
1239-
/// - ``order(_:)-6co0m``
12401260
/// - ``order(_:)-9d0hr``
12411261
/// - ``order(_:)-35kv9``
12421262
/// - ``order(literal:)``
@@ -1245,6 +1265,13 @@ extension AggregatingRequest {
12451265
/// - ``reversed()``
12461266
/// - ``unordered()``
12471267
/// - ``withStableOrder()``
1268+
///
1269+
/// ### Legacy APIs
1270+
///
1271+
/// It is recommended to prefer the closure-based apis defined above.
1272+
///
1273+
/// - ``order(_:)-63rzl``
1274+
/// - ``order(_:)-6co0m``
12481275
public protocol OrderedRequest {
12491276
/// Sorts the fetched rows according to the given SQL ordering terms.
12501277
///
@@ -1777,7 +1804,6 @@ extension JoinableRequest where Self: SelectionRequest {
17771804
/// ### Instance Methods
17781805
///
17791806
/// - ``TableRequest/aliased(_:)-3k5h4``
1780-
/// - ``TableRequest/aliased(_:)-772vb``
17811807
/// - ``TableAlias``
17821808
///
17831809
/// ### The WITH Clause
@@ -1786,14 +1812,10 @@ extension JoinableRequest where Self: SelectionRequest {
17861812
///
17871813
/// ### The SELECT Clause
17881814
///
1789-
/// - ``SelectionRequest/annotated(with:)-4qcem``
1790-
/// - ``SelectionRequest/annotated(with:)-6ehs4``
17911815
/// - ``SelectionRequest/annotated(with:)-1satx``
17921816
/// - ``SelectionRequest/annotated(with:)-6q3b``
17931817
/// - ``SelectionRequest/annotatedWhenConnected(with:)``
17941818
/// - ``distinct()``
1795-
/// - ``SelectionRequest/select(_:)-30yzl``
1796-
/// - ``SelectionRequest/select(_:)-7e2y5``
17971819
/// - ``SelectionRequest/select(_:)-ruzy``
17981820
/// - ``SelectionRequest/select(_:)-37j4h``
17991821
/// - ``SelectionRequest/select(literal:)``
@@ -1803,7 +1825,6 @@ extension JoinableRequest where Self: SelectionRequest {
18031825
/// ### The WHERE Clause
18041826
///
18051827
/// - ``FilteredRequest/all()``
1806-
/// - ``FilteredRequest/filter(_:)-48a4t``
18071828
/// - ``FilteredRequest/filter(_:)-6xr3d``
18081829
/// - ``TableRequest/filter(id:)``
18091830
/// - ``TableRequest/filter(ids:)``
@@ -1820,24 +1841,19 @@ extension JoinableRequest where Self: SelectionRequest {
18201841
///
18211842
/// ### The GROUP BY and HAVING Clauses
18221843
///
1823-
/// - ``AggregatingRequest/group(_:)-edak``
1824-
/// - ``AggregatingRequest/group(_:)-4216o``
18251844
/// - ``AggregatingRequest/group(_:)-2g7br``
18261845
/// - ``AggregatingRequest/group(_:)-s6lb``
18271846
/// - ``AggregatingRequest/group(literal:)``
18281847
/// - ``AggregatingRequest/group(sql:arguments:)``
18291848
/// - ``TableRequest/groupByPrimaryKey()``
18301849
/// - ``AggregatingRequest/groupWhenConnected(_:)``
1831-
/// - ``AggregatingRequest/having(_:)-2ssg9``
18321850
/// - ``AggregatingRequest/having(_:)-2oggh``
18331851
/// - ``AggregatingRequest/having(literal:)``
18341852
/// - ``AggregatingRequest/having(sql:arguments:)``
18351853
/// - ``AggregatingRequest/havingWhenConnected(_:)``
18361854
///
18371855
/// ### The ORDER BY Clause
18381856
///
1839-
/// - ``OrderedRequest/order(_:)-63rzl``
1840-
/// - ``OrderedRequest/order(_:)-6co0m``
18411857
/// - ``OrderedRequest/order(_:)-9d0hr``
18421858
/// - ``OrderedRequest/order(_:)-35kv9``
18431859
/// - ``OrderedRequest/order(literal:)``
@@ -1870,6 +1886,23 @@ extension JoinableRequest where Self: SelectionRequest {
18701886
/// - ``SelectionRequest``
18711887
/// - ``TableRequest``
18721888
/// - ``TypedRequest``
1889+
///
1890+
/// ### Legacy APIs
1891+
///
1892+
/// It is recommended to prefer the closure-based apis defined above, as
1893+
/// well as record aliases over anonymous aliases.
1894+
///
1895+
/// - ``TableRequest/aliased(_:)-772vb``
1896+
/// - ``SelectionRequest/annotated(with:)-4qcem``
1897+
/// - ``SelectionRequest/annotated(with:)-6ehs4``
1898+
/// - ``FilteredRequest/filter(_:)-48a4t``
1899+
/// - ``AggregatingRequest/group(_:)-edak``
1900+
/// - ``AggregatingRequest/group(_:)-4216o``
1901+
/// - ``AggregatingRequest/having(_:)-2ssg9``
1902+
/// - ``OrderedRequest/order(_:)-63rzl``
1903+
/// - ``OrderedRequest/order(_:)-6co0m``
1904+
/// - ``SelectionRequest/select(_:)-30yzl``
1905+
/// - ``SelectionRequest/select(_:)-7e2y5``
18731906
public protocol DerivableRequest<RowDecoder>: AggregatingRequest, FilteredRequest,
18741907
JoinableRequest, OrderedRequest,
18751908
SelectionRequest, TableRequest

‎GRDB/QueryInterface/SQL/Table.swift‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -743,17 +743,21 @@ extension Table {
743743
all().limit(limit, offset: offset)
744744
}
745745

746-
/// Returns a request that can be referred to with the provided alias.
746+
/// Returns a request that can be referred to with the provided
747+
/// anonymous alias.
747748
///
748749
/// `table.aliased(alias)` is equivalent to `table.all().aliased(alias)`.
750+
///
749751
/// See ``TableRequest/aliased(_:)-772vb`` for more information.
750752
public func aliased(_ alias: TableAlias<Void>) -> QueryInterfaceRequest<RowDecoder> {
751753
all().aliased(alias)
752754
}
753755

754-
/// Returns a request that can be referred to with the provided alias.
756+
/// Returns a request that can be referred to with the provided
757+
/// record alias.
755758
///
756759
/// `table.aliased(alias)` is equivalent to `table.all().aliased(alias)`.
760+
///
757761
/// See ``TableRequest/aliased(_:)-3k5h4`` for more information.
758762
public func aliased(_ alias: TableAlias<RowDecoder>) -> QueryInterfaceRequest<RowDecoder> {
759763
all().aliased(alias)

‎GRDB/QueryInterface/SQLGeneration/TableAlias.swift‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
/// A TableAlias identifies a table in a request.
1+
/// `TableAliasBase` is the base class of `TableAlias`.
22
///
3-
/// See ``TableRequest/aliased(_:)-772vb`` for more information and examples.
3+
/// See <https://github.com/groue/GRDB.swift/blob/master/Documentation/AssociationsBasics.md#table-aliases> for more information and examples.
44
///
55
/// - note: [**🔥 EXPERIMENTAL**](https://github.com/groue/GRDB.swift/blob/master/README.md#what-are-experimental-features)
66
public class TableAliasBase: @unchecked Sendable {
@@ -285,6 +285,11 @@ extension TableAliasBase {
285285

286286
// MARK: - TableAlias
287287

288+
/// A TableAlias identifies a table in a request.
289+
///
290+
/// See <https://github.com/groue/GRDB.swift/blob/master/Documentation/AssociationsBasics.md#table-aliases> for more information and examples.
291+
///
292+
/// - note: [**🔥 EXPERIMENTAL**](https://github.com/groue/GRDB.swift/blob/master/README.md#what-are-experimental-features)
288293
@dynamicMemberLookup
289294
public final class TableAlias<RowDecoder>: TableAliasBase, @unchecked Sendable {
290295
init(tableName: String, userName: String? = nil)
@@ -298,7 +303,7 @@ public final class TableAlias<RowDecoder>: TableAliasBase, @unchecked Sendable {
298303
becomeProxy(of: root)
299304
}
300305

301-
/// Creates a TableAlias.
306+
/// Creates an anonymous TableAlias.
302307
///
303308
/// When the alias is given a name, this name is guaranteed to be used as
304309
/// the table alias in the SQL query:
@@ -308,6 +313,10 @@ public final class TableAlias<RowDecoder>: TableAliasBase, @unchecked Sendable {
308313
/// let alias = TableAlias(name: "p")
309314
/// let request = Player.all().aliased(alias)
310315
/// ```
316+
///
317+
/// Anonymous aliases do not provide convenience access to table
318+
/// columns, unlike record aliases. See ``TableAlias`` for
319+
/// more information.
311320
public init(name: String? = nil)
312321
where RowDecoder == Void
313322
{

0 commit comments

Comments
 (0)