@@ -40,6 +40,39 @@ optional = mapOpaleye $ Opaleye.QueryArr . go
40 condition = toPrimExpr true
40 condition = toPrimExpr true
43+-- | Filter out 'MaybeTable's, returning only the tables that are not-null.
45+-- This operation can be used to "undo" the effect of 'optional', which
46+-- operationally is like turning a @LEFT JOIN@ back into a full @JOIN@. You
47+-- can think of this as analogous to 'Data.Maybe.catMaybes'.
49+-- To see this in action, first consider the following 'optional' query:
53+-- author <- each authorSchema
54+-- maybeRel8 <- optional $
56+-- >>= filter (\p -> projectAuthorId p ==. authorId author)
57+-- >>= filter (\p -> projectName p ==. "rel8")
58+-- return (authorName author, projectName <$> maybeRel8)
60+-- [("Ollie",Just "rel8"),("Bryan O'Sullivan",Nothing),("Emily Pillmore",Nothing)]
62+-- Here @optional@ is acting as a @LEFT JOIN@. We can turn this into a proper
63+-- join by using @catMaybeTable@ to filter out rows where the join failed:
67+-- author <- each authorSchema
68+-- maybeRel8 <- optional $
70+-- >>= filter (\p -> projectAuthorId p ==. authorId author)
71+-- >>= filter (\p -> projectName p ==. "rel8")
72+-- rel8 <- catMaybeTable maybeRel8
73+-- return (authorName author, projectName rel8)
43catMaybeTable :: MaybeTable a -> Query a
76catMaybeTable :: MaybeTable a -> Query a
44catMaybeTable ma@(MaybeTable _ a) = do
77catMaybeTable ma@(MaybeTable _ a) = do
45 where_ $ isJustTable ma
78 where_ $ isJustTable ma