Group by documentation (#170)

* Group by documentation

changelog.md

@@ -1,3 +1,9 @@
+3.3.1.1
+========
+
+- @parsonsmatt
+  - [#170](https://github.com/bitemyapp/esqueleto/pull/170) Add documentation to `groupBy` to explain tuple nesting.
+
 3.3.1
 ========
 

esqueleto.cabal

@@ -1,7 +1,7 @@
 cabal-version: 1.12
 
 name:           esqueleto
-version:        3.3.1
+version:        3.3.1.1
 synopsis:       Type-safe EDSL for SQL queries on persistent backends.
 description:    @esqueleto@ is a bare bones, type-safe EDSL for SQL queries that works with unmodified @persistent@ SQL backends.  Its language closely resembles SQL, so you don't have to learn new concepts, just new syntax, and it's fairly easy to predict the generated SQL and optimize it for your backend. Most kinds of errors committed when writing SQL are caught as compile-time errors---although it is possible to write type-checked @esqueleto@ queries that fail at runtime.
                 .

src/Database/Esqueleto.hs

@@ -453,7 +453,8 @@ deleteKey = Database.Persist.delete
 --   'where_' (foo '^.' FooParentId '==.' 'val' parentId)
 --   'pure' (foo, bar)
 -- @
--- /Since: 3.1.2/
+--
+-- @since 3.1.2
 associateJoin
   :: forall e1 e0
    . Ord (Key e0)

src/Database/Esqueleto/Internal/Internal.hs

@@ -213,6 +213,25 @@ on expr = Q $ W.tell mempty { sdFromClause = [OnClause expr] }
 --   print name
 --   print (count :: Int)
 -- @
+--
+-- === Need more columns?
+--
+-- The 'ToSomeValues' class is defined for 'SqlExpr' and tuples of 'SqlExpr's.
+-- We only have definitions for up to 8 elements in a tuple right now, so it's
+-- possible that you may need to have more than 8 elements.
+--
+-- For example, consider a query with a 'groupBy' call like this:
+--
+-- @
+-- groupBy (e0, e1, e2, e3, e4, e5, e6, e7)
+-- @
+--
+-- This is the biggest you can get with a single tuple. However, you can easily
+-- nest the tuples to add more:
+--
+-- @
+-- groupBy ((e0, e1, e2, e3, e4, e5, e6, e7), e8, e9)
+-- @
 groupBy :: (ToSomeValues a) => a -> SqlQuery ()
 groupBy expr = Q $ W.tell mempty { sdGroupByClause = GroupBy $ toSomeValues expr }
 

test/Common/Test.hs

@@ -1355,6 +1355,20 @@ testUpdate run = do
         liftIO $ ret `shouldMatchList` [ (Value l3k, Value 7)
                                        , (Value l1k, Value 3) ]
 
+    it "GROUP BY works with nested tuples" $ do
+      run $ do
+        l1k <- insert l1
+        l3k <- insert l3
+        mapM_ (\k -> insert $ Deed k l1k) (map show [1..3 :: Int])
+
+        mapM_ (\k -> insert $ Deed k l3k) (map show [4..10 :: Int])
+
+        (ret :: [(Value (Key Lord), Value Int)]) <- select $ from $
+          \ ( lord `InnerJoin` deed ) -> do
+          on $ lord ^. LordId ==. deed ^. DeedOwnerId
+          groupBy ((lord ^. LordId, lord ^. LordDogs), deed ^. DeedContract)
+          return (lord ^. LordId, count $ deed ^. DeedId)
+        liftIO $ length ret `shouldBe` 10
     it "GROUP BY works with HAVING" $
       run $ do
         p1k <- insert p1