wip

Author: stephencelis

Sources/StructuredQueriesCore/Documentation.docc/Articles/CommonTableExpressions.md

@@ -6,9 +6,9 @@ or recursive queries of trees and graphs.
 ## Overview
 
 One can build [common table expressions][] (commonly referred to as CTEs) by using the ``With``
-statement, along with the `@Table` macro. CTEs allow you to refactor complex queries into smaller
-pieces, and they allow you to execute recursive queries that can traverse tree-like and graph-like
-tables.
+statement, along with the `@Selection` macro. CTEs allow you to refactor complex queries into
+smaller pieces, and they allow you to execute recursive queries that can traverse tree-like and
+graph-like tables.
 
 [common table expressions]: https://sqlite.org/lang_with.html
 
@@ -47,10 +47,10 @@ selecting only lists whose average priority of reminders is greater than 1.5 int
 that can then be used in another query.
 
 One can define a new type that represents the data you want to pre-compute as a CTE, and you
-annotate the type with the `@Table`:
+annotate the type with `@Selection`:
 
 ```swift
-@Table
+@Selection
 struct HighPriorityRemindersList {
   let id: RemindersList.ID
 }
@@ -173,7 +173,7 @@ As a simple example let's construct a query that selects the numbers from 1 to 1
 by defining a CTE data type that holds the data we want to compute:
 
 ```swift
-@Table
+@Selection
 struct Counts {
   let value: Int
 }
@@ -271,7 +271,7 @@ Fibonacci number, as well as the previous Fibonacci number:
 [recurrence relation]: https://en.wikipedia.org/wiki/Recurrence_relation
 
 ```swift
-@Table
+@Selection
 private struct Fibonacci {
   let n: Int
   let prevFib: Int

Sources/StructuredQueriesCore/Documentation.docc/Articles/GettingStarted.md

@@ -766,11 +766,11 @@ struct ReminderResult: QueryRepresentable {
 )
 ```
 
-There is also a way to streamline providing the ``QueryRepresentable`` conformance. You can use the
-`@Table` to describe the datatype you want to decode:
+There is also a way to streamline providing the ``QueryRepresentable`` conformance. You can use
+`@Selection` to describe the datatype you want to decode:
 
 ```swift
-@Table
+@Selection
 struct ReminderResult {
   let title: String
   let isCompleted: Bool
@@ -784,7 +784,4 @@ struct ReminderResult {
 )
 ```
 
-The `@Table` macro can be used to describe any table-like entity. This includes virtual tables,
-database views, common table expressions, and even groups of columns that you'd like to decode.
-
 See <doc:SafeSQLStrings> for more information about the `#sql` macro.

Sources/StructuredQueriesCore/Documentation.docc/Articles/QueryCookbook.md

@@ -262,20 +262,16 @@ you can use the ``Table/unscoped`` property:
 It will often be the case that you want to select very specific data from your database and then
 decode that data into a custom Swift data type. For example, if you are displaying a list of
 reminders and only need their titles for the list, it would be wasteful to decode an array of all
-reminder data. The `@Table` macro allows you to define a custom data type of only the fields you
+reminder data. The `@Selection` macro allows you to define a custom data type of only the fields you
 want to decode:
 
 ```swift
-@Table
+@Selection
 struct ReminderTitle {
   let title: String
 }
 ```
 
