Improve documentation for ordering nulls

How do I order by a nullable column? This doesn't work:

data SomeTable f = SomeTable {
  someColumn :: Column f (Maybe UTCTime)
}

-- ...

someQuery = do
  row <- each someTableSchema
  orderBy (someColumn >$< desc) row

GHC complains:

    • No instance for (DBOrd (Maybe UTCTime))
        arising from a use of ‘desc’
    • In the second argument of ‘(>$<)’, namely ‘desc’
      In the first argument of ‘orderBy’, namely ‘(someColumn >$< desc)’
      In the expression: orderBy (someColumn >$< desc)

I was surprised to discover that there is no instance (DBOrd a) => DBOrd (Maybe a). Is this missing, or is this intentional? Is there a better way to order a nullable field?

Hi @liftM,

To order by nullable, you need to use nullsFirst (or nullsLast). Also, orderBy operates on a whole Query rather than a single row (much like how sort operates on a [a] rather than just an a). Putting this all together, we have:

someQuery = orderBy (someColumn >$< nullsFirst desc) $ do
  each someTableSchema

Ah, thanks! It wasn't clear that this is how nullsFirst and nullsLast was meant to be used. Thanks for the assist!

@liftM Ok, sounds like we should improve the documentation around this. I'll re-open this and repurpose the issue.

I think also something helpful would be explicitly categorizing which query functions are monadic guards (like where_), which are monadic functions (like with and filter), and which are query functions (like orderBy). I eventually puzzled most of this out on my own using the examples (which are really helpful!), but it took me a while to realize that different query modifiers were meant to be used in different ways.