github.com/hamba/avro@v1.8.0/README.md (about)

     1  ![Logo](http://svg.wiersma.co.za/hamba/project?title=avro&tag=A%20fast%20Go%20avro%20codec)
     2  
     3  [![Go Report Card](https://goreportcard.com/badge/github.com/hamba/avro)](https://goreportcard.com/report/github.com/hamba/avro)
     4  [![Build Status](https://github.com/hamba/avro/actions/workflows/test.yml/badge.svg)](https://github.com/hamba/avro/actions)
     5  [![Coverage Status](https://coveralls.io/repos/github/hamba/avro/badge.svg?branch=master)](https://coveralls.io/github/hamba/avro?branch=master)
     6  [![GoDoc](https://godoc.org/github.com/hamba/avro?status.svg)](https://godoc.org/github.com/hamba/avro)
     7  [![GitHub release](https://img.shields.io/github/release/hamba/avro.svg)](https://github.com/hamba/avro/releases)
     8  [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/hamba/avro/master/LICENSE)
     9  
    10  A fast Go avro codec
    11  
    12  ## Overview
    13  
    14  Install with:
    15  
    16  ```shell
    17  go get github.com/hamba/avro
    18  ```
    19  
    20  ## Usage
    21  
    22  ```go
    23  type SimpleRecord struct {
    24  	A int64  `avro:"a"`
    25  	B string `avro:"b"`
    26  }
    27  
    28  schema, err := avro.Parse(`{
    29      "type": "record",
    30      "name": "simple",
    31      "namespace": "org.hamba.avro",
    32      "fields" : [
    33          {"name": "a", "type": "long"},
    34          {"name": "b", "type": "string"}
    35      ]
    36  }`)
    37  if err != nil {
    38  	log.Fatal(err)
    39  }
    40  
    41  in := SimpleRecord{A: 27, B: "foo"}
    42  
    43  data, err := avro.Marshal(schema, in)
    44  if err != nil {
    45  	log.Fatal(err)
    46  }
    47  
    48  fmt.Println(data)
    49  // Outputs: [54 6 102 111 111]
    50  
    51  out := SimpleRecord{}
    52  err = avro.Unmarshal(schema, data, &out)
    53  if err != nil {
    54  	log.Fatal(err)
    55  }
    56  
    57  fmt.Println(out)
    58  // Outputs: {27 foo}
    59  ```
    60  
    61  More examples in the [godoc](https://godoc.org/github.com/hamba/avro).
    62  
    63  #### Types Conversions
    64  
    65  | Avro                    | Go Struct                          | Go Interface              |
    66  | ----------------------- | ---------------------------------- | ------------------------- |
    67  | `null`                  | `nil`                              | `nil`                     |
    68  | `boolean`               | `bool`                             | `bool`                    |
    69  | `bytes`                 | `[]byte`                           | `[]byte`                  |
    70  | `float`                 | `float32`                          | `float32`                 |
    71  | `double`                | `float64`                          | `float64`                 |
    72  | `long`                  | `int64`                            | `int64`                   |
    73  | `int`                   | `int`, `int32`, `int16`, `int8`    | `int`                     |
    74  | `string`                | `string`                           | `string`                  |
    75  | `array`                 | `[]T`                              | `[]interface{}`           |
    76  | `enum`                  | `string`                           | `string`                  |
    77  | `fixed`                 | `[n]byte`                          | `[]byte`                  |
    78  | `map`                   | `map[string]T{}`                   | `map[string]interface{}`  |
    79  | `record`                | `struct`                           | `map[string]interface{}`  |
    80  | `union`                 | *see below*                        | *see below*               |
    81  | `int.date`              | `time.Time`                        | `time.Time`               |
    82  | `int.time-millis`       | `time.Duration`                    | `time.Duration`           |
    83  | `long.time-micros`      | `time.Duration`                    | `time.Duration`           |
    84  | `long.timestamp-millis` | `time.Time`                        | `time.Time`               |
    85  | `long.timestamp-micros` | `time.Time`                        | `time.Time`               |
    86  | `bytes.decimal`         | `*big.Rat`                         | `*big.Rat`                |
    87  | `fixed.decimal`         | `*big.Rat`                         | `*big.Rat`                |
    88  
    89  ##### Unions
    90  
    91  The following union types are accepted: `map[string]interface{}`, `*T` and `interface{}`.
    92  
    93  * **map[string]interface{}:** If the union value is `nil`, a `nil` map will be en/decoded. 
    94  When a non-`nil` union value is encountered, a single key is en/decoded. The key is the avro
    95  type name, or scheam full name in the case of a named schema (enum, fixed or record).
    96  * ***T:** This is allowed in a "nullable" union. A nullable union is defined as a two schema union, 
    97  with one of the types being `null` (ie. `["null", "string"]` or `["string", "null"]`), in this case 
    98  a `*T` is allowed, with `T` matching the conversion table above.
    99  * **interface{}:** An `interface` can be provided and the type or name resolved. Primitive types
   100  are pre-registered, but named types, maps and slices will need to be registered with the `Register` function. In the 
   101  case of arrays and maps the enclosed schema type or name is postfix to the type
   102  with a `:` separator, e.g `"map:string"`. If any type cannot be resolved the map type above is used unless
   103  `Config.UnionResolutionError` is set to `true` in which case an error is returned.
   104  
   105  ##### TextMarshaler and TextUnmarshaler
   106  
   107  The interfaces `TextMarshaler` and `TextUnmarshaler` are supported for a `string` schema type. The object will
   108  be tested first for implementation of these interfaces, in the case of a `string` schema, before trying regular
   109  encoding and decoding. 
   110  
   111  ### Recursive Structs
   112  
   113  At this moment recursive structs are not supported. It is planned for the future.
   114  
   115  ## Benchmark
   116  
   117  Benchmark source code can be found at: [https://github.com/nrwiersma/avro-benchmarks](https://github.com/nrwiersma/avro-benchmarks)
   118  
   119  ```
   120  BenchmarkGoAvroDecode-10       	  495176	      2413 ns/op	     418 B/op	      27 allocs/op
   121  BenchmarkGoAvroEncode-10       	  420168	      2917 ns/op	     948 B/op	      63 allocs/op
   122  BenchmarkGoGenAvroDecode-10    	  757150	      1552 ns/op	     728 B/op	      45 allocs/op
   123  BenchmarkGoGenAvroEncode-10    	 1882940	       639.0 ns/op	     256 B/op	       3 allocs/op
   124  BenchmarkHambaDecode-10        	 3138063	       383.0 ns/op	      64 B/op	       4 allocs/op
   125  BenchmarkHambaEncode-10        	 4377513	       273.3 ns/op	     112 B/op	       1 allocs/op
   126  BenchmarkLinkedinDecode-10     	 1000000	      1109 ns/op	    1688 B/op	      35 allocs/op
   127  BenchmarkLinkedinEncode-10     	 2641016	       456.0 ns/op	     248 B/op	       5 allocs/op
   128  ```
   129  
   130  Always benchmark with your own workload. The result depends heavily on the data input.