NB Opaleye exports Opaleye.Table.optional from the top level. If you want this optional you will have to import it from this module.

Convenient access to lateral left/right join functionality. Performs a LATERAL LEFT JOIN under the hood and has behaviour equivalent to the following Haskell function:

optional :: [a] -> [Maybe a]
optional q = case q of
    [] -> [Nothing]
    xs -> map Just xs

That is, if q :: SelectArr i a returns no rows, optional q :: SelectArr i (MaybeFields a) returns exactly one "Nothing" row. Otherwise, optional q returns exactly the rows of q wrapped in "Just". For example,

> let l1 = ["one", "two", "three"] :: [Field SqlText]
> runSelect conn (optional (valuesSafe l1)) :: IO [Maybe String]
[Just "one", Just "two", Just "three"]

> let l2 = [] :: [Field SqlText]
> runSelect conn (optional (valuesSafe l2)) :: IO [Maybe String]
[Nothing]

optionalRestrict is a special case of optional and could be written in terms of optional as follows (except that optionalRestrict doesn't use LATERAL under the hood and optional does).

optionalRestrict q = optional $ proc cond -> do
  a <- q -< ()
  restrict -< cond a
  returnA -< a

Convenient access to left/right join functionality. Performs a LEFT JOIN under the hood and has behaviour equivalent to the following Haskell function:

optionalRestrict :: [a] -> (a -> Bool) -> [Maybe a]
optionalRestrict xs p =
   case filter p xs of []  -> [Nothing]
                       xs' -> map Just xs'

For example,

> let l = [1, 10, 100, 1000] :: [Field SqlInt4]
> runSelect conn (proc () -> optionalRestrict (valuesSafe l) -< (.> 100000)) :: IO [Maybe Int]
[Nothing]

> runSelect conn (proc () -> optionalRestrict (valuesSafe l) -< (.> 15)) :: IO [Maybe Int]
[Just 100,Just 1000]

See the documentation of leftJoin for how to use optionalRestrict to replace leftJoin (and by symmetry, rightJoin).

We suggest you use optionalRestrict instead. Instead of writing "leftJoin qL qR cond" you can write

proc () -> do
  fieldsL <- qL -< ()
  maybeFieldsR <- optionalRestrict qR -< curry cond fieldsL
  returnA -< (fieldsL, maybeFieldsR)

Typically everything except the optionalRestrict line can be inlined in surrounding arrow notation. In such cases, readability and maintainibility increase dramatically.

We suggest you don't use this. optionalRestrict is probably better for your use case. leftJoinA is the same as optionalRestrict except without the return type wrapped in MaybeFields.

We suggest you use optionalRestrict instead. See leftJoin for more details.