Data.Avro

Avro encoding and decoding routines.

This library provides a high level interface for encoding (and decoding) Haskell values in Apache's Avro serialization format. The goal is to match Aeson's API whenever reasonable, meaning user experience with one effectively translate to the other.

Avro RPC is not currently supported.

• *Library Structure**

The library structure includes: * This module, Avro, providing a high-level interface via classes of FromAvro and ToAvro for decoding and encoding values. * Type define the types of Avro data, providing a common (intermediate) representation for any data that is encoded or decoded by Data.Avro. * Encode and Decode: More efficient conversion capable of avoiding the intermediate representation. Also, the implementation of the en/decoding of the intermediate representation. * Deconflict: translate decoded data from an encoder schema to the (potentially different) decoder's schema. * Schema: Defines the type for Avro schema's and its JSON encoding/decoding.

Example decoding:

Let's say you have an ADT and related schema:

{--}
import qualified Data.Avro.Types as Ty
import Data.Avro.Schema
import Data.Avro
import           Data.List.NonEmpty (NonEmpty(..))

data MyEnum = A | B | C | D deriving (Eq,Ord,Show,Enum,Generic)
data MyStruct = MyStruct (Either MyEnum String) Int

meSchema :: Schema
meSchema = Schema $ mkEnum MyEnum [] Nothing Nothing [A,B,C,D]

msSchema  :: Schema
msSchema =
  Struct MyStruct Nothing [] Nothing Nothing
      [ fld "enumOrString" eOrS (Just $ String "The Default")
      , fld "int" Int (Just (Ty.Int 1))
      ]
     where
     fld nm ty def = Field nm [] Nothing Nothing ty def
     eOrS = mkUnion (meSchema :| [String])

instance ToAvro MyEnum where
    toAvro = toAvroEnum
instance ToAvro MyStruct where
    toAvro (MyStruct ab i) =
     record [ "enumOrString" .= ab
            , "int"          .= i
            ]

main = do
  let val = MyStruct (Right Hello) 1
  print (fromAvro (toAvro val) == Success val)

Documentation

class FromAvro a where

Minimal complete definition

fromAvro

Methods

fromAvro :: Value Type -> Result a

Instances

FromAvro Bool

Methods

fromAvro :: Value Type -> Result Bool

FromAvro Double

Methods

fromAvro :: Value Type -> Result Double

FromAvro Int

Methods

fromAvro :: Value Type -> Result Int

FromAvro Int32

Methods

fromAvro :: Value Type -> Result Int32

FromAvro Int64

Methods

fromAvro :: Value Type -> Result Int64

FromAvro ByteString

Methods

fromAvro :: Value Type -> Result ByteString

FromAvro ByteString

Methods

fromAvro :: Value Type -> Result ByteString

FromAvro Text

Methods

fromAvro :: Value Type -> Result Text

FromAvro Text

Methods

fromAvro :: Value Type -> Result Text

FromAvro a => FromAvro [a]

Methods

fromAvro :: Value Type -> Result [a]

FromAvro a => FromAvro (Maybe a)

Methods

fromAvro :: Value Type -> Result (Maybe a)

FromAvro (Value Type)

Methods

fromAvro :: Value Type -> Result (Value Type)

(ToAvro a, ToAvro b, FromAvro a, FromAvro b) => FromAvro (Either a b)

Methods

fromAvro :: Value Type -> Result (Either a b)

FromAvro a => FromAvro (HashMap Text a)

Methods

fromAvro :: Value Type -> Result (HashMap Text a)

FromAvro a => FromAvro (Map Text a)

Methods

fromAvro :: Value Type -> Result (Map Text a)

class ToAvro a where

Minimal complete definition

toAvro, schema

Methods

toAvro :: a -> Value Type

schema :: Tagged a Type

Instances

ToAvro Bool

Methods

toAvro :: Bool -> Value Type

schema :: Tagged * Bool Type

ToAvro Double

Methods

toAvro :: Double -> Value Type

schema :: Tagged * Double Type

ToAvro Int

Methods

toAvro :: Int -> Value Type

schema :: Tagged * Int Type

ToAvro Int32

Methods

toAvro :: Int32 -> Value Type

schema :: Tagged * Int32 Type

ToAvro Int64

Methods

toAvro :: Int64 -> Value Type

schema :: Tagged * Int64 Type

ToAvro ()

Methods

toAvro :: () -> Value Type

schema :: Tagged * () Type

ToAvro ByteString

Methods

toAvro :: ByteString -> Value Type

schema :: Tagged * ByteString Type

ToAvro ByteString

Methods

toAvro :: ByteString -> Value Type

schema :: Tagged * ByteString Type

ToAvro Text

Methods

toAvro :: Text -> Value Type

schema :: Tagged * Text Type

ToAvro Text

Methods

toAvro :: Text -> Value Type

schema :: Tagged * Text Type

ToAvro a => ToAvro [a]

Methods

toAvro :: [a] -> Value Type

schema :: Tagged * [a] Type

ToAvro a => ToAvro (Maybe a)

Methods

toAvro :: Maybe a -> Value Type

schema :: Tagged * (Maybe a) Type

(ToAvro a, ToAvro b) => ToAvro (Either a b)

Methods

toAvro :: Either a b -> Value Type

