documentation

src/Database/Esqueleto/Experimental/From/CommonTableExpression.hs

@@ -38,7 +38,8 @@ import Database.Esqueleto.Internal.Internal hiding (From(..), from, on)
 -- PostgreSQL 12, non-recursive and side-effect-free queries may be inlined and
 -- optimized accordingly if not declared @MATERIALIZED@ to get the previous
 -- behaviour. See [the PostgreSQL CTE documentation](https://www.postgresql.org/docs/current/queries-with.html#id-1.5.6.12.7),
--- section Materialization, for more information.
+-- section Materialization, for more information. To use a @MATERIALIZED@ query
+-- in Esquelto, see functions 'withMaterialized' and 'withRecursiveMaterialized'.
 --
 -- /Since: 3.4.0.0/
 with :: ( ToAlias a

src/Database/Esqueleto/PostgreSQL.hs

@@ -488,38 +488,32 @@ forShareOf :: LockableEntity a => a -> OnLockedBehavior -> SqlQuery ()
 forShareOf lockableEntities onLockedBehavior =
   putLocking $ PostgresLockingClauses [PostgresLockingKind PostgresForShare (Just $ LockingOfClause lockableEntities) onLockedBehavior]
 
--- | @WITH@ @MATERIALIZED@ clause used to introduce a [Common Table Expression (CTE)](https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression).
--- CTEs are supported in most modern SQL engines and can be useful
--- in performance tuning. In Esqueleto, CTEs should be used as a
--- subquery memoization tactic. When writing plain SQL, CTEs
--- are sometimes used to organize the SQL code, in Esqueleto, this
--- is better achieved through function that return 'SqlQuery' values.
+-- | @WITH@ @MATERIALIZED@ clause is used to introduce a
+-- [Common Table Expression (CTE)](https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression)
+-- with the MATERIALIZED keyword. The MATERIALIZED keyword is only supported in PostgreSQL >= version 12.
+-- In Esqueleto, CTEs should be used as a subquery memoization tactic. PostgreSQL treats a materialized CTE as an optimization fence.
+-- A materialized CTE is always fully calculated, and is not "inlined" with other table joins.
+-- Without the MATERIALIZED keyword, PostgreSQL >= 12 may "inline" the CTE as though it was any other join.
+-- You should always verify that using a materialized CTE will in fact improve your performance
+-- over a regular subquery.
 --
 -- @
 -- select $ do
--- cte <- with subQuery
+-- cte <- withMaterialized subQuery
 -- cteResult <- from cte
 -- where_ $ cteResult ...
 -- pure cteResult
 -- @
 --
--- __WARNING__: In some SQL engines using a CTE can diminish performance.
--- In these engines the CTE is treated as an optimization fence. You should
--- always verify that using a CTE will in fact improve your performance
--- over a regular subquery.
 --
--- Notably, in PostgreSQL prior to version 12, CTEs are always fully
--- calculated, which can potentially significantly pessimize queries. As of
--- PostgreSQL 12, non-recursive and side-effect-free queries may be inlined and
--- optimized accordingly if not declared @MATERIALIZED@ to get the previous
--- behaviour. See [the PostgreSQL CTE documentation](https://www.postgresql.org/docs/current/queries-with.html#id-1.5.6.12.7),
--- section Materialization, for more information.
+-- For more information on materialized CTEs, see the PostgreSQL manual documentation on
+-- [Common Table Expression Materialization](https://www.postgresql.org/docs/14/queries-with.html#id-1.5.6.12.7).
 --
--- /Since: 3.4.0.0/
+-- /Since: 3.5.8.3/
 withMaterialized :: ( ToAlias a
-        , ToAliasReference a
-        , SqlSelect a r
-        ) => SqlQuery a -> SqlQuery (Ex.From a)
+                    , ToAliasReference a
+                    , SqlSelect a r
+                    ) => SqlQuery a -> SqlQuery (Ex.From a)
 withMaterialized query = do
     (ret, sideData) <- Q $ W.censor (\_ -> mempty) $ W.listen $ unQ query
     aliasedValue <- toAlias ret
@@ -530,42 +524,48 @@ withMaterialized query = do
     ref <- toAliasReference ident aliasedValue
     pure $ Ex.From $ pure (ref, (\_ info -> (useIdent info ident, mempty)))
 
--- | @WITH@ clause used to introduce a [Common Table Expression (CTE)](https://en.wikipedia.org/wiki/Hierarchical_and_recursive_queries_in_SQL#Common_table_expression).
--- CTEs are supported in most modern SQL engines and can be useful
--- in performance tuning. In Esqueleto, CTEs should be used as a
--- subquery memoization tactic. When writing plain SQL, CTEs
--- are sometimes used to organize the SQL code, in Esqueleto, this
--- is better achieved through function that return 'SqlQuery' values.
+-- | @WITH@ @RECURSIVE@ @MATERIALIZED@ allows one to make a recursive subquery, which can
+-- reference itself. The @MATERIALIZED@ keyword will ensure the CTE is fully calculated.
+-- See documentation on 'withMaterialized'
+-- This is supported in PostgreSQL >= 12. See also 'withRecursive'
 --
 -- @
 -- select $ do
--- cte <- with subQuery
--- cteResult <- from cte
--- where_ $ cteResult ...
--- pure cteResult
+-- cte <- withRecursiveMaterialized
+--          (do
+--              person <- from $ table \@Person
+--              where_ $ person ^. PersonId ==. val personId
+--              pure person
+--          )
+--          unionAll_
+--          (\\self -> do
+--              (p :& f :& p2 :& pSelf) <- from self
+--                       \`innerJoin\` $ table \@Follow
+--                       \`on\` (\\(p :& f) ->
+--                               p ^. PersonId ==. f ^. FollowFollower)
+--                       \`innerJoin\` $ table \@Person
+--                       \`on\` (\\(p :& f :& p2) ->
+--                               f ^. FollowFollowed ==. p2 ^. PersonId)
+--                       \`leftJoin\` self
+--                       \`on\` (\\(_ :& _ :& p2 :& pSelf) ->
+--                               just (p2 ^. PersonId) ==. pSelf ?. PersonId)
+--              where_ $ isNothing (pSelf ?. PersonId)
+--              groupBy (p2 ^. PersonId)
+--              pure p2
+--          )
+-- from cte
 -- @
 --
--- __WARNING__: In some SQL engines using a CTE can diminish performance.
--- In these engines the CTE is treated as an optimization fence. You should
--- always verify that using a CTE will in fact improve your performance
--- over a regular subquery.
---
--- Notably, in PostgreSQL prior to version 12, CTEs are always fully
--- calculated, which can potentially significantly pessimize queries. As of
--- PostgreSQL 12, non-recursive and side-effect-free queries may be inlined and
--- optimized accordingly if not declared @MATERIALIZED@ to get the previous
--- behaviour. See [the PostgreSQL CTE documentation](https://www.postgresql.org/docs/current/queries-with.html#id-1.5.6.12.7),
--- section Materialization, for more information.
---
--- /Since: 3.4.0.0/
-withRecursiveMaterialized :: ( ToAlias a
-                 , ToAliasReference a
-                 , SqlSelect a r
-                 )
-              => SqlQuery a
-              -> UnionKind
-              -> (Ex.From a -> SqlQuery a)
-              -> SqlQuery (Ex.From a)
+-- /Since: 3.5.8.3/
+withRecursiveMaterialized
+  :: ( ToAlias a
+     , ToAliasReference a
+     , SqlSelect a r
+     )
+  => SqlQuery a
+  -> UnionKind
+  -> (Ex.From a -> SqlQuery a)
+  -> SqlQuery (Ex.From a)
 withRecursiveMaterialized baseCase unionKind recursiveCase = do
     (ret, sideData) <- Q $ W.censor (\_ -> mempty) $ W.listen $ unQ baseCase
     aliasedValue <- toAlias ret