@@ -74,6 +74,36 @@ type family UnwrapDefault a where
74 UnwrapDefault a = a
74 UnwrapDefault a = a
77+-- | The @Column@ type family should be used to indicate which fields of your
78+-- data types are single columns in queries. This type family has special
79+-- support when a query is executed, allowing you to use a single data type for
80+-- both query data and rows decoded to Haskell.
82+-- To understand why this type family is special, let's consider a simple
83+-- higher-kinded data type of Haskell packages:
86+-- data Package f = Package
87+-- { packageName :: Column f Text
88+-- , packageAuthor :: Column f Text
92+-- In queries, @f@ will be some type of 'Expr', and @Column Expr a@ reduces to
95+-- >>> :t packageName (undefined :: Package Expr)
96+-- packageName (undefined :: Package Expr) :: Expr Text
98+-- When we 'select' queries of this type, @f@ will be instantiated as
99+-- @Identity@, at which point all wrapping entire disappears:
101+-- >>> :t packageName (undefined :: Package Identity)
102+-- packageName (undefined :: Package Identity) :: Text
104+-- In @rel8@ we try hard to always know what @f@ is, which means holes should
105+-- mention precise types, rather than the @Column@ type family. You should only
106+-- need to be aware of the type family when defining your table types.
77type Column :: K.Context -> Type -> Type
107type Column :: K.Context -> Type -> Type
78type Column context a =
108type Column context a =
79 Field context (GetLabel a)
109 Field context (GetLabel a)