@@ -21,6 +21,10 @@ import Rel8.Table ( fromColumns, toColumns )
2121import Rel8.Table.Recontextualize ( Inserts )
2222
2323
24+-- | @toInsert@ converts a 'Table' of 'Expr's into a 'Table' that can be used
25+-- with 'insert'. This will override any columns that have default values to
26+-- use exactly what is given. If you want to use default values, you can either
27+-- override the result of @toInsert@, or use 'toInsertDefaults'.
2428toInsert :: Inserts exprs inserts => exprs -> inserts
2529toInsert (toColumns -> exprs) = fromColumns $ htabulate $ \field ->
2630 case hfield hspecs field of
@@ -30,6 +34,14 @@ toInsert (toColumns -> exprs) = fromColumns $ htabulate $ \field ->
3034 SOptional -> OptionalInsert (Just expr)
3135
3236
37+-- | @toInsertDefaults@ converts a 'Table' of 'Expr's into a 'Table' that can
38+-- be used with 'insert'. Any columns that have a default value will override
39+-- whatever is in the input expression.
40+--
41+-- One example where this is useful is for any table that has a special @id@
42+-- column, which has a default value to draw a new value from a sequence. If we
43+-- use 'toInsertDefaults', we can provide a dummy value that will be replaced
44+-- with a call to @DEFAULT@.
3345toInsertDefaults :: Inserts exprs inserts => exprs -> inserts
3446toInsertDefaults (toColumns -> exprs) = fromColumns $ htabulate $ \field ->
3547 case hfield hspecs field of