duckdb-simple-1.0.0.0: src/Database/DuckDB/Simple/Generic.hs
{-# LANGUAGE AllowAmbiguousTypes #-}
{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE DataKinds #-}
{-# LANGUAGE DefaultSignatures #-}
{-# LANGUAGE FlexibleContexts #-}
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE MultiParamTypeClasses #-}
{-# LANGUAGE NamedFieldPuns #-}
{-# LANGUAGE ScopedTypeVariables #-}
{-# LANGUAGE TypeApplications #-}
{-# LANGUAGE TypeFamilies #-}
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE UndecidableInstances #-}
-- |
-- Module : Database.DuckDB.Simple.Generic
-- Description : Generic helpers for encoding Haskell ADTs as DuckDB structs/unions.
--
-- Encode and decode algebraic data types through @ToField@/@FromField@ with
-- GHC generics. The mapping is:
--
-- * /Product types/ (records or tuples) whose fields already satisfy @DuckValue@
-- are encoded as STRUCT values. Record fields retain their selector name;
-- positional products fall back to @field1@, @field2@, …
-- * /Sum types/ (:+:) become UNION values. Each constructor becomes a union
-- member; payloads are encoded as structs (a STRUCT without fields for a
-- constructor without fields).
--
-- Each field needs a @DuckValue@ instance with a finite logical type. A nested
-- user-defined type needs its own instance.
--
-- Encode a product:
--
-- > data User = User { userId :: Int64, userName :: Text }
-- > deriving stock (Generic)
-- >
-- > genericToFieldValue (User 1 "alice")
-- > -- A FieldStruct with the fields userId = FieldInt64 1 and userName = FieldText "alice".
--
-- For sum types:
--
-- > data Shape
-- > = Circle Double
-- > | Rectangle Double Double
-- > | Origin
-- > deriving stock (Generic)
--
-- Constructors are turned into a union with the members @Circle@ (a STRUCT with
-- the field @field1@), @Rectangle@ (a STRUCT with the fields @field1@ and
-- @field2@), and @Origin@ (a STRUCT without fields).
--
-- Derive instances with @DerivingVia@ and the @ViaDuckDB@ newtype:
--
-- > data User = User { userId :: Int64, userName :: Text }
-- > deriving stock (Generic)
-- > deriving (DuckDBColumnType, ToField, FromField) via (ViaDuckDB User)
--
-- The derived instances encode and decode STRUCT/UNION representations.
-- Also derive @ToDuckValue@ to use the type as a column of a typed table function,
-- as an argument or result of a typed aggregate function, or as the result of
-- a scalar function.
--
-- === Extending this module
--
-- The implementation has these parts:
--
-- * @DuckValue@ covers leaf-level conversions between Haskell values, DuckDB
-- @FieldValue@s, and logical type metadata.
-- * @GToField@ and the related classes convert the generic representation to
-- structs or unions. They keep the logical type information for parameter
-- binding.
-- * @ViaDuckDB@ supplies the deriving-via instances.
--
-- Follow this structure when you add a feature, and document each new class.
module Database.DuckDB.Simple.Generic (
-- * Field-level primitives
DuckValue (..),
typedFromField,
GToField (),
GFromField (),
-- * Generic encoding/decoding for ADTs
genericToFieldValue,
genericFromFieldValue,
genericLogicalType,
genericToStructValue,
genericToUnionValue,
-- * DerivingVia helper
ViaDuckDB (..),
) where
import Control.Exception (toException)
import Control.Monad (unless)
import Data.Array (Array, elems, listArray)
import qualified Data.ByteString as BS
import Data.Int (Int16, Int32, Int64, Int8)
import Data.List (intercalate, stripPrefix)
import qualified Data.Map.Strict as Map
import Data.Maybe (fromMaybe, isJust)
import Data.Proxy (Proxy (..))
import Data.Text (Text)
import qualified Data.Text as Text
import Data.Time (UTCTime)
import Data.Time.Calendar (Day)
import Data.Time.LocalTime (LocalTime, TimeOfDay)
import Data.Typeable (Typeable)
import qualified Data.UUID as UUID
import Data.Word (Word16, Word32, Word64, Word8)
import Database.DuckDB.Simple.Conversion (
Conversion,
conversionError,
mapConversionErrors,
mapConversionErrorsWith,
)
import Database.DuckDB.Simple.Element (containsType, valueTypeName)
import Database.DuckDB.Simple.FromField (
Field (..),
FieldValue (..),
FromField (..),
IntervalValue (..),
ResultError (..),
SizedArray,
TimeWithZone (..),
fieldTypeName,
returnError,
sizedArrayFromList,
sizedArrayToArray,
)
import Database.DuckDB.Simple.Internal (duckDBTypeToName)
import Database.DuckDB.Simple.LogicalRep (
LogicalTypeRep (..),
StructField (..),
StructValue (..),
TypeDeclaration (..),
UnionMemberType (..),
UnionValue (..),
listElementType,
mapEntryTypes,
)
import Database.DuckDB.Simple.Native
import Database.DuckDB.Simple.Time (Unbounded (..))
import Database.DuckDB.Simple.ToField (DuckDBColumnType (..), ToDuckValue (..), ToField (..))
import Database.DuckDB.Simple.Variant (Variant (..))
import GHC.Generics
import GHC.TypeLits (KnownNat, natVal)
import Numeric.Natural (Natural)
--------------------------------------------------------------------------------
-- DuckValue: bridge between Haskell scalars and FieldValue/LogicalTypeRep
-- | Types that can appear inside generated structs/unions.
--
-- A @DuckValue@ instance must provide:
--
-- * encoding to @FieldValue@
-- * logical type metadata (@duckLogicalType@)
-- * decoding from @FieldValue@
--
-- The primitive instances define the scalar representations for generic
-- conversion. The default decoder uses the @FromField@ instance of the type.
-- See Note [Generic decoding].
class DuckValue a where
-- | Encode a field value.
duckToField :: a -> FieldValue
-- | Decode a field value. Run it with @runConversion@.
duckFromField :: FieldValue -> Conversion a
-- | Give the SQL type used to encode the field.
duckLogicalType :: Proxy a -> LogicalTypeRep
-- | Decode a value with the SQL type of its place, for example the type of a
-- field of a STRUCT or of an element of a LIST. The default runs
-- 'duckFromField' and ignores the supplied type. An instance that reads
-- through 'FromField' can use
-- 'typedFromField', so that 'fieldType' returns the type. See
-- Note [Column types] in "Database.DuckDB.Simple.FromField".
duckFromTypedField :: LogicalTypeRep -> FieldValue -> Conversion a
duckFromTypedField _ = duckFromField
default duckFromField :: (FromField a) => FieldValue -> Conversion a
duckFromField = typedFromField (LogicalTypeScalar LogicalTypeIdVariant)
{- Note [Generic decoding]
~~~~~~~~~~~~~~~~~~~~~~~~~~
Generic decoding uses Conversion because a FromField instance can request SQL
metadata. Encoding and logical type declarations remain pure. Error context is
added only when a conversion's failure is selected. A discarded Alternative
branch does not request metadata for its diagnostic.
-}
-- | Decode a value through 'FromField', with a t'Field' of the given SQL type.
-- See Note [Generic decoding] and Note [Column types] in
-- "Database.DuckDB.Simple.FromField".
typedFromField :: (FromField a) => LogicalTypeRep -> FieldValue -> Conversion a
typedFromField logical fv =
fromField Field{fieldName = Text.empty, fieldIndex = 0, fieldValue = fv, fieldType = pure logical}
instance DuckValue Variant where
duckToField = variantPayload
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdVariant
duckFromTypedField = typedFromField
instance DuckValue Bool where
duckToField = FieldBool
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdBoolean
duckFromTypedField = typedFromField
instance DuckValue Int where
duckToField = FieldInt64 . fromIntegral
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdBigInt
duckFromTypedField = typedFromField
instance DuckValue Int8 where
duckToField = FieldInt8
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTinyInt
duckFromTypedField = typedFromField
instance DuckValue Int16 where
duckToField = FieldInt16
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdSmallInt
duckFromTypedField = typedFromField
instance DuckValue Int32 where
duckToField = FieldInt32
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdInteger
duckFromTypedField = typedFromField
instance DuckValue Int64 where
duckToField = FieldInt64
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdBigInt
duckFromTypedField = typedFromField
-- | A field of a generic record has the type HUGEINT. A value outside that range
-- raises an error. A top-level parameter of this type also binds as HUGEINT
-- when the value is in that range. See Note [Integer parameters] in
-- "Database.DuckDB.Simple.ToField".
instance DuckValue Integer where
duckToField = FieldHugeInt
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdHugeInt
duckFromTypedField = typedFromField
-- | A field of a generic record has the type UHUGEINT. A value outside that range
-- raises an error. A top-level parameter of this type binds as HUGEINT when the
-- value is in the HUGEINT range. See Note [Integer parameters] in
-- "Database.DuckDB.Simple.ToField".
instance DuckValue Natural where
duckToField = FieldUHugeInt . toInteger
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUHugeInt
duckFromTypedField = typedFromField
instance DuckValue Word where
duckToField = FieldWord64 . fromIntegral
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUBigInt
duckFromTypedField = typedFromField
instance DuckValue Word8 where
duckToField = FieldWord8
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUTinyInt
duckFromTypedField = typedFromField
instance DuckValue Word16 where
duckToField = FieldWord16
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUSmallInt
duckFromTypedField = typedFromField
instance DuckValue Word32 where
duckToField = FieldWord32
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUInteger
duckFromTypedField = typedFromField
instance DuckValue Word64 where
duckToField = FieldWord64
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUBigInt
duckFromTypedField = typedFromField
instance DuckValue Float where
duckToField = FieldFloat
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdFloat
duckFromTypedField = typedFromField
instance DuckValue Double where
duckToField = FieldDouble
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdDouble
duckFromTypedField = typedFromField
instance DuckValue Text where
duckToField = FieldText
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdVarchar
duckFromTypedField = typedFromField
instance DuckValue String where
duckToField = FieldText . Text.pack
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdVarchar
duckFromField fv = Text.unpack <$> duckFromField fv
duckFromTypedField logical fv = Text.unpack <$> duckFromTypedField logical fv
instance DuckValue BS.ByteString where
duckToField = FieldBlob
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdBlob
duckFromTypedField = typedFromField
instance DuckValue Day where
duckToField = FieldDate . Finite
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdDate
duckFromTypedField = typedFromField
instance DuckValue TimeOfDay where
duckToField = FieldTime
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTime
duckFromTypedField = typedFromField
instance DuckValue LocalTime where
duckToField = FieldTimestamp . Finite
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimestamp
duckFromTypedField = typedFromField
instance DuckValue UTCTime where
duckToField = FieldTimestampTZ . Finite
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimestampTz
duckFromTypedField = typedFromField
instance DuckValue (Unbounded Day) where
duckToField = FieldDate
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdDate
duckFromTypedField = typedFromField
instance DuckValue (Unbounded LocalTime) where
duckToField = FieldTimestamp
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimestamp
duckFromTypedField = typedFromField
instance DuckValue (Unbounded UTCTime) where
duckToField = FieldTimestampTZ
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimestampTz
duckFromTypedField = typedFromField
instance DuckValue UUID.UUID where
duckToField = FieldUUID
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdUUID
duckFromTypedField = typedFromField
instance DuckValue IntervalValue where
duckToField = FieldInterval
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdInterval
duckFromTypedField = typedFromField
instance DuckValue TimeWithZone where
duckToField = FieldTimeTZ
duckLogicalType _ = LogicalTypeScalar LogicalTypeIdTimeTz
duckFromTypedField = typedFromField
instance (DuckValue a) => DuckValue (Maybe a) where
duckToField (Just x) = duckToField x
duckToField Nothing = FieldNull
duckLogicalType _ = duckLogicalType (Proxy @a)
duckFromField FieldNull = pure Nothing
duckFromField other = Just <$> duckFromField other
duckFromTypedField _ FieldNull = pure Nothing
duckFromTypedField logical other = Just <$> duckFromTypedField logical other
-- | List values encode as DuckDB LIST (variable-length). A field reads a LIST
-- and an ARRAY, as the top-level @FromField@ instance of a list does. 'String'
-- keeps its own instance.
instance {-# OVERLAPPABLE #-} (DuckValue a) => DuckValue [a] where
duckToField xs = FieldList (map duckToField xs)
duckLogicalType _ = LogicalTypeList (duckLogicalType (Proxy @a))
duckFromField = duckFromTypedField (LogicalTypeScalar LogicalTypeIdVariant)
duckFromTypedField logical (FieldList fvs) = traverse (duckFromTypedField (listElementType logical)) fvs
duckFromTypedField logical (FieldArray arr) = traverse (duckFromTypedField (listElementType logical)) (elems arr)
duckFromTypedField logical other = unexpectedTypedValue logical "LIST or ARRAY" other
-- | A 'SizedArray' field is an ARRAY of size @n@. It reads an ARRAY and a LIST of
-- @n@ elements, as the 'FromField' instance does. See Note [Sized arrays] in
-- "Database.DuckDB.Simple.ToField".
instance (KnownNat n, DuckValue a) => DuckValue (SizedArray n a) where
duckToField values = FieldArray (fmap duckToField (sizedArrayToArray values))
-- See Note [Sized ARRAY bounds] in "Database.DuckDB.Simple.Native".
duckLogicalType _ = LogicalTypeArray (duckLogicalType (Proxy @a)) (fromInteger (min (natVal (Proxy @n)) (toInteger (maxBound :: Word64))))
duckFromField = duckFromTypedField (LogicalTypeScalar LogicalTypeIdVariant)
duckFromTypedField logical value = case value of
FieldArray arr -> sized (elems arr)
FieldList entries -> sized entries
other -> unexpectedTypedValue logical "ARRAY" other
where
size = natVal (Proxy @n)
sized entries
| Just reason <- arraySizeReason size = conversionError (sizeError reason)
| otherwise = case sizedArrayFromList entries of
Nothing -> conversionError (sizeError (Text.pack ("the value has " <> show (length entries) <> " elements")))
Just values -> traverse (duckFromTypedField (listElementType logical)) values
sizeError reason =
Incompatible
(fieldTypeName logical value)
Text.empty
(Text.pack ("SizedArray " <> show size))
reason
-- | Map values encode as DuckDB MAP.
instance (Ord k, DuckValue k, DuckValue v) => DuckValue (Map.Map k v) where
duckToField m =
let pairs = Map.toList m
in FieldMap [(duckToField k, duckToField v) | (k, v) <- pairs]
duckLogicalType _ =
LogicalTypeMap
(duckLogicalType (Proxy @k))
(duckLogicalType (Proxy @v))
duckFromField = duckFromTypedField (LogicalTypeScalar LogicalTypeIdVariant)
duckFromTypedField logical (FieldMap pairs) = do
result <- Map.fromList <$> traverse decodePair pairs
if Map.size result == length pairs
then pure result
else decodingError "duplicate MAP key after conversion"
where
(keyType, valueType) = mapEntryTypes logical
decodePair (kfv, vfv) = do
k <- duckFromTypedField keyType kfv
v <- duckFromTypedField valueType vfv
pure (k, v)
duckFromTypedField logical other = unexpectedTypedValue logical "MAP" other
-- | The error of a decoder that does not read a value. The text has the form of
-- each other read error: it names the SQL type of the value, not the value,
-- because a value can be large.
unexpectedValue :: String -> FieldValue -> Conversion a
unexpectedValue expected value = conversionError (Incompatible (valueTypeName value) Text.empty (Text.pack expected) Text.empty)
-- | The error of a decoder that cannot read a value with the given SQL type.
-- It names the type as 'returnError' does.
unexpectedTypedValue :: LogicalTypeRep -> String -> FieldValue -> Conversion a
unexpectedTypedValue logical expected value = conversionError (Incompatible (fieldTypeName logical value) Text.empty (Text.pack expected) Text.empty)
--------------------------------------------------------------------------------
-- Generic machinery
-- | A STRUCT or UNION value with its logical type metadata, produced by the
-- generic traversal for @genericToFieldValue@. @genericLogicalType@ produces
-- the type metadata without a value.
data Encoded
= EncodedStruct (StructValue FieldValue)
| EncodedUnion (UnionValue FieldValue)
encodedValue :: Encoded -> FieldValue
encodedValue = \case
EncodedStruct sv -> FieldStruct sv
EncodedUnion uv -> FieldUnion uv
-- | Convert a Haskell value (using its generic representation) into a DuckDB @FieldValue@.
genericToFieldValue :: forall a. (Generic a, GToField (Rep a)) => a -> FieldValue
genericToFieldValue = encodedValue . gToField . from
-- | Give the logical DuckDB type of a Haskell type.
genericLogicalType :: forall a. (Generic a, GToField (Rep a)) => Proxy a -> LogicalTypeRep
genericLogicalType _ = gLogicalType (Proxy @(Rep a ()))
-- | Decode a DuckDB @FieldValue@ with its generic representation. Run the
-- result with @runConversion@. See Note [Generic decoding].
genericFromFieldValue :: forall a. (Generic a, GFromField (Rep a)) => FieldValue -> Conversion a
genericFromFieldValue fv = to <$> gFromField fv
-- | Extract the STRUCT encoding when the value produces one.
genericToStructValue :: forall a. (Generic a, GToField (Rep a)) => a -> Maybe (StructValue FieldValue)
genericToStructValue value =
case gToField (from value) of
EncodedStruct sv -> Just sv
_ -> Nothing
-- | Extract a UNION-shaped generic encoding directly when one is produced.
genericToUnionValue :: forall a. (Generic a, GToField (Rep a)) => a -> Maybe (UnionValue FieldValue)
genericToUnionValue value =
case gToField (from value) of
EncodedUnion uv -> Just uv
_ -> Nothing
-- | Wrapper for deriving-via so that @instance ToField (ViaDuckDB a)@ picks up
-- the generic encoding provided by this module.
newtype ViaDuckDB a = ViaDuckDB {getViaDuckDB :: a}
-- Type family to decide whether a representation is a sum.
-- | Select sum encoding with @'True@ and product encoding with @'False@.
type family IsSum f :: Bool where
IsSum (f :+: g) = 'True
IsSum (M1 D _ f) = IsSum f
IsSum (M1 C _ f) = IsSum f
IsSum _ = 'False
-- | Generic encoding to the intermediate @Encoded@ representation. Every
-- instance must also supply the corresponding logical type description.
class GToField f where
gToField :: f p -> Encoded
gLogicalType :: Proxy (f p) -> LogicalTypeRep
instance (GToField' (IsSum f) f) => GToField f where
gToField = gToField' (Proxy @(IsSum f))
gLogicalType _ = gLogicalType' (Proxy @(IsSum f)) (Proxy @f)
-- | Select product (@'False@) or sum (@'True@) encoding with the @IsSum@ type
-- family.
class GToField' (isSum :: Bool) f where
gToField' :: Proxy isSum -> f p -> Encoded
gLogicalType' :: Proxy isSum -> Proxy f -> LogicalTypeRep
-- Products (single constructor records)
{- Note [Types without fields]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A product type with no fields encodes as the STRUCT without fields. The payload
of a constructor with no fields in a sum type is also the STRUCT without fields,
and the type of its UNION member is the STRUCT type without fields. DuckDB shows
this value as {}. The value is not NULL.
- Why not NULL. NULL is the encoding of Nothing in a field of the type Maybe a.
If a value without fields encodes as NULL, then Just x and Nothing are the
same value in a field.
- The decoders also accept NULL for a product type with no fields and for the
payload of a constructor with no fields. NULL decodes as the value with
no fields.
-}
-- | Product encoding: single-constructor datatypes become STRUCT values. See
-- Note [Types without fields].
instance (GStruct f) => GToField' 'False (M1 D meta (M1 C c f)) where
gToField' _ (M1 (M1 inner)) =
let comps = gStructValues inner
typeComps = gStructTypes (Proxy @(f _))
names = resolveNames (zip progIndices (map fcName comps))
valueArray = listArrayFrom names (map fcValue comps)
typeArray = listArrayFrom names (map fcValue typeComps)
indexMap = Map.fromList (zip names [0 ..])
in EncodedStruct
StructValue
{ structValueFields = valueArray
, structValueTypes = typeArray
, structValueIndex = indexMap
}
where
progIndices = [0 :: Int ..]
gLogicalType' _ _ =
let typeComps = gStructTypes (Proxy @(f _))
names = resolveNames (zip [0 :: Int ..] (map fcName typeComps))
typeArray = listArrayFrom names (map fcValue typeComps)
in LogicalTypeStruct typeArray
-- Sums (encode as union)
-- | Sum encoding: multi-constructor datatypes become UNION values.
instance (GSum f) => GToField' 'True (M1 D meta f) where
gToField' _ (M1 value) =
let members = gSumMembers (Proxy @(f _))
membersArray = listArray (0, length members - 1) members
(idx, payload) = gSumEncode value
label = unionMemberName (members !! idx)
in EncodedUnion
UnionValue
{ unionValueIndex = fromIntegral idx
, unionValueLabel = label
, unionValuePayload = payload
, unionValueMembers = membersArray
}
gLogicalType' _ _ =
let members = gSumMembers (Proxy @(f _))
membersArray = listArray (0, length members - 1) members
in LogicalTypeUnion membersArray
--------------------------------------------------------------------------------
-- GStruct: products
data FieldComponent a = FieldComponent
{ fcName :: Maybe Text
, fcValue :: a
}
-- | Keep the selector names from GHC.Generics. Use @fieldN@ for positional
-- products.
resolveNames :: [(Int, Maybe Text)] -> [Text]
resolveNames =
map pick
where
pick (_, Just n) = n
pick (idx, Nothing) = Text.pack ("field" <> show (idx + 1))
-- | Helper that builds an @Array@ of struct fields from parallel lists of names
-- and payloads.
listArrayFrom :: [Text] -> [b] -> Array Int (StructField b)
listArrayFrom names values =
listArray
(0, length values - 1)
(zipWith (\n v -> StructField{structFieldName = n, structFieldValue = v}) names values)
-- | Collect the values and types of a product in parallel lists for encoding
-- and decoding.
class GStruct f where
gStructValues :: f p -> [FieldComponent FieldValue]
gStructTypes :: Proxy (f p) -> [FieldComponent LogicalTypeRep]
instance GStruct U1 where
gStructValues _ = []
gStructTypes _ = []
instance (GStruct a, GStruct b) => GStruct (a :*: b) where
gStructValues (a :*: b) = gStructValues a ++ gStructValues b
gStructTypes _ = gStructTypes (Proxy @(a _)) ++ gStructTypes (Proxy @(b _))
instance (Selector s, DuckValue a) => GStruct (M1 S s (K1 i a)) where
gStructValues m@(M1 (K1 x)) =
let name = toMaybe (selName m)
in [FieldComponent name (duckToField x)]
gStructTypes _ =
let raw = selName (undefined :: M1 S s (K1 i a) ())
name = toMaybe raw
in [FieldComponent name (duckLogicalType (Proxy @a))]
instance (GStruct f) => GStruct (M1 C c f) where
gStructValues (M1 x) = gStructValues x
gStructTypes _ = gStructTypes (Proxy @(f _))
toMaybe :: String -> Maybe Text
toMaybe name
| null name = Nothing
| otherwise = Just (Text.pack name)
--------------------------------------------------------------------------------
-- Sums (unions)
-- | Describe the members of a sum type (@gSumMembers@). Encode a value as its
-- tag and payload (@gSumEncode@), or decode them (@gSumDecode@).
class GSum f where
gSumMembers :: Proxy (f p) -> [UnionMemberType]
gSumEncode :: f p -> (Int, FieldValue)
gSumDecode :: Int -> FieldValue -> Conversion (f p)
instance (GSum a, GSum b) => GSum (a :+: b) where
gSumMembers _ = gSumMembers (Proxy @(a _)) ++ gSumMembers (Proxy @(b _))
gSumEncode (L1 x) = gSumEncode x
gSumEncode (R1 x) =
let leftCount = length (gSumMembers (Proxy @(a _)))
(idx, payload) = gSumEncode x
in (idx + leftCount, payload)
gSumDecode idx payload =
let leftCount = length (gSumMembers (Proxy @(a _)))
in if idx < leftCount
then L1 <$> gSumDecode idx payload
else R1 <$> gSumDecode (idx - leftCount) payload
instance (Constructor c, GStruct f, GStructDecode f) => GSum (M1 C c f) where
gSumMembers _ =
[ UnionMemberType
{ unionMemberName = Text.pack (conName (undefined :: M1 C c f p))
, unionMemberType =
let typeComps = gStructTypes (Proxy @(f _))
names = resolveNames (zip [0 :: Int ..] (map fcName typeComps))
in LogicalTypeStruct (listArrayFrom names (map fcValue typeComps))
}
]
-- See Note [Types without fields].
gSumEncode (M1 x) =
let comps = gStructValues x
typeComps = gStructTypes (Proxy @(f _))
names = resolveNames (zip [0 :: Int ..] (map fcName comps))
valueArray = listArrayFrom names (map fcValue comps)
typeArray = listArrayFrom names (map fcValue typeComps)
indexMap = Map.fromList (zip names [0 ..])
in (0, FieldStruct StructValue{structValueFields = valueArray, structValueTypes = typeArray, structValueIndex = indexMap})
gSumDecode idx payload
| idx /= 0 = decodingError ("duckdb-simple: union tag mismatch (expected 0, got " <> show idx <> ")")
| otherwise =
case payload of
-- NULL also decodes as a value with no fields. See Note [Types without fields].
FieldNull -> M1 . fst <$> gStructDecodeList (Proxy @(f _)) []
FieldStruct structVal -> do
ordered <- either decodingError pure (orderStructFields (gStructTypes (Proxy @(f _))) structVal)
M1 <$> gStructDecodeStruct (Proxy @(f _)) ordered
other -> unexpectedValue "STRUCT for a member of a sum type" other
-- | Match decoded fields to their selector names before product decoding.
orderStructFields :: [FieldComponent LogicalTypeRep] -> StructValue FieldValue -> Either String (StructValue FieldValue)
orderStructFields components sv
-- The fields have the order of the selectors, so the names are unique.
| map structFieldName fields == names = Right sv
| otherwise = reorder
where
names = resolveNames (zip [0 ..] (map fcName components))
fields = elems (structValueFields sv)
reorder = do
let byName = Map.fromList [(structFieldName field, field) | field <- fields]
unless (length fields <= length names) $
Left "duckdb-simple: extra fields when decoding struct"
unless (length fields == length names && Map.size byName == length names) $
Left "duckdb-simple: struct field names or count mismatch"
ordered <-
traverse (\name -> maybe (Left ("duckdb-simple: missing struct field " <> Text.unpack name)) Right (Map.lookup name byName)) names
-- The types keep the order of the fields. See Note [Column types] in
-- "Database.DuckDB.Simple.FromField".
let typeByName = Map.fromList [(structFieldName field, field) | field <- elems (structValueTypes sv)]
variant name = StructField name (LogicalTypeScalar LogicalTypeIdVariant)
orderedTypes = [fromMaybe (variant name) (Map.lookup name typeByName) | name <- names]
pure
sv{structValueFields = listArray (0, length ordered - 1) ordered, structValueTypes = listArray (0, length orderedTypes - 1) orderedTypes}
--------------------------------------------------------------------------------
-- GStructDecode: inverse of GStruct for decoding
-- | Inverse of @GStruct@: decode struct payloads back into a generic product.
class GStructDecode f where
gStructDecodeStruct :: Proxy (f p) -> StructValue FieldValue -> Conversion (f p)
-- | Consume a prefix of fields from left to right while decoding, returning
-- the reconstructed value and any remaining fields. Each field has its
-- type and its value.
gStructDecodeList :: Proxy (f p) -> [(LogicalTypeRep, FieldValue)] -> Conversion (f p, [(LogicalTypeRep, FieldValue)])
instance GStructDecode U1 where
gStructDecodeStruct _ structVal =
if null (elems (structValueFields structVal))
then pure U1
else decodingError ("duckdb-simple: expected empty struct, but got " <> show (length (elems (structValueFields structVal))) <> " field(s)")
gStructDecodeList _ xs = pure (U1, xs)
instance (GStructDecode a, GStructDecode b) => GStructDecode (a :*: b) where
gStructDecodeStruct proxy structVal = do
(decoded, rest) <- gStructDecodeList proxy (typedFields structVal)
unless (null rest) $
decodingError ("duckdb-simple: extra " <> show (length rest) <> " field(s) when decoding struct (too many fields provided)")
pure decoded
gStructDecodeList _ xs = do
(leftVal, rest) <- gStructDecodeList (Proxy @(a _)) xs
(rightVal, rest') <- gStructDecodeList (Proxy @(b _)) rest
pure (leftVal :*: rightVal, rest')
instance (Selector s, DuckValue a) => GStructDecode (M1 S s (K1 i a)) where
gStructDecodeStruct _ structVal =
case typedFields structVal of
[(logical, fv)] -> M1 . K1 <$> namedField (selName (undefined :: M1 S s (K1 i a) ())) (duckFromTypedField logical fv)
[] -> decodingError "duckdb-simple: missing struct field (expected 1, got 0)"
xs -> decodingError ("duckdb-simple: expected single field struct, but got " <> show (length xs) <> " fields")
gStructDecodeList _ [] = decodingError "duckdb-simple: missing struct field (expected field but list is empty)"
gStructDecodeList _ ((logical, fv) : rest) = do
val <- namedField (selName (undefined :: M1 S s (K1 i a) ())) (duckFromTypedField logical fv)
pure (M1 (K1 val), rest)
-- | The type and the value of each field of a STRUCT value, in order. A field
-- with no type in the value has the type VARIANT. See Note [Column types] in
-- "Database.DuckDB.Simple.FromField".
typedFields :: StructValue FieldValue -> [(LogicalTypeRep, FieldValue)]
typedFields StructValue{structValueFields, structValueTypes} =
zip
(map structFieldValue (elems structValueTypes) <> repeat (LogicalTypeScalar LogicalTypeIdVariant))
(map structFieldValue (elems structValueFields))
-- | Name the record field in the error of its decoder, after the prefix of the
-- library. A positional field has no name. See Note [Generic decoding].
namedField :: String -> Conversion a -> Conversion a
namedField name
| null name = id
| otherwise = mapConversionErrors \errors ->
[ toException
( ConversionFailed
Text.empty
Text.empty
Text.empty
(Text.pack ("duckdb-simple: field " <> name <> ": " <> withoutPrefix (intercalate "; " (map exceptionText errors))))
)
]
where
withoutPrefix message = fromMaybe message (stripPrefix "duckdb-simple: " message)
-- | Fail a generic decoder with the supplied diagnostic text.
decodingError :: String -> Conversion a
decodingError = conversionError . ConversionFailed Text.empty Text.empty Text.empty . Text.pack
instance (GStructDecode f) => GStructDecode (M1 C c f) where
gStructDecodeStruct _ structVal = M1 <$> gStructDecodeStruct (Proxy @(f _)) structVal
gStructDecodeList _ values = do
(inner, rest) <- gStructDecodeList (Proxy @(f _)) values
pure (M1 inner, rest)
--------------------------------------------------------------------------------
-- GFromField (inverse generic)
-- | Generic decoding entry point mirroring @GToField@. This is used both by
-- @genericFromFieldValue@ and the @ViaDuckDB@ deriving helper.
class GFromField f where
gFromField :: FieldValue -> Conversion (f p)
instance (GFromField' (IsSum f) f) => GFromField f where
gFromField = gFromField' (Proxy @(IsSum f))
class GFromField' (isSum :: Bool) f where
gFromField' :: Proxy isSum -> FieldValue -> Conversion (f p)
instance (GStruct f, GStructDecode f) => GFromField' 'False (M1 D meta (M1 C c f)) where
gFromField' _ = \case
-- NULL also decodes as a value with no fields. See Note [Types without fields].
FieldNull -> M1 . M1 . fst <$> gStructDecodeList (Proxy @(f _)) []
FieldStruct sv -> do
ordered <- either decodingError pure (orderStructFields (gStructTypes (Proxy @(f _))) sv)
M1 . M1 <$> gStructDecodeStruct (Proxy @(f _)) ordered
other -> unexpectedValue "STRUCT for a product type" other
instance (GSum f) => GFromField' 'True (M1 D meta f) where
gFromField' _ = \case
FieldUnion uv -> do
let actualMembers = elems (unionValueMembers uv)
actualIndex = fromIntegral (unionValueIndex uv)
unless (actualIndex < length actualMembers) $
decodingError "duckdb-simple: union tag out of range"
unless (unionMemberName (actualMembers !! actualIndex) == unionValueLabel uv) $
decodingError "duckdb-simple: union tag and member name mismatch"
let members = gSumMembers (Proxy @(f _))
indexed = zip [0 ..] members
matching = [idx | (idx, member) <- indexed, unionMemberName member == unionValueLabel uv]
case matching of
[idx] -> M1 <$> gSumDecode idx (unionValuePayload uv)
_ -> decodingError "duckdb-simple: unknown union member name"
other -> unexpectedValue "UNION for a sum type" other
instance GFromField' 'False (M1 D meta U1) where
gFromField' _ _ = pure (M1 U1)
--------------------------------------------------------------------------------
-- ViaDuckDB instances
-- | The deriving-via version of @DuckDBColumnType@. The text is the bare name
-- of the generic logical type, for diagnostics. The declaration is the
-- structured generic logical type. Each field type comes from 'DuckValue'.
-- See Note [Type declarations] in "Database.DuckDB.Simple.ToField".
-- See Note [Sized ARRAY bounds] in
-- <src/Database.DuckDB.Simple.Native.html Database.DuckDB.Simple.Native>.
instance (Generic a, GToField (Rep a)) => DuckDBColumnType (ViaDuckDB a) where
duckdbTypeDeclaration _
| containsType invalidArray logical =
Left (Text.pack ("a generic field has no ARRAY type, because a DuckDB ARRAY must have 1 to " <> show maxArraySize <> " elements"))
| otherwise = Right (StructuredType logical)
where
logical = genericLogicalType (Proxy @a)
invalidArray (LogicalTypeArray _ size) = isJust (arraySizeReason (toInteger size))
invalidArray _ = False
duckdbColumnTypeFor _ =
case genericLogicalType (Proxy @a) of
LogicalTypeStruct{} -> Text.pack "STRUCT"
LogicalTypeTuple{} -> Text.pack "TUPLE"
LogicalTypeUnion{} -> Text.pack "UNION"
LogicalTypeList{} -> Text.pack "LIST"
LogicalTypeArray{} -> Text.pack "ARRAY"
LogicalTypeMap{} -> Text.pack "MAP"
LogicalTypeScalar dtype -> duckDBTypeToName dtype
LogicalTypeDecimal{} -> Text.pack "DECIMAL"
LogicalTypeEnum{} -> Text.pack "ENUM"
LogicalTypeGeometry{} -> Text.pack "GEOMETRY"
LogicalTypeCollatedVarchar{} -> Text.pack "VARCHAR"
LogicalTypeAlias name _ -> name
-- | Deriving-via @ToField@ instance. A sum type binds as a UNION and a product
-- type as a STRUCT, through the @ToField@ instances of those values. A product
-- type with no fields binds as a STRUCT without fields. See
-- Note [Types without fields].
instance (Generic a, GToField (Rep a)) => ToField (ViaDuckDB a) where
toField (ViaDuckDB x) = case gToField (from x) of
EncodedUnion unionVal -> toField unionVal
EncodedStruct structVal -> toField structVal
-- | Deriving-via @ToDuckValue@ instance. A sum type gives a UNION value and a
-- product type a STRUCT value, through the @ToDuckValue@ instances of those
-- values. See Note [Types without fields].
instance (Generic a, GToField (Rep a)) => ToDuckValue (ViaDuckDB a) where
toDuckValue factory (ViaDuckDB x) = case gToField (from x) of
EncodedUnion unionVal -> toDuckValue factory unionVal
EncodedStruct structVal -> toDuckValue factory structVal
-- | Deriving-via @FromField@ instance. It reads a STRUCT for a product type and
-- a UNION for a sum type. Convert decoder errors to @ResultError@ with
-- @returnError@. See Note [Generic decoding].
instance (Generic a, GFromField (Rep a), Typeable a) => FromField (ViaDuckDB a) where
fromField f@Field{fieldValue} =
mapConversionErrorsWith
(\errors -> [] <$ returnError @(ViaDuckDB a) ConversionFailed f (Text.pack (intercalate "; " (map exceptionText errors))))
(ViaDuckDB <$> genericFromFieldValue fieldValue)