Modelling sum types

[chrisdone-artificial]

Hey @ocharles. We're experimenting with Rel8 at Artificial and enjoying it!

I'd like to handle tables like this:

data Task f = Pending | Complete (CompletedTask f)
data CompletedTask f = CompletedTask {
  date :: f UTCTime, ...
}

create table task (serial id primary key, tag varchar(32) not null, date timestamp, ...)

Then have a Rel8able instance and tableSchema that inspects the tag and based on the tag, will produce either Pending or Complete.

How would you do this with Rel8?

I feel like Rel8.Table.Either is related, but I'm not sure how. That seems to use a special field "isRight", which is a little bit more specific to Either than a more general sum type thing. 🤔

[chrisdone-artificial]

Related is modelling things like data_int, data_text, data_date tables as one, which I think can be nicely modelled with Either. But in this case I have one table that encodes multiple things at once.

[ocharles]

Hey @chrisdone-artificial, cool to hear you're having a play with Rel8!

This is an interesting question, and I think we've got support for this, or we're at least pretty close. For Task, you'll need to use the unfortunately undocumented ADT stuff here. I believe it will be something like:

data Task f = Pending | Complete (CompletedTask f)
  deriving stock Generic
  deriving anyclass Rel8able

data CompletedTask f = CompletedTask
  { date :: Column f UTCTime, ...
  }
  deriving stock Generic
  deriving anyclass Rel8able

You would then use nameADT to specify all the column names. The first argument is the name of the "tag" column. When working with this in a Query (the Expr context), you'll actually be working with a ADT Task Expr (as we can't give you an actual Task because we wouldn't know which constructor to use). When you select rows, you'll get back a Task Result.

Have a play with this and maybe try seeing what the type of nameTable @Task is. I'll have a bit more time tomorrow to look a bit deeper, but maybe this will unstick you.

[chrisdone-artificial]

Thanks @ocharles! The hints about ADT are enough that we can do a little more experimenting.

[shane-circuithub]

Here's an example of how you could embed that into a Rel8able, which is probably what you want to do:

