@@ -203,9 +203,40 @@ and this query can be written in Rel8 as::
203203Left (outer) joins with ``optional``
204204------------------------------------
205205
206−.. todo::
206+A left join is like an inner join, but allows for the possibility of the join to
207+"fail". You use left joins when you want to join optional information against a
208+row.
207209
208− Write this
210+In Rel8, a ``LEFT JOIN`` is introduced by converting an inner join with
211+``optional``. While this approach might seem a little foreign at first, it has a
212+strong similarity with the ``Control.Applicative.optional`` function, and allows
213+you to reuse previous code.
214+
215+To see an example of this, let's assume that we want to get the latest comment
216+for each blog post. Not all blog posts are popular though, so some blog posts
217+might have no comment at all. To write this in Rel8, we could write::
218+
219+ blogPost <- each blogPostSchema
220+
221+ latestComment <-
222+ optional $ limit 1 $
223+ orderBy (commentCreatedAt >$< desc) $
224+ commentsForBlogPost blogPost
225+
226+``optional`` will transform a ``Query a`` into a ``Query (MaybeTable a)``.
227+``MaybeTable`` is similar to the normal ``Maybe`` data type in Haskell, and
228+represents the choice between a ``justTable x`` and a ``nothingTable`` (like
229+``Just x`` and ``Nothing``, respectively). When you execute a query containing
230+``MaybeTable x`` with ``select``, Rel8 will return ``Maybe x``. ``MaybeTable``
231+comes with a library of routines, similar to the functions that can be used to
232+operate on ``Maybe``. For more details, see the API documentation.
233+
234+.. hint::
235+
236+ ``optional`` converts an inner join into a ``LEFT JOIN``, but you can also go
237+ the other way - and turn a ``LEFT JOIN`` back into an inner join! To do this,
238+ you can use ``catMaybeTable``, which will select only the rows when the left
239+ join was successful.
209240
210241Ordering results
211242----------------