1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
This page is meant to provide a brief overview of `avro`'s API:
+ [What is a `Type`?](#what-is-a-type)
+ [How do I get a `Type`?](#how-do-i-get-a-type)
+ [What about Avro files?](#what-about-avro-files)
+ [Next steps](#next-steps)
## What is a `Type`?
Each Avro type maps to a corresponding JavaScript [`Type`](API#class-type):
+ `int` maps to `IntType`.
+ `array`s map to `ArrayType`s.
+ `record`s map to `RecordType`s.
+ etc.
An instance of a `Type` knows how to [`decode`](Api#typedecodebuf-pos-resolver)
and [`encode`](Api#typeencodeval-buf-pos) and its corresponding objects. For
example the `StringType` knows how to handle JavaScript strings:
```javascript
var stringType = new avro.types.StringType();
var buf = stringType.toBuffer('Hi'); // Buffer containing 'Hi''s Avro encoding.
var str = stringType.fromBuffer(buf); // === 'Hi'
```
The [`toBuffer`](API#typetobufferval) and
[`fromBuffer`](API#typefrombufferval-resolver-nocheck) methods above are
convenience functions which encode and decode a single object into/from a
standalone buffer.
Each `type` also provides other methods which can be useful. Here are a few
(refer to the [API documentation](API#avro-types) for the full list):
+ JSON-encoding:
```javascript
var jsonString = type.toString('Hi'); // === '"Hi"'
var str = type.fromString(jsonString); // === 'Hi'
```
+ Validity checks:
```javascript
var b1 = stringType.isValid('hello'); // === true ('hello' is a valid string.)
var b2 = stringType.isValid(-2); // === false (-2 is not.)
```
+ Random object generation:
```javascript
var s = stringType.random(); // A random string.
```
## How do I get a `Type`?
It is possible to instantiate types directly by calling their constructors
(available in the `avro.types` namespace; this is what we used earlier), but in
the vast majority of use-cases they will be automatically generated by parsing
an existing schema.
`avro` exposes a [`parse`](Api#parseschema-opts) method to do the
heavy lifting:
```javascript
// Equivalent to what we did earlier.
var stringType = avro.parse({type: 'string'});
// A slightly more complex type.
var mapType = avro.parse({type: 'map', values: 'long'});
// The sky is the limit!
var personType = avro.parse({
name: 'Person',
type: 'record',
fields: [
{name: 'name', type: 'string'},
{name: 'phone', type: ['null', 'string'], default: null},
{name: 'address', type: {
name: 'Address',
type: 'record',
fields: [
{name: 'city', type: 'string'},
{name: 'zip', type: 'int'}
]
}}
]
});
```
Of course, all the `type` methods are available. For example:
```javascript
personType.isValid({
name: 'Ann',
phone: null,
address: {city: 'Cambridge', zip: 02139}
}); // === true
personType.isValid({
name: 'Bob',
phone: {string: '617-000-1234'},
address: {city: 'Boston'}
}); // === false (Missing the zip code.)
```
Since schemas are often stored in separate files, passing a path to `parse`
will attempt to load a JSON-serialized schema from there:
```javascript
var couponType = avro.parse('./Coupon.avsc');
```
For advanced use-cases, `parse` also has a few options which are detailed the
API documentation.
## What about Avro files?
Avro files (meaning [Avro object container files][object-container]) hold
serialized Avro records along with their schema. Reading them is as simple as
calling [`createFileDecoder`](Api#createfiledecoderpath-opts):
```javascript
var personStream = avro.createFileDecoder('./persons.avro');
```
`personStream` is a [readable stream][rstream] of decoded records, which we can
for example use as follows:
```javascript
personStream.on('data', function (person) {
if (person.address.city === 'San Francisco') {
doSomethingWith(person);
}
});
```
In case we need the records' `type` or the file's codec, they are available by
listening to the `'metadata'` event:
```javascript
personStream.on('metadata', function (type, codec) { /* Something useful. */ });
```
To access a file's header synchronously, there also exists an
[`extractFileHeader`](Api#extractfileheaderpath-opts) method:
```javascript
var header = avro.extractFileHeader('persons.avro');
```
Writing to an Avro container file is possible using
[`createFileEncoder`](Api#createfileencoderpath-type-opts):
```javascript
var encoder = avro.createFileEncoder('./processed.avro', type);
```
## Next steps
The [API documentation](Api) provides a comprehensive list of available
functions and their options. The [Advanced usage section](Advanced-usage) goes
through a few examples to show how the API can be used.
[object-container]: https://avro.apache.org/docs/current/spec.html#Object+Container+Files
[rstream]: https://nodejs.org/api/stream.html#stream_class_stream_readable
|
