@@ -74,6 +74,36 @@ type family UnwrapDefault a where
7474 UnwrapDefault a = a
7575
7676
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.
81+--
82+-- To understand why this type family is special, let's consider a simple
83+-- higher-kinded data type of Haskell packages:
84+--
85+-- >>> :{
86+-- data Package f = Package
87+-- { packageName :: Column f Text
88+-- , packageAuthor :: Column f Text
89+-- }
90+-- :}
91+--
92+-- In queries, @f@ will be some type of 'Expr', and @Column Expr a@ reduces to
93+-- just @Expr a@:
94+--
95+-- >>> :t packageName (undefined :: Package Expr)
96+-- packageName (undefined :: Package Expr) :: Expr Text
97+--
98+-- When we 'select' queries of this type, @f@ will be instantiated as
99+-- @Identity@, at which point all wrapping entire disappears:
100+--
101+-- >>> :t packageName (undefined :: Package Identity)
102+-- packageName (undefined :: Package Identity) :: Text
103+--
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.
77107type Column :: K.Context -> Type -> Type
78108type Column context a =
79109 Field context (GetLabel a)