@@ -0,0 +1,96 @@
1+Writing queries with ``Query``
2+==============================
4+To fetch data from a database, Rel8 allows you to write ``SELECT`` queries using
5+the ``Query`` monad. While this monad might look a little different from
6+ordinary SQL, it is equal in expressivity, but due to Haskell's ``do`` notation
7+we get to benefit from all the means of abstraction available.
9+Understanding the ``Query`` monad
10+---------------------------------
12+Before we look at special functions for working with ``Query``, we'll first take
13+a moment to understand how the ``Query`` monad works. First, what does the type
14+``Query a`` *mean*? To be a ``Query a`` means to be a SQL ``SELECT`` query that
15+selects rows of type ``a``. Usually ``a`` will be an instance of ``Table Expr``,
16+such as ``Expr Text``, or maybe ``BlogPostComment Expr``.
18+As ``Query`` is an instance of ``Monad`` means that we already have three
19+familiar APIs to work with: ``Functor``, ``Applicative``, and ``Monad``.
24+The ``Functor`` instance gives us access to ``fmap``, and its type is::
26+ fmap :: (a -> b) -> Query a -> Query b
28+``fmap`` uniformly transforms rows of one type into rows of another type. In
29+SQL, this is corresponds to a *projection*. For example, if we have a ``Query
30+(User Expr)``, we might do ``fmap userId`` to transform this into a ``Query
36+The ``Applicative`` instance for ``Query`` gives us::
39+ (<*>) :: Query (a -> b) -> Query a -> Query b
41+``pure`` constructs a ``Query`` that returns exactly one row - a row containing
42+the ``a`` that was given. This might seem fairly pointless, but it's an
43+important ``Query`` when compared with ``(<*>)``. The ``<*>`` combines two
44+``Query``\s by taking their *cartesian product*, followed by a projection that
45+combines each row into a new row.
47+One example of using the ``Applicative`` operators is to combine two ``Query``\s
50+ pure (,) <*> queryA <*> queryB
55+The final type class to discuss is ``Monad Query``. ``Monad Query`` has two
58+ return :: a -> Query a
59+ (>>=) :: Query a -> (a -> Query b) -> Query b
61+``return`` is the same ``pure``, so we won't discuss this further. The much more
62+interesting operation is ``>>=`` - commonly referred to as "bind". This operator
63+allows you to *extend* a ``Query`` with a new query. In SQL this is also similar
64+to a cartesian product, but uses the ``LATERAL`` modifier to allow the second
65+query to refer to columns from the first.
67+This extension operator allows you to expand each row in the first query into
68+zero, one, or many rows, according to the given function. For example, if we
69+have a database of orders, we might write::
71+ getAllOrders >>= \order -> getUserById (orderUserId order)
73+This ``Query`` will return, for each ``Order``, the ``User`` who placed that
74+order. In this case, this is a one-to-one relationship, so we get back exactly
75+as many rows as there are orders.
77+Going in the other direction, we have::
79+ getAllUsers >>= \user -> getOrdersForUser (userId user)
81+This is a different query, as we start by fetching all ``User``\s, and for each
82+user find all ``Order``\s they have placed. This ``Query`` has a different
83+cardinality, as we're following a one-to-many relationship: any ``User`` may
84+have zero, one, or many orders.
86+Haskell has special syntax for working with monads - ``do`` notation. ``do``
87+notation allows you to write these queries in a simpler form, where we don't
88+have to introduce functions. Expanding on the latter query, we could write::
90+ do user <- getAllUsers
91+ order <- getOrdersForUser (user)
94+Now we have a query that, for each ``User``, fetches all orders for that user.
95+The final ``return`` means that for each ``User`` and ``Order``, we'll return a