simple-avro

Clojure wrapper for Avro schema and serialization.

Quick Start

Schema definition

(defavro-enum State
  "AL" "AK" "AS" "AZ" "AR" "CA" "CO" ; ...
  )

(defavro-record Address
  :street  avro-string
  :city    avro-string
  :state   State
  :zip     avro-int
  :country avro-string)

(defavro-record Contact
  :first   avro-string
  :last    avro-string
  :address Address
  :email   avro-string
  :phone   (avro-union avro-string avro-null))

simple-avro implements all types defined in Avro schema specification. Just prepend avro- to the type name or use plain string names. defavro- macros defined for all named types (defavro-record, defavro-enum and defavro-fixed) create var objects convenient for hierarchical schema compositions. Parameters namespace, aliases and doc can by provided in an optional argument map. In recursive type definitions use string names for type references, for example:

(defavro-record IntList
  :value avro-int 
  :next  (avro-union "IntList" avro-null))

Data serialization

(def contact {:first "Mike" :last ...})
(def packed (pack Contact contact <optional encoder>))
(assert (= contact (unpack Contact packed <optional decoder>)))

pack serializes objects into generic Avro objects. For json or binary serialization provide an optional json-encoder or binary-encoder. Use equivalent decoder to de-serialize objects using unpack. unpack takes an optional list of fields to deserialize from a record. Use singe filed names or path vectors for nested records, for example [:first [:address :city]] will deserialize only the two fields first and city. If no fields provided, the entire record is deserialized.

Custom types API

simple-avro.core supports only basic Avro types. For custom types import simple-avro.api instead of core. To add support for a new custom type first add a schema best matching the type. For example a Date object can be represented as:

(defavro-type avro-date
  :time avro-long)

Second, register mapping functions from the custom object to Avro record and back using pack-avro-instance and unpack-avro-instance:

(pack-avro-instance Date
  (fn [date] 
    (avro-instance avro-date "time" (.getTime date))))
  
(unpack-avro-instance avro-date
  (fn [rec]
    (Date. (rec "time"))))

Now you can use default pack/unpack methods to serialize Date objects:

(unpack avro-date (pack avro-date (Date.)))

simple-avro.api adds serialization support for Date, UUID and an avro-maybe helper for optional values. For more details see examples and unit tests.

Installation

Leiningen

[simple-avro/simple-avro "0.0.5"]

Maven

<dependency>
  <groupId>simple-avro</groupId>
  <artifactId>simple-avro</artifactId>
  <version>0.0.5</version>
</dependency>

Found a bug? Have a question? Drop me an email at adam.smyczek _at_ gmail.com.

asmyczek/simple-avro