-> Note: The `@Table` macro can be used to describe not only database tables, but a number of
-> table-like things, including virtual tables, database views, common table expressions, and even
-> simply groups of columns you'd like to decode together.
-
 Then when selecting the columns for your query you can use this data type:
 
 @Row {
@@ -304,7 +300,7 @@ As another example, consider the query that selects all reminders lists with the
 in each list. A data type can be defined like so:
 
 ```swift
-@Table
+@Selection
 struct RemindersListWithCount {
   let remindersCount: Int
   let remindersList: RemindersList

Sources/StructuredQueriesCore/Documentation.docc/Articles/SelectStatements.md

@@ -108,10 +108,10 @@ To add (or remove) a `DISTINCT` clause from a selection, use ``Select/distinct(_
 }
 
 To bundle selected columns up into a custom data type, you can annotate a struct of decoded results
-with the `@Table` macro:
+with the `@Selection` macro:
 
 ```swift
-@Table
+@Selection
 struct ReminderResult {
   let title: String
   let isCompleted: Bool

Sources/StructuredQueriesCore/Documentation.docc/Extensions/PrimaryKeyedTable.md

@@ -6,8 +6,8 @@ Typically such columns are also initialized by the database so that when inserti
 table you do not need to specify the primary key. The library provides extra tools that make it
 easier to insert, update, and delete records that have a primary key.
 
-> Note: Don't conform to this protocol directly. Instead, use the `@Table` and `@Column` macros to
-> generate a conformance.
+> Note: Don't conform to this protocol directly. Instead, use the `@Table`, `@Column`, and
+> `@Columns` macros to generate a conformance.
 
 ### Specifying a primary key
 
@@ -39,7 +39,23 @@ struct Reminder {
 }
 ```
 
-> Note: At most one column can be designated as a primary key.
+To define a composite primary key, group them together into a `@Selection` type and annotate the
+field with the `@Columns` macro:
+
+```swift
+@Table
+struct Enrollment {
+  @Selection
+  struct ID {
+    var courseID: CourseID
+    var studentID: StudentID
+  }
+
+  @Columns  // Automatically inferred as '@Columns(primaryKey: True)
+  let id: ID
+  // ...
+}
+```
 
 ### Drafts
 

Sources/StructuredQueriesCore/PrimaryKeyed.swift

@@ -44,8 +44,8 @@ extension TableDraft {
 
 /// A type representing a database table's columns.
 ///
-/// Don't conform to this protocol directly. Instead, use the `@Table` and `@Column` macros to
-/// generate a conformance.
+/// Don't conform to this protocol directly. Instead, use the `@Table`, `@Column`, and `@Columns`
+/// macros to generate a conformance.
 public protocol PrimaryKeyedTableDefinition<PrimaryKey>: TableDefinition
 where QueryValue: PrimaryKeyedTable {
   /// A type representing this table's primary key.

Sources/StructuredQueriesCore/TableColumn.swift

@@ -46,8 +46,8 @@ extension WritableTableColumnExpression {
 
 /// A type representing a table column.
 ///
-/// Don't create instances of this value directly. Instead, use the `@Table` and `@Column` macros to
-/// generate values of this type.
+/// Don't create instances of this value directly. Instead, use the `@Table`, `@Column`, and
+/// `@Columns` macros to generate values of this type.
 public struct TableColumn<Root: Table, Value: QueryRepresentable & QueryBindable>:
   WritableTableColumnExpression
 {
@@ -144,8 +144,8 @@ public enum GeneratedColumnStorage {
 
 /// A type representing a generated column.
 ///
-/// Don't create instances of this value directly. Instead, use the `@Table` and `@Column` macros to
-/// generate values of this type.
+/// Don't create instances of this value directly. Instead, use the `@Table`, `@Column`, and
+/// `@Columns` macros to generate values of this type.
 public struct GeneratedColumn<Root: Table, Value: QueryRepresentable & QueryBindable>:
   TableColumnExpression
 {

Sources/StructuredQueriesCore/TableDefinition.swift

@@ -1,7 +1,7 @@
 /// A type representing a database table's columns.
 ///
-/// Don't conform to this protocol directly. Instead, use the `@Table` and `@Column` macros to
-/// generate a conformance.
+/// Don't conform to this protocol directly. Instead, use the `@Table`, `@Column`, and `@Columns`
+/// macros to generate a conformance.
 @dynamicMemberLookup
 public protocol TableDefinition<QueryValue>: QueryExpression where QueryValue: Table {
   /// An array of this table's columns.

Sources/StructuredQueriesCore/TableExpression.swift

@@ -1,7 +1,7 @@
 /// An expression of table columns.
 ///
-/// Don't conform to this protocol directly. Instead, use the `@Table` macro to generate a
-/// conformance.
+/// Don't conform to this protocol directly. Instead, use the `@Table` and `@Selection` macros to
+/// generate a conformance.
 public protocol TableExpression<QueryValue>: QueryExpression where QueryValue: Table {
   var allColumns: [any QueryExpression] { get }
 }

Sources/StructuredQueriesSQLiteCore/Documentation.docc/Articles/QueryCookbook.md

@@ -58,11 +58,11 @@ this is doing work that SQL actually excels at. In fact, the condition inside th
 suspiciously like a join constraint, which should give us a hint that what we are doing is not
 quite right.
 
-Another way to do this is to use the `@Table` and `@Column` macros along with a
+Another way to do this is to use the `@Selection` and `@Column` macros along with a
 `JSONRepresentation`` of the collection of reminders you want to load for each list:
 
 ```swift
-@Table
+@Selection
 struct Row {
   let remindersList: RemindersList
   @Column(as: [Reminder].JSONRepresentation.self)
@@ -117,9 +117,8 @@ And suppose you would like to fetch all `RemindersList`s along with the collecti
 and reminders associated with the list:
 
 ```struct
-@Table
+@Selection
 struct Row {
-  @Columns
   let remindersList: RemindersList
   @Column(as: [Milestone].JSONRepresentation.self)
   let milestones: [Milestone]