{-# language DeriveAnyClass #-}
{-# language DeriveGeneric #-}
{-# language DisambiguateRecordFields #-}
{-# language OverloadedStrings #-}
{-# language TypeApplications #-}

-- base
import Data.Int ( Int64 )
import GHC.Generics ( Generic )

-- rel8
import Rel8

-- time
import Data.Time ( UTCTime )


data TaskTable f = TaskTable
  { id :: Column f Int64
  , task :: HADT f Task
  }
  deriving (Generic, Rel8able)


data Task f = Pending | Complete (CompletedTask f)
  deriving (Generic)


data CompletedTask f = CompletedTask
  { date :: Column f UTCTime
  }
  deriving (Generic, Rel8able)


main :: IO ()
main = putStrLn $ showQuery $ each TableSchema
  { schema = Nothing
  , name = "task"
  , columns = TaskTable
      { id = "id"
      , task =
          nameADT @Task
            "tag"
            CompletedTask
              { date = "date"
              }
      }
  }

[chrisdone-artificial]

@shane-circuithub Now that I came to take a proper look at the API, I see that most of the types are actually magic 🪄 🧙‍♀️ built on generics. We had some open questions from what's demonstrated here:

1. The "tag" - does this specify the column of the table from which to get the tag, and if so, how does it store/read the given constructor, is based on the name so e.g. "CompletedTask"?
2. There isn't mention of the Pending constructor here, how does one list multiple constructors? How do nameADT, constructADT, deconstructADT, etc. all relate and function?

The haddocks aren't very enlightening:

The type-level programming going on here is way over my head.

Can you shed some light on the mechanics?

[chrisdone-artificial]

Follow-up: running the code shows that "tag" refers to the table column:

SELECT
CAST("id0_1" AS int8) as "id",
CAST("tag1_1" AS text) as "task/tag",
CAST("date2_1" AS timestamptz) as "task/Complete/_1/date" --- the "Complete" constructor features here, which is interesting
FROM (SELECT
      *
      FROM (SELECT
            "id" as "id0_1",
            "tag" as "tag1_1",  --- <---- HERE: tag field
            "date" as "date2_1"
            FROM "task" as "T1") as "T1") as "T1"

[shane-circuithub]

These are great questions! I never wrote any proper documentation for this stuff and it's been a long time since I looked at it, but I'll try to walk you through how get these types less scary.

But as for your first question, yes, "tag" is just whatever you want to call the tag column in your database schema. It doesn't have to be exactly "tag", you could call it "task_type" or whatever if you preferred — the first argument to nameADT is what determines this. As for the data that's actually stored in this column, yes, it will be text. Either 'Pending' or 'Complete', the constructor names from the definition of Task:

data Task f = Pending | Complete (CompletedTask f)

The reason the Pending constructor doesn't explicitly show up is because it doesn't have any fields. So the table doesn't need to contain any columns in the table that specifically pertain to Pending. A tag with the value 'Pending' is sufficient to represent a Pending Haskell value.

I'll now show the types of all the above functions when applied specifically to Task and try to explain what they mean.

buildADT

buildADT is for constructing values of Task in the Expr context. buildADT needs two type-level arguments before its type makes any sense. The first argument is the type of the "ADT", which in our case is Task. The second is the name of the constructor we want to use. So that means we have the following possible instantiations of buildADT for Task:

> :t buildADT @Task @"Pending"
buildADT @Task @"Pending" :: ADT Task Expr
> :t buildADT @Task @"Complete" 
buildADT @Task @"Complete" :: CompletedTask Expr -> ADT Task Expr

Note that as the Pending constructor has no fields, buildADT @Task @"Pending" is equivalent to lit Pending. But buildADT @Task @"Complete" is not the same as lit . Complete:

> :t lit . Complete
lit . Complete :: CompletedTask Result -> ADT Task Expr

Note that the former takes a CompletedTask Expr while the latter takes a CompletedTask Result. The former is more powerful because you can construct Tasks using dynamic values coming a database query.

To show what this can look like in SQL, consider:

> :{
showQuery $ values
  [ buildADT @Task @"Pending"
  , buildADT @Task @"Complete" CompletedTask {date = Rel8.Expr.Time.now}
  ]
:}

This produces the following SQL:

SELECT
CAST("values0_1" AS text) as "tag",
CAST("values1_1" AS timestamptz) as "Complete/_1/date"
FROM (SELECT
      *
      FROM (SELECT "column1" as "values0_1",
                   "column2" as "values1_1"
            FROM
            (VALUES
             (CAST(E'Pending' AS text),CAST(NULL AS timestamptz)),
             (CAST(E'Complete' AS text),CAST(now() AS timestamptz))) as "V") as "T1") as "T1"

This is what you get if you run it in psql:

   tag    |       Complete/_1/date        
----------+-------------------------------
 Pending  | 
 Complete | 2022-05-19 21:28:23.969065+00
(2 rows)

constructADT

constructADT is less convenient but more general alternative to buildADT. It requires only one type-level argument for its type to make sense:

> :t constructADT @Task
constructADT @Task
  :: (forall r. r -> (CompletedTask Expr -> r) -> r) -> ADT Task Expr

This might still seem a bit opaque, but basically it gives you a Church-encoded constructor for arbitrary algebraic data types. You might use it as follows:

let
  pending :: ADT Task Expr
  pending = constructADT @Task $ \pending _complete -> pending

  complete :: ADT Task Expr
  complete = constructADT @Task $ \_pending complete -> complete CompletedTask {date = Rel8.Expr.Time.now}

These values are otherwise identical to the ones we saw above with buildADT, it's just a different style of constructing them.

deconstructADT

deconstructADT is basically the inverse of constructADT. It again only requires the single type-level argument:

> :t deconstructADT @Task
deconstructADT @Task
  :: Table Expr r => r -> (CompletedTask Expr -> r) -> ADT Task Expr -> r

Basically, it gives you a Church-encoded deconstructor in the vein of the maybe and either functions from the Prelude. You could use it as follows:

let
  isPending :: ADT Task Expr -> Expr Bool
  isPending = deconstructADT @Task true (const false)
  isComplete :: ADT Task Expr -> Expr Bool
  isComplete = deconstructADT @Task false (const true)

You could even use it to extract individual fields from particular constructors:

let
  completedAt :: ADT Task Expr -> Expr (Maybe UTCTime)
  completedAt = deconstructADT @Task null (\CompletedTask {date} -> nullify date)

nameADT

This is for building ADT values in the Name context; basically, to give names to the necessary columns when embedding an ADT inside a table you want to be able to SELECT from and INSERT into.

Let's look at its type when applied to Task:

:t nameADT @Task
nameADT @Task
  :: Name Tag -> CompletedTask Name -> ADT Task Name

The first argument is always the name of the tag; "tag" in the example I used above but you could call it something else if you wanted. Then the subsequent arguments are just each field from each constructor. The Pending constructor comes first, but it has zero fields, which means we skip straight to the Complete constructor. That has one field, CompletedTask f, so we need to supply a CompletedTask Name. As that is all the fields from all the constructors of Task, that's sufficient to build an ADT Task Name. Does that make sense?

aggregateADT

This is left as an exercise to the reader ;)

Miscellaneous

1. Note that the order of the arguments for all of these functions is determined by the order of the constructors in the data definition. If it were data Task = Complete (CompletedTask f) | Pending then the order of all the invocations of constructADT and deconstructADT would need to change.
2. Maybe this is obvious, but just to spell it out: once you're in the Result context, you can of course construct Task values normally and use standard Haskell pattern-matching. constructADT and deconstructADT are specifically only needed in the Expr context, and they allow you to do the equivalent of pattern matching in PostgreSQL.
3. I suggest defining other algebraic data types with different combinations of constructors and fields and looking at the types of the above functions when applied to them. I think you'll develop an intuition for how they work pretty quickly.

[chrisdone-artificial]

Thanks a lot @shane-circuithub for the long write-up! ❤️ I made a larger example based on your explanation. The ability to do well-typed case analysis at the SQL level is excellent.

I'll open a PR for the rel8 docs with these docs.

[chrisdone-artificial]

For posterity, opened PR here.