@@ -54,21 +54,21 @@ module Squeal.PostgreSQL.Query
5454 , orderBy
5555 , limit
5656 , offset
57− -- ** JSON table expressions
58− , PGjson_each
59− , PGjsonb_each
57+ -- ** Json
6058 , jsonEach
6159 , jsonbEach
6260 , jsonEachAsText
6361 , jsonbEachAsText
64− , jsonPopulateRecordAs
65− , jsonbPopulateRecordAs
66− , jsonPopulateRecordSetAs
67− , jsonbPopulateRecordSetAs
68− , jsonToRecordAs
69− , jsonbToRecordAs
70− , jsonToRecordSetAs
71− , jsonbToRecordSetAs
62+ , jsonObjectKeys
63+ , jsonbObjectKeys
64+ , jsonPopulateRecord
65+ , jsonbPopulateRecord
66+ , jsonPopulateRecordSet
67+ , jsonbPopulateRecordSet
68+ , jsonToRecord
69+ , jsonbToRecord
70+ , jsonToRecordSet
71+ , jsonbToRecordSet
7272 -- * From
7373 , FromClause (..)
7474 , table
@@ -90,8 +90,6 @@ module Squeal.PostgreSQL.Query
9090 , SortExpression (..)
9191 , renderSortExpression
9292 -- * Subquery expressions
93− , unsafeSubqueryExpression
94− , unsafeRowSubqueryExpression
9593 , in_
9694 , rowIn
9795 , allEq
@@ -701,184 +699,144 @@ offset off rels = rels {offsetClause = off : offsetClause rels}
701699JSON stuff
702700-----------------------------------------}
703701
704−type PGjson_each_variant val tab =
705− '[ tab ::: '[ "key" ::: 'NotNull 'PGtext, "value" ::: 'NotNull val ] ]
706−
707−-- | The type of a `json_each` `FromClause`.
708−type PGjson_each tab = PGjson_each_variant 'PGjson tab
709−-- | The type of a `jsonb_each` `FromClause`.
710−type PGjsonb_each tab = PGjson_each_variant 'PGjsonb tab
711−-- | The type of a `json_each_text` `FromClause`.
712−type PGjson_each_text tab = PGjson_each_variant 'PGtext tab
713−-- | The type of a `jsonb_each_text` `FromClause`.
714−type PGjsonb_each_text tab = PGjson_each_variant 'PGtext tab
715−
716−unsafeAliasedFromClauseExpression
717− :: Aliased (Expression schema' from' grouping' params') ty'
718− -> FromClause schema params from
719−unsafeAliasedFromClauseExpression aliasedExpr = UnsafeFromClause
720− (renderAliasedAs renderExpression aliasedExpr)
702+unsafeSetOfFunction
703+ :: ByteString
704+ -> Expression schema '[] 'Ungrouped params ty
705+ -> Query schema params row
706+unsafeSetOfFunction fun expr = UnsafeQuery $
707+ "SELECT * FROM " <> fun <> "(" <> renderExpression expr <> ")"
721708
722709-- | Expands the outermost JSON object into a set of key/value pairs.
723710jsonEach
724− :: Aliased (Expression schema '[] 'Ungrouped params) '(tab, nullity 'PGjson)
725− -> FromClause schema params (PGjson_each tab)
726−jsonEach (As jexpr jname) = unsafeAliasedFromClauseExpression
727− (As (unsafeFunction "json_each" jexpr) jname)
711+ :: Expression schema '[] 'Ungrouped params (nullity 'PGjson) -- ^ json
712+ -> Query schema params
713+ '["key" ::: 'NotNull 'PGtext, "value" ::: 'NotNull 'PGjson]
714+jsonEach = unsafeSetOfFunction "json_each"
728715
729716-- | Expands the outermost binary JSON object into a set of key/value pairs.
730717jsonbEach
731− :: Aliased (Expression schema '[] 'Ungrouped params) '(tab, nullity 'PGjsonb)
732− -> FromClause schema params (PGjsonb_each tab)
733−jsonbEach (As jexpr jname) = unsafeAliasedFromClauseExpression
734− (As (unsafeFunction "jsonb_each" jexpr) jname)
718+ :: Expression schema '[] 'Ungrouped params (nullity 'PGjsonb) -- ^ jsonb
719+ -> Query schema params
720+ '["key" ::: 'NotNull 'PGtext, "value" ::: 'NotNull 'PGjsonb]
721+jsonbEach = unsafeSetOfFunction "jsonb_each"
735722
736723-- | Expands the outermost JSON object into a set of key/value pairs.
737724jsonEachAsText
738− :: Aliased (Expression schema '[] 'Ungrouped params) '(tab, nullity 'PGjson)
739− -> FromClause schema params (PGjson_each_text tab)
740−jsonEachAsText (As jexpr jname) = unsafeAliasedFromClauseExpression
741− (As (unsafeFunction "json_each" jexpr) jname)
725+ :: Expression schema '[] 'Ungrouped params (nullity 'PGjson) -- ^ json
726+ -> Query schema params
727+ '["key" ::: 'NotNull 'PGtext, "value" ::: 'NotNull 'PGtext]
728+jsonEachAsText = unsafeSetOfFunction "json_each_text"
742729
743730-- | Expands the outermost binary JSON object into a set of key/value pairs.
744731jsonbEachAsText
745− :: Aliased (Expression schema '[] 'Ungrouped params) '(tab, nullity 'PGjsonb)
746− -> FromClause schema params (PGjsonb_each_text tab)
747−jsonbEachAsText (As jexpr jname) = unsafeAliasedFromClauseExpression
748− (As (unsafeFunction "jsonb_each" jexpr) jname)
749−
750−nullRow
751− :: Has tab schema ('Table table)
752− => Alias tab
753− -> Expression schema from grouping params
754− (nullity ('PGcomposite (TableToRow table)))
755−nullRow tab = UnsafeExpression ("null::"<+>renderAlias tab)
732+ :: Expression schema '[] 'Ungrouped params (nullity 'PGjsonb) -- ^ jsonb
733+ -> Query schema params
734+ '["key" ::: 'NotNull 'PGtext, "value" ::: 'NotNull 'PGtext]
735+jsonbEachAsText = unsafeSetOfFunction "jsonb_each_text"
736+
737+-- | Returns set of keys in the outermost JSON object.
738+jsonObjectKeys
739+ :: Expression schema '[] 'Ungrouped params (nullity 'PGjson)
740+ -> Query schema params '["json_object_keys" ::: 'NotNull 'PGtext]
741+jsonObjectKeys = unsafeSetOfFunction "json_object_keys"
742+
743+-- | Returns set of keys in the outermost JSON object.
744+jsonbObjectKeys
745+ :: Expression schema '[] 'Ungrouped params (nullity 'PGjsonb)
746+ -> Query schema params '["jsonb_object_keys" ::: 'NotNull 'PGtext]
747+jsonbObjectKeys = unsafeSetOfFunction "jsonb_object_keys"
748+
749+unsafePopulateFunction
750+ :: ByteString
751+ -> TypeExpression schema (nullity ('PGcomposite row))
752+ -> Expression schema '[] 'Ungrouped params ty
753+ -> Query schema params row
754+unsafePopulateFunction fun ty expr = UnsafeQuery $
755+ "SELECT * FROM " <> fun <> "("
756+ <> "null::" <> renderTypeExpression ty <> ", "
757+ <> renderExpression expr <> ")"
756758
757759-- | Expands the JSON expression to a row whose columns match the record
758760-- type defined by the given table.
759−jsonPopulateRecordAs
760− :: (KnownSymbol alias, Has tab schema ('Table table))
761− => Alias tab
761+jsonPopulateRecord
762+ :: TypeExpression schema (nullity ('PGcomposite row))
762763 -> Expression schema '[] 'Ungrouped params (nullity 'PGjson)
763− -> Alias alias
764− -> FromClause schema params '[alias ::: TableToRow table]
765−jsonPopulateRecordAs tableName expr alias = unsafeAliasedFromClauseExpression
766− (unsafeVariadicFunction "json_populate_record"
767− (nullRow tableName :* expr :* Nil) `As` alias)
764+ -> Query schema params row
765+jsonPopulateRecord = unsafePopulateFunction "json_populate_record"
768766
769767-- | Expands the binary JSON expression to a row whose columns match the record
770768-- type defined by the given table.
771−jsonbPopulateRecordAs
772− :: (KnownSymbol alias, Has tab schema ('Table table))
773− => Alias tab
769+jsonbPopulateRecord
770+ :: TypeExpression schema (nullity ('PGcomposite row))
774771 -> Expression schema '[] 'Ungrouped params (nullity 'PGjsonb)
775− -> Alias alias
776− -> FromClause schema params '[alias ::: TableToRow table]
777−jsonbPopulateRecordAs tableName expr alias = unsafeAliasedFromClauseExpression
778− (unsafeVariadicFunction "jsonb_populate_record"
779− (nullRow tableName :* expr :* Nil) `As` alias)
772+ -> Query schema params row
773+jsonbPopulateRecord = unsafePopulateFunction "jsonb_populate_record"
780774
781775-- | Expands the outermost array of objects in the given JSON expression to a
782776-- set of rows whose columns match the record type defined by the given table.
783−jsonPopulateRecordSetAs
784− :: (KnownSymbol alias, Has tab schema ('Table table))
785− => Alias tab
777+jsonPopulateRecordSet
778+ :: TypeExpression schema (nullity ('PGcomposite row))
786779 -> Expression schema '[] 'Ungrouped params (nullity 'PGjson)
787− -> Alias alias
788− -> FromClause schema params '[alias ::: TableToRow table]
789−jsonPopulateRecordSetAs tableName expr alias = unsafeAliasedFromClauseExpression
790− (unsafeVariadicFunction "json_populate_record_set"
791− (nullRow tableName :* expr :* Nil) `As` alias)
780+ -> Query schema params row
781+jsonPopulateRecordSet = unsafePopulateFunction "json_populate_record_set"
792782
793783-- | Expands the outermost array of objects in the given binary JSON expression
794784-- to a set of rows whose columns match the record type defined by the given
795785-- table.
796−jsonbPopulateRecordSetAs
797− :: (KnownSymbol alias, Has tab schema ('Table table))
798− => Alias tab
786+jsonbPopulateRecordSet
787+ :: TypeExpression schema (nullity ('PGcomposite row))
799788 -> Expression schema '[] 'Ungrouped params (nullity 'PGjsonb)
800− -> Alias alias
801− -> FromClause schema params '[alias ::: TableToRow table]
802−jsonbPopulateRecordSetAs tableName expr alias = unsafeAliasedFromClauseExpression
803− (unsafeVariadicFunction "jsonb_populate_record_set"
804− (nullRow tableName :* expr :* Nil) `As` alias)
789+ -> Query schema params row
790+jsonbPopulateRecordSet = unsafePopulateFunction "jsonb_populate_record_set"
805791
806−renderTableTypeExpression
807− :: All Top types
808− => Aliased (NP (Aliased (TypeExpression schema))) (tab ::: types)
809− -> ByteString
810−renderTableTypeExpression (hc `As` tab)
811− = (renderAlias tab <>)
812− . parenthesized
813− . commaSeparated
814− . flip appEndo []
815− . hcfoldMap
816− (Proxy :: Proxy Top)
817− (\(ty `As` name) -> Endo
818− ((renderAlias name <+> renderTypeExpression ty):))
819− $ hc
820−
821−unsafeTableAliasedFromClauseExpression
822− :: All Top types
823− => Expression schema' from' grouping' params' ty'
824− -> Aliased (NP (Aliased (TypeExpression schema))) (tab ::: types)
825− -> FromClause schema params '[alias ::: types]
826−unsafeTableAliasedFromClauseExpression expr types = UnsafeFromClause
827− (renderExpression expr
828− <+> "AS"
829− <+> renderTableTypeExpression types)
830−
831−-- | Builds an arbitrary record from a JSON object. As with all functions
832−-- returning record, the caller must explicitly define the structure of the
833−-- record with an AS clause.
834−jsonToRecordAs
835− :: All Top types
792+unsafeRecordFunction
793+ :: (SListI row, json `In` PGJsonType)
794+ => ByteString
795+ -> Expression schema '[] 'Ungrouped params (nullity json)
796+ -> NP (Aliased (TypeExpression schema)) row
797+ -> Query schema params row
798+unsafeRecordFunction fun expr types = UnsafeQuery $
799+ "SELECT * FROM " <> fun <> "("
800+ <> renderExpression expr <> ")"
801+ <+> "AS" <+> "x" <> parenthesized (renderCommaSeparated renderTy types)
802+ where
803+ renderTy :: Aliased (TypeExpression schema) ty -> ByteString
804+ renderTy (ty `As` alias) =
805+ renderAlias alias <+> renderTypeExpression ty
806+
807+-- | Builds an arbitrary record from a JSON object.
808+jsonToRecord
809+ :: SListI row
836810 => Expression schema '[] 'Ungrouped params (nullity 'PGjson)
837− -> Aliased (NP (Aliased (TypeExpression schema))) (tab ::: types)
838− -> FromClause schema params '[tab ::: types]
839−jsonToRecordAs expr types =
840− unsafeTableAliasedFromClauseExpression
841− (unsafeFunction "json_to_record" expr)
842− types
843−
844−-- | Builds an arbitrary record from a binary JSON object. As with all functions
845−-- returning record, the caller must explicitly define the structure of the
846−-- record with an AS clause.
847−jsonbToRecordAs
848− :: All Top types
811+ -> NP (Aliased (TypeExpression schema)) row
812+ -> Query schema params row
813+jsonToRecord = unsafeRecordFunction "json_to_record"
814+
815+-- | Builds an arbitrary record from a binary JSON object.
816+jsonbToRecord
817+ :: SListI row
849818 => Expression schema '[] 'Ungrouped params (nullity 'PGjsonb)
850− -> Aliased (NP (Aliased (TypeExpression schema))) (tab ::: types)
851− -> FromClause schema params '[tab ::: types]
852−jsonbToRecordAs expr types =
853− unsafeTableAliasedFromClauseExpression
854− (unsafeFunction "jsonb_to_record" expr)
855− types
856−
857−-- | Builds an arbitrary set of records from a JSON array of objects (see note
858−-- below). As with all functions returning record, the caller must explicitly
859−-- define the structure of the record with an AS clause.
860−jsonToRecordSetAs
861− :: All Top types
819+ -> NP (Aliased (TypeExpression schema)) row
820+ -> Query schema params row
821+jsonbToRecord = unsafeRecordFunction "jsonb_to_record"
822+
823+-- | Builds an arbitrary set of records from a JSON array of objects.
824+jsonToRecordSet
825+ :: SListI row
862826 => Expression schema '[] 'Ungrouped params (nullity 'PGjson)
863− -> Aliased (NP (Aliased (TypeExpression schema))) (tab ::: types)
864− -> FromClause schema params '[tab ::: types]
865−jsonToRecordSetAs expr types =
866− unsafeTableAliasedFromClauseExpression
867− (unsafeFunction "json_to_recordset" expr)
868− types
827+ -> NP (Aliased (TypeExpression schema)) row
828+ -> Query schema params row
829+jsonToRecordSet = unsafeRecordFunction "json_to_record_set"
869830
870831-- | Builds an arbitrary set of records from a binary JSON array of objects (see
871832-- note below). As with all functions returning record, the caller must
872833-- explicitly define the structure of the record with an AS clause.
873−jsonbToRecordSetAs
874− :: All Top types
834+jsonbToRecordSet
835+ :: SListI row
875836 => Expression schema '[] 'Ungrouped params (nullity 'PGjsonb)
876− -> Aliased (NP (Aliased (TypeExpression schema))) (tab ::: types)
877− -> FromClause schema params '[tab ::: types]
878−jsonbToRecordSetAs expr types =
879− unsafeTableAliasedFromClauseExpression
880− (unsafeFunction "jsonb_to_recordset" expr)
881− types
837+ -> NP (Aliased (TypeExpression schema)) row
838+ -> Query schema params row
839+jsonbToRecordSet = unsafeRecordFunction "jsonb_to_record_set"
882840
883841{-----------------------------------------
884842FROM clauses
@@ -908,9 +866,9 @@ subquery = UnsafeFromClause . renderAliasedAs (parenthesized . renderQuery)
908866
909867-- | `view` derives a table from a `View`.
910868view
911− :: Has view schema ('View rel)
869+ :: Has view schema ('View row)
912870 => Aliased Alias (alias ::: view)
913− -> FromClause schema params '[alias ::: rel]
871+ -> FromClause schema params '[alias ::: row]
914872view (vw `As` alias) = UnsafeFromClause $
915873 renderAlias vw <+> "AS" <+> renderAlias alias
916874
@@ -1143,25 +1101,52 @@ unsafeRowSubqueryExpression
11431101unsafeRowSubqueryExpression op xs q = UnsafeExpression $
11441102 renderExpression (row xs) <+> op <+> parenthesized (renderQuery q)
11451103
1104+-- | The right-hand side is a sub`Query`, which must return exactly one column.
1105+-- The left-hand expression is evaluated and compared to each row of the
1106+-- sub`Query` result. The result of `in_` is `true` if any equal subquery row is found.
1107+-- The result is `false` if no equal row is found
1108+-- (including the case where the subquery returns no rows).
1109+--
1110+-- >>> printSQL $ true `in_` values_ (true `as` #foo)
1111+-- TRUE IN (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
11461112in_
1147− :: Expression schema from grp params ty
1148− -> Query schema params '[alias ::: ty]
1113+ :: Expression schema from grp params ty -- ^ expression
1114+ -> Query schema params '[alias ::: ty] -- ^ subquery
11491115 -> Condition schema from grp params
11501116in_ = unsafeSubqueryExpression "IN"
11511117
1118+{- | The left-hand side of this form of `rowIn` is a row constructor.
1119+The right-hand side is a sub`Query`,
1120+which must return exactly as many columns as
1121+there are expressions in the left-hand row.
1122+The left-hand expressions are evaluated and compared row-wise to each row
1123+of the subquery result. The result of `rowIn`
1124+is `true` if any equal subquery row is found.
1125+The result is `false` if no equal row is found
1126+(including the case where the subquery returns no rows).
1127+
1128+>>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1129+>>> printSQL $ myRow `rowIn` values_ myRow
1130+ROW(1, FALSE) IN (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
1131+-}
11521132rowIn
11531133 :: SListI row
1154− => NP (Aliased (Expression schema from grp params)) row
1155− -> Query schema params row
1134+ => NP (Aliased (Expression schema from grp params)) row -- ^ row constructor
1135+ -> Query schema params row -- ^ subquery
11561136 -> Condition schema from grp params
11571137rowIn = unsafeRowSubqueryExpression "IN"
11581138
1139+-- | >>> printSQL $ true `allEq` values_ (true `as` #foo)
1140+-- TRUE ALL = (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
11591141allEq
11601142 :: Expression schema from grp params ty
11611143 -> Query schema params '[alias ::: ty]
11621144 -> Condition schema from grp params
11631145allEq = unsafeSubqueryExpression "ALL ="
11641146
1147+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1148+-- >>> printSQL $ myRow `rowAllEq` values_ myRow
1149+-- ROW(1, FALSE) ALL = (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
11651150rowAllEq
11661151 :: SListI row
11671152 => NP (Aliased (Expression schema from grp params)) row
@@ -1169,12 +1154,17 @@ rowAllEq
11691154 -> Condition schema from grp params
11701155rowAllEq = unsafeRowSubqueryExpression "ALL ="
11711156
1157+-- | >>> printSQL $ true `anyEq` values_ (true `as` #foo)
1158+-- TRUE ANY = (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
11721159anyEq
11731160 :: Expression schema from grp params ty
11741161 -> Query schema params '[alias ::: ty]
11751162 -> Condition schema from grp params
11761163anyEq = unsafeSubqueryExpression "ANY ="
11771164
1165+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1166+-- >>> printSQL $ myRow `rowAnyEq` values_ myRow
1167+-- ROW(1, FALSE) ANY = (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
11781168rowAnyEq
11791169 :: SListI row
11801170 => NP (Aliased (Expression schema from grp params)) row
@@ -1182,12 +1172,17 @@ rowAnyEq
11821172 -> Condition schema from grp params
11831173rowAnyEq = unsafeRowSubqueryExpression "ANY ="
11841174
1175+-- | >>> printSQL $ true `allNeq` values_ (true `as` #foo)
1176+-- TRUE ALL <> (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
11851177allNeq
11861178 :: Expression schema from grp params ty
11871179 -> Query schema params '[alias ::: ty]
11881180 -> Condition schema from grp params
11891181allNeq = unsafeSubqueryExpression "ALL <>"
11901182
1183+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1184+-- >>> printSQL $ myRow `rowAllNeq` values_ myRow
1185+-- ROW(1, FALSE) ALL <> (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
11911186rowAllNeq
11921187 :: SListI row
11931188 => NP (Aliased (Expression schema from grp params)) row
@@ -1195,12 +1190,17 @@ rowAllNeq
11951190 -> Condition schema from grp params
11961191rowAllNeq = unsafeRowSubqueryExpression "ALL <>"
11971192
1193+-- | >>> printSQL $ true `anyNeq` values_ (true `as` #foo)
1194+-- TRUE ANY <> (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
11981195anyNeq
11991196 :: Expression schema from grp params ty
12001197 -> Query schema params '[alias ::: ty]
12011198 -> Condition schema from grp params
12021199anyNeq = unsafeSubqueryExpression "ANY <>"
12031200
1201+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1202+-- >>> printSQL $ myRow `rowAnyNeq` values_ myRow
1203+-- ROW(1, FALSE) ANY <> (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
12041204rowAnyNeq
12051205 :: SListI row
12061206 => NP (Aliased (Expression schema from grp params)) row
@@ -1208,12 +1208,17 @@ rowAnyNeq
12081208 -> Condition schema from grp params
12091209rowAnyNeq = unsafeRowSubqueryExpression "ANY <>"
12101210
1211+-- | >>> printSQL $ true `allLt` values_ (true `as` #foo)
1212+-- TRUE ALL < (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
12111213allLt
12121214 :: Expression schema from grp params ty
12131215 -> Query schema params '[alias ::: ty]
12141216 -> Condition schema from grp params
12151217allLt = unsafeSubqueryExpression "ALL <"
12161218
1219+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1220+-- >>> printSQL $ myRow `rowAllLt` values_ myRow
1221+-- ROW(1, FALSE) ALL < (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
12171222rowAllLt
12181223 :: SListI row
12191224 => NP (Aliased (Expression schema from grp params)) row
@@ -1221,12 +1226,17 @@ rowAllLt
12211226 -> Condition schema from grp params
12221227rowAllLt = unsafeRowSubqueryExpression "ALL <"
12231228
1229+-- | >>> printSQL $ true `anyLt` values_ (true `as` #foo)
1230+-- TRUE ANY < (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
12241231anyLt
12251232 :: Expression schema from grp params ty
12261233 -> Query schema params '[alias ::: ty]
12271234 -> Condition schema from grp params
12281235anyLt = unsafeSubqueryExpression "ANY <"
12291236
1237+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1238+-- >>> printSQL $ myRow `rowAllLt` values_ myRow
1239+-- ROW(1, FALSE) ALL < (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
12301240rowAnyLt
12311241 :: SListI row
12321242 => NP (Aliased (Expression schema from grp params)) row
@@ -1234,12 +1244,17 @@ rowAnyLt
12341244 -> Condition schema from grp params
12351245rowAnyLt = unsafeRowSubqueryExpression "ANY <"
12361246
1247+-- | >>> printSQL $ true `allLte` values_ (true `as` #foo)
1248+-- TRUE ALL <= (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
12371249allLte
12381250 :: Expression schema from grp params ty
12391251 -> Query schema params '[alias ::: ty]
12401252 -> Condition schema from grp params
12411253allLte = unsafeSubqueryExpression "ALL <="
12421254
1255+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1256+-- >>> printSQL $ myRow `rowAllLte` values_ myRow
1257+-- ROW(1, FALSE) ALL <= (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
12431258rowAllLte
12441259 :: SListI row
12451260 => NP (Aliased (Expression schema from grp params)) row
@@ -1247,12 +1262,17 @@ rowAllLte
12471262 -> Condition schema from grp params
12481263rowAllLte = unsafeRowSubqueryExpression "ALL <="
12491264
1265+-- | >>> printSQL $ true `anyLte` values_ (true `as` #foo)
1266+-- TRUE ANY <= (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
12501267anyLte
12511268 :: Expression schema from grp params ty
12521269 -> Query schema params '[alias ::: ty]
12531270 -> Condition schema from grp params
12541271anyLte = unsafeSubqueryExpression "ANY <="
12551272
1273+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1274+-- >>> printSQL $ myRow `rowAnyLte` values_ myRow
1275+-- ROW(1, FALSE) ANY <= (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
12561276rowAnyLte
12571277 :: SListI row
12581278 => NP (Aliased (Expression schema from grp params)) row
@@ -1260,12 +1280,17 @@ rowAnyLte
12601280 -> Condition schema from grp params
12611281rowAnyLte = unsafeRowSubqueryExpression "ANY <="
12621282
1283+-- | >>> printSQL $ true `allGt` values_ (true `as` #foo)
1284+-- TRUE ALL > (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
12631285allGt
12641286 :: Expression schema from grp params ty
12651287 -> Query schema params '[alias ::: ty]
12661288 -> Condition schema from grp params
12671289allGt = unsafeSubqueryExpression "ALL >"
12681290
1291+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1292+-- >>> printSQL $ myRow `rowAllGt` values_ myRow
1293+-- ROW(1, FALSE) ALL > (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
12691294rowAllGt
12701295 :: SListI row
12711296 => NP (Aliased (Expression schema from grp params)) row
@@ -1273,12 +1298,17 @@ rowAllGt
12731298 -> Condition schema from grp params
12741299rowAllGt = unsafeRowSubqueryExpression "ALL >"
12751300
1301+-- | >>> printSQL $ true `anyGt` values_ (true `as` #foo)
1302+-- TRUE ANY > (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
12761303anyGt
12771304 :: Expression schema from grp params ty
12781305 -> Query schema params '[alias ::: ty]
12791306 -> Condition schema from grp params
12801307anyGt = unsafeSubqueryExpression "ANY >"
12811308
1309+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1310+-- >>> printSQL $ myRow `rowAnyGt` values_ myRow
1311+-- ROW(1, FALSE) ANY > (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
12821312rowAnyGt
12831313 :: SListI row
12841314 => NP (Aliased (Expression schema from grp params)) row
@@ -1286,12 +1316,17 @@ rowAnyGt
12861316 -> Condition schema from grp params
12871317rowAnyGt = unsafeRowSubqueryExpression "ANY >"
12881318
1319+-- | >>> printSQL $ true `allGte` values_ (true `as` #foo)
1320+-- TRUE ALL >= (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
12891321allGte
12901322 :: Expression schema from grp params ty
12911323 -> Query schema params '[alias ::: ty]
12921324 -> Condition schema from grp params
12931325allGte = unsafeSubqueryExpression "ALL >="
12941326
1327+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1328+-- >>> printSQL $ myRow `rowAllGte` values_ myRow
1329+-- ROW(1, FALSE) ALL >= (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
12951330rowAllGte
12961331 :: SListI row
12971332 => NP (Aliased (Expression schema from grp params)) row
@@ -1299,12 +1334,17 @@ rowAllGte
12991334 -> Condition schema from grp params
13001335rowAllGte = unsafeRowSubqueryExpression "ALL >="
13011336
1337+-- | >>> printSQL $ true `anyGte` values_ (true `as` #foo)
1338+-- TRUE ANY >= (SELECT * FROM (VALUES (TRUE)) AS t ("foo"))
13021339anyGte
13031340 :: Expression schema from grp params ty
13041341 -> Query schema params '[alias ::: ty]
13051342 -> Condition schema from grp params
13061343anyGte = unsafeSubqueryExpression "ANY >="
13071344
1345+-- | >>> let myRow = 1 `as` #foo :* false `as` #bar :: NP (Aliased (Expression '[] '[] 'Ungrouped '[])) '["foo" ::: 'NotNull 'PGint2, "bar" ::: 'NotNull 'PGbool]
1346+-- >>> printSQL $ myRow `rowAnyGte` values_ myRow
1347+-- ROW(1, FALSE) ANY >= (SELECT * FROM (VALUES (1, FALSE)) AS t ("foo", "bar"))
13081348rowAnyGte
13091349 :: SListI row
13101350 => NP (Aliased (Expression schema from grp params)) row
@@ -1312,6 +1352,7 @@ rowAnyGte
13121352 -> Condition schema from grp params
13131353rowAnyGte = unsafeRowSubqueryExpression "ANY >="
13141354
1355+-- | A `CommonTableExpression` is an auxiliary statement in a `with` clause.
13151356data CommonTableExpression statement
13161357 (params :: [NullityType])
13171358 (schema0 :: SchemaType)
@@ -1330,6 +1371,7 @@ instance (KnownSymbol alias, schema1 ~ (alias ::: 'View cte ': schema))
13301371 (AlignedList (CommonTableExpression statement params) schema schema1) where
13311372 statement `as` alias = single (statement `as` alias)
13321373
1374+-- | render a `CommonTableExpression`.
13331375renderCommonTableExpression
13341376 :: (forall sch ps row. statement ps sch row -> ByteString)
13351377 -> CommonTableExpression statement params schema0 schema1 -> ByteString
@@ -1337,6 +1379,7 @@ renderCommonTableExpression renderStatement
13371379 (CommonTableExpression (statement `As` alias)) =
13381380 renderAlias alias <+> "AS" <+> parenthesized (renderStatement statement)
13391381
1382+-- | render a non-empty `AlignedList` of `CommonTableExpression`s.
13401383renderCommonTableExpressions
13411384 :: (forall sch ps row. statement ps sch row -> ByteString)
13421385 -> CommonTableExpression statement params schema0 schema1
@@ -1348,9 +1391,9 @@ renderCommonTableExpressions renderStatement cte ctes =
13481391 cte' :>> ctes' -> "," <+>
13491392 renderCommonTableExpressions renderStatement cte' ctes'
13501393
1351−-- | `with` provides a way to write auxiliary statements for use in a larger statement.
1352−-- These statements, which are often referred to as Common Table Expressions or CTEs,
1353−-- can be thought of as defining temporary tables that exist just for one statement.
1394+-- | `with` provides a way to write auxiliary statements for use in a larger query.
1395+-- These statements, referred to as `CommonTableExpression`s, can be thought of as
1396+-- defining temporary tables that exist just for one query.
13541397class With statement where
13551398 with
13561399 :: AlignedList (CommonTableExpression statement params) schema0 schema1