schema :: Tagged * (Either a b) Type

ToAvro a => ToAvro (HashMap String a)

Methods

toAvro :: HashMap String a -> Value Type

schema :: Tagged * (HashMap String a) Type

ToAvro a => ToAvro (HashMap Text a)

Methods

toAvro :: HashMap Text a -> Value Type

schema :: Tagged * (HashMap Text a) Type

ToAvro a => ToAvro (HashMap Text a)

Methods

toAvro :: HashMap Text a -> Value Type

schema :: Tagged * (HashMap Text a) Type

ToAvro a => ToAvro (Map String a)

Methods

toAvro :: Map String a -> Value Type

schema :: Tagged * (Map String a) Type

ToAvro a => ToAvro (Map Text a)

Methods

toAvro :: Map Text a -> Value Type

schema :: Tagged * (Map Text a) Type

ToAvro a => ToAvro (Map Text a)

Methods

toAvro :: Map Text a -> Value Type

schema :: Tagged * (Map Text a) Type

type Avro a = (FromAvro a, ToAvro a)

(.:) :: FromAvro a => HashMap Text (Value Type) -> Text -> Result a

(.=) :: ToAvro a => Text -> a -> (Text, Value Type)

record :: Foldable f => Type -> f (Text, Value Type) -> Value Type

data Result a

Constructors

Success a

Error String

Instances

Monad Result

Methods

(>>=) :: Result a -> (a -> Result b) -> Result b

(>>) :: Result a -> Result b -> Result b

return :: a -> Result a

fail :: String -> Result a

Functor Result

Methods

fmap :: (a -> b) -> Result a -> Result b

(<$) :: a -> Result b -> Result a

MonadFail Result

Methods

fail :: String -> Result a

Applicative Result

Methods

pure :: a -> Result a

(<*>) :: Result (a -> b) -> Result a -> Result b

(*>) :: Result a -> Result b -> Result b

(<*) :: Result a -> Result b -> Result a

Foldable Result

Methods

fold :: Monoid m => Result m -> m

foldMap :: Monoid m => (a -> m) -> Result a -> m

foldr :: (a -> b -> b) -> b -> Result a -> b

foldr' :: (a -> b -> b) -> b -> Result a -> b

foldl :: (b -> a -> b) -> b -> Result a -> b

foldl' :: (b -> a -> b) -> b -> Result a -> b

foldr1 :: (a -> a -> a) -> Result a -> a

foldl1 :: (a -> a -> a) -> Result a -> a

toList :: Result a -> [a]

null :: Result a -> Bool

length :: Result a -> Int

elem :: Eq a => a -> Result a -> Bool

maximum :: Ord a => Result a -> a

minimum :: Ord a => Result a -> a

sum :: Num a => Result a -> a

product :: Num a => Result a -> a

Traversable Result

Methods

traverse :: Applicative f => (a -> f b) -> Result a -> f (Result b)

sequenceA :: Applicative f => Result (f a) -> f (Result a)

mapM :: Monad m => (a -> m b) -> Result a -> m (Result b)

sequence :: Monad m => Result (m a) -> m (Result a)

Alternative Result

Methods

empty :: Result a

(<|>) :: Result a -> Result a -> Result a

some :: Result a -> Result [a]

many :: Result a -> Result [a]

MonadPlus Result

Methods

mzero :: Result a

mplus :: Result a -> Result a -> Result a

MonadError String Result

Methods

throwError :: String -> Result a

catchError :: Result a -> (String -> Result a) -> Result a

Eq a => Eq (Result a)

Methods

(==) :: Result a -> Result a -> Bool

(/=) :: Result a -> Result a -> Bool

Ord a => Ord (Result a)

Methods

compare :: Result a -> Result a -> Ordering

(<) :: Result a -> Result a -> Bool

(<=) :: Result a -> Result a -> Bool

(>) :: Result a -> Result a -> Bool

(>=) :: Result a -> Result a -> Bool

max :: Result a -> Result a -> Result a

min :: Result a -> Result a -> Result a

Show a => Show (Result a)

Methods

showsPrec :: Int -> Result a -> ShowS

show :: Result a -> String

showList :: [Result a] -> ShowS

Monoid (Result a)

Methods

mempty :: Result a

mappend :: Result a -> Result a -> Result a

mconcat :: [Result a] -> Result a

badValue :: Value Type -> String -> Result a

decode :: FromAvro a => Schema -> ByteString -> Result a

Decode a lazy bytestring using a given Schema.

decodeContainer :: FromAvro a => Schema -> ByteString -> [[a]]

Decode a container and de-conflict the writer schema with a given reader-schema. Exceptions are thrown instead of a Result type to allow this function to be read lazy (to be done in some later version).

decodeContainerBytes :: ByteString -> [[ByteString]]

Like decodeContainer but returns the avro-encoded bytes for each object in the container instead of the Haskell type.

This is particularly useful when slicing up containers into one or more smaller files. By extracting the original bytestring it is possible to avoid re-encoding data.

encode :: ToAvro a => a -> ByteString

encodeContainer :: ToAvro a => [[a]] -> IO ByteString

encodeContainerWithSync :: ToAvro a => (Word64, Word64, Word64, Word64) -> [[a]] -> ByteString

schemaOf :: ToAvro a => a -> Type