@@ -213,21 +213,21 @@ joins:
213213let
214214 query :: Query
215215 '[ "orders" :::
216− '["pk" ::: PrimaryKey '["id"]
217− ,"fk_customer" ::: ForeignKey '["customer_id"] "customers" '["id"]
218− ,"fk_shipper" ::: ForeignKey '["shipper_id"] "shippers" '["id"]] :=>
216+ '["pk_orders" ::: PrimaryKey '["id"]
217+ ,"fk_customers" ::: ForeignKey '["customer_id"] "customers" '["id"]
218+ ,"fk_shippers" ::: ForeignKey '["shipper_id"] "shippers" '["id"]] :=>
219219 '[ "id" ::: 'NoDef :=> 'NotNull 'PGint4
220220 , "price" ::: 'NoDef :=> 'NotNull 'PGfloat4
221221 , "customer_id" ::: 'NoDef :=> 'NotNull 'PGint4
222222 , "shipper_id" ::: 'NoDef :=> 'NotNull 'PGint4
223223 ]
224224 , "customers" :::
225− '["pk" ::: PrimaryKey '["id"]] :=>
225+ '["pk_customers" ::: PrimaryKey '["id"]] :=>
226226 '[ "id" ::: 'NoDef :=> 'NotNull 'PGint4
227227 , "name" ::: 'NoDef :=> 'NotNull 'PGtext
228228 ]
229229 , "shippers" :::
230− '["pk" ::: PrimaryKey '["id"]] :=>
230+ '["pk_shippers" ::: PrimaryKey '["id"]] :=>
231231 '[ "id" ::: 'NoDef :=> 'NotNull 'PGint4
232232 , "name" ::: 'NoDef :=> 'NotNull 'PGtext
233233 ]
@@ -412,7 +412,7 @@ selectDistinctStar rels = UnsafeQuery $
412412selectDotStar
413413 :: Has relation relations columns
414414 => Alias relation
415− -- ^ particular virtual Table
415+ -- ^ particular virtual subtable
416416 -> TableExpression schema params relations 'Ungrouped
417417 -- ^ intermediate virtual table
418418 -> Query schema params columns
@@ -424,7 +424,7 @@ selectDotStar rel relations = UnsafeQuery $
424424selectDistinctDotStar
425425 :: Has relation relations columns
426426 => Alias relation
427− -- ^ particular virtual Table
427+ -- ^ particular virtual table
428428 -> TableExpression schema params relations 'Ungrouped
429429 -- ^ intermediate virtual table
430430 -> Query schema params columns
@@ -612,9 +612,9 @@ subquery
612612 -> FromClause schema params '[table]
613613subquery = UnsafeFromClause . renderAliasedAs (parenthesized . renderQuery)
614614
615−{- | @t1 & crossJoin t2@. For every possible combination of rows from
616− @t1@ and @t2@ (i.e., a Cartesian product), the joined table will contain
617− a row consisting of all columns in @t1@ followed by all columns in @t2@.
615+{- | @left & crossJoin right@. For every possible combination of rows from
616+ @left@ and @right@ (i.e., a Cartesian product), the joined table will contain
617+ a row consisting of all columns in @left@ followed by all columns in @right@.
618618 If the tables have @n@ and @m@ rows respectively, the joined table will
619619 have @n * m@ rows.
620620-}
@@ -627,15 +627,14 @@ crossJoin
627627crossJoin right left = UnsafeFromClause $
628628 renderFromClause left <+> "CROSS JOIN" <+> renderFromClause right
629629
630−{- | @t1 & InnerJoin t2 on@. For each row @r1@ of @t1@, the joined
631− table has a row for each row in @t2@ that satisfies the @on@ condition
632− with @r1@
630+{- | @left & innerJoin right on@. The joined table is filtered by
631+the @on@ condition.
633632-}
634633innerJoin
635634 :: FromClause schema params right
636635 -- ^ right
637636 -> Condition (Join left right) 'Ungrouped params
638− -- ^ @ON@ condition
637+ -- ^ @on@ condition
639638 -> FromClause schema params left
640639 -- ^ left
641640 -> FromClause schema params (Join left right)
@@ -643,16 +642,16 @@ innerJoin right on left = UnsafeFromClause $
643642 renderFromClause left <+> "INNER JOIN" <+> renderFromClause right
644643 <+> "ON" <+> renderExpression on
645644
646−{- | @t1 & LeftOuterJoin t2 on@. First, an inner join is performed.
647− Then, for each row in @t1@ that does not satisfy the @on@ condition with
648− any row in @t2@, a joined row is added with null values in columns of @t2@.
649− Thus, the joined table always has at least one row for each row in @t1@.
645+{- | @left & leftOuterJoin right on@. First, an inner join is performed.
646+ Then, for each row in @left@ that does not satisfy the @on@ condition with
647+ any row in @right@, a joined row is added with null values in columns of @right@.
648+ Thus, the joined table always has at least one row for each row in @left@.
650649-}
651650leftOuterJoin
652651 :: FromClause schema params right
653652 -- ^ right
654653 -> Condition (Join left right) 'Ungrouped params
655− -- ^ @ON@ condition
654+ -- ^ @on@ condition
656655 -> FromClause schema params left
657656 -- ^ left
658657 -> FromClause schema params (Join left (NullifyRelations right))
@@ -660,17 +659,17 @@ leftOuterJoin right on left = UnsafeFromClause $
660659 renderFromClause left <+> "LEFT OUTER JOIN" <+> renderFromClause right
661660 <+> "ON" <+> renderExpression on
662661
663−{- | @t1 & RightOuterJoin t2 on@. First, an inner join is performed.
664− Then, for each row in @t2@ that does not satisfy the @on@ condition with
665− any row in @t1@, a joined row is added with null values in columns of @t1@.
662+{- | @left & rightOuterJoin right on@. First, an inner join is performed.
663+ Then, for each row in @right@ that does not satisfy the @on@ condition with
664+ any row in @left@, a joined row is added with null values in columns of @left@.
666665 This is the converse of a left join: the result table will always
667− have a row for each row in @t2@.
666+ have a row for each row in @right@.
668667-}
669668rightOuterJoin
670669 :: FromClause schema params right
671670 -- ^ right
672671 -> Condition (Join left right) 'Ungrouped params
673− -- ^ @ON@ condition
672+ -- ^ @on@ condition
674673 -> FromClause schema params left
675674 -- ^ left
676675 -> FromClause schema params (Join (NullifyRelations left) right)
@@ -678,18 +677,18 @@ rightOuterJoin right on left = UnsafeFromClause $
678677 renderFromClause left <+> "RIGHT OUTER JOIN" <+> renderFromClause right
679678 <+> "ON" <+> renderExpression on
680679
681−{- | @t1 & FullOuterJoin t2 on@. First, an inner join is performed.
682− Then, for each row in @t1@ that does not satisfy the @on@ condition with
683− any row in @t2@, a joined row is added with null values in columns of @t2@.
684− Also, for each row of @t2@ that does not satisfy the join condition
685− with any row in @t1@, a joined row with null values in the columns of @t1@
680+{- | @left & fullOuterJoin right on@. First, an inner join is performed.
681+ Then, for each row in @left@ that does not satisfy the @on@ condition with
682+ any row in @right@, a joined row is added with null values in columns of @right@.
683+ Also, for each row of @right@ that does not satisfy the join condition
684+ with any row in @left@, a joined row with null values in the columns of @left@
686685 is added.
687686-}
688687fullOuterJoin
689688 :: FromClause schema params right
690689 -- ^ right
691690 -> Condition (Join left right) 'Ungrouped params
692− -- ^ @ON@ condition
691+ -- ^ @on@ condition
693692 -> FromClause schema params left
694693 -- ^ left
695694 -> FromClause schema params
@@ -732,7 +731,8 @@ renderBy = \case
732731-- A `NoGroups` indicates `Ungrouped` while a `Group` indicates `Grouped`.
733732-- @NoGroups@ is distinguised from @Group Nil@ since no aggregation can be
734733-- done on @NoGroups@ while all output `Expression`s must be aggregated
735−-- in @Group Nil@.
734+-- in @Group Nil@. In general, all output `Expression`s in the
735+-- complement of @bys@ must be aggregated in @Group bys@.
736736data GroupByClause relations grouping where
737737 NoGroups :: GroupByClause relations 'Ungrouped
738738 Group