Система типов и схема

Схема — центральная концепция Avro

В Avro схема определяет всё: как данные сериализуются, десериализуются, и как работает эволюция. В отличие от Protobuf и Thrift, где схема компилируется в код заранее, Avro-схема — JSON-документ, который можно обрабатывать динамически. Это позволяет строить generic tools (ридеры, конвертеры, валидаторы), которые не знают конкретную схему на этапе компиляции.

Два формата описания схем:

• JSON — основной, machine-readable формат. Все Avro-инструменты работают с JSON-схемами
• Avro IDL — человекочитаемый, C-подобный синтаксис. Компилируется в JSON-схему

Примитивные типы

Avro определяет 8 примитивных типов. Каждый тип имеет фиксированное бинарное представление:

Сложные типы

Avro определяет 6 сложных типов. Каждый описывается JSON-объектом со свойством "type":

Record

Именованный набор полей — основной тип для структурированных данных. Аналог struct в C, class в Java, message в Protobuf:

{
 "type": "record",
 "name": "User",
 "namespace": "com.example.avro",
 "doc": "A user record",
 "fields": [
 {"name": "id", "type": "long"},
 {"name": "name", "type": "string"},
 {"name": "email", "type": ["null", "string"], "default": null},
 {"name": "age", "type": "int", "default": 0}
 ]
}

Каждое поле имеет: name (обязательно), type (обязательно), default (опционально — критично для эволюции), doc, order, aliases.

Enum

Фиксированный набор символьных имён. Значение кодируется как 0-based index:

{
 "type": "enum",
 "name": "Status",
 "symbols": ["ACTIVE", "INACTIVE", "DELETED"],
 "default": "ACTIVE"
}

ACTIVE = 0, INACTIVE = 1, DELETED = 2 на wire. Поле default (с Avro 1.9) используется при schema evolution — если ридер встречает неизвестный символ, подставляется default.

Array

Упорядоченная коллекция элементов одного типа. Кодируется как серия blocks:

{
 "type": "array",
 "items": "string"
}

Map

Набор пар key-value. Ключ всегда string. Значение — произвольный тип:

{
 "type": "map",
 "values": "long"
}

Union

Тип, который может быть одним из перечисленных типов. Описывается JSON-массивом:

["null", "string"]

Это union из null и string — аналог Optional<String>. На wire: индекс типа (0 = null, 1 = string) + значение. Union не может содержать другой union (нет вложенных union) и не может содержать два типа с одним именем.

Fixed

Фиксированное количество байт. Аналог byte[N], записывается без length prefix:

{
 "type": "fixed",
 "name": "MD5",
 "size": 16
}

Named Types и Namespaces

Три типа в Avro являются named: record, enum, fixed. Они имеют:

• name — обязательное имя типа
• namespace — опциональное пространство имён (Java-style: com.example.avro)
• aliases — список альтернативных имён для schema evolution
• doc — документация

Полное имя (fullname) = namespace.name. Если namespace не указан, наследуется от ближайшего enclosing named type:

{
 "type": "record",
 "name": "Event",
 "namespace": "com.example",
 "fields": [
 {
 "name": "header",
 "type": {
 "type": "record",
 "name": "Header",
 "fields": [
 {"name": "timestamp", "type": "long"},
 {"name": "source", "type": "string"}
 ]
 }
 }
 ]
}

Здесь Header наследует namespace com.example → fullname = com.example.Header. Вложенный record можно ссылать по fullname из других типов: "type": "com.example.Header".

Aliases позволяют переименовывать типы и поля при schema evolution:

{
 "type": "record",
 "name": "UserEvent",
 "aliases": ["UserAction", "com.legacy.UserEvent"],
 "fields": [
 {"name": "userId", "type": "long", "aliases": ["user_id", "uid"]}
 ]
}

Ридер со схемой UserAction успешно прочитает данные, записанные со схемой UserEvent — alias разрешается при schema resolution.

Avro IDL

JSON-схемы verbose — Avro IDL предоставляет человекочитаемую альтернативу с C-подобным синтаксисом:

@namespace("com.example.avro")
protocol UserProtocol {

 enum Status {
 ACTIVE, INACTIVE, DELETED
 }

 record User {
 long id;
 string name;
 union { null, string } email = null;
 int age = 0;
 Status status = "ACTIVE";
 array<string> tags = [];
 }

 record Event {
 long timestamp;
 string type;
 union { null, User } user = null;
 }
}

IDL компилируется в JSON-схему утилитой avro-tools:

java -jar avro-tools.jar idl2schemata user.avdl output/

Логические типы

Логические типы — семантическая надстройка над примитивными и fixed типами. Физическое представление одно и то же, но ридер интерпретирует значение по-другому:

Пример JSON-схемы с логическими типами:

{
 "type": "record",
 "name": "Transaction",
 "fields": [
 {
 "name": "amount",
 "type": {
 "type": "bytes",
 "logicalType": "decimal",
 "precision": 10,
 "scale": 2
 }
 },
 {
 "name": "created_at",
 "type": {"type": "long", "logicalType": "timestamp-millis"}
 },
 {
 "name": "date",
 "type": {"type": "int", "logicalType": "date"}
 },
 {
 "name": "id",
 "type": {"type": "string", "logicalType": "uuid"}
 }
 ]
}

Каноническая форма схемы

Avro определяет Parsing Canonical Form (PCF) — нормализованное JSON-представление схемы, используемое для вычисления fingerprint:

Правила нормализации:

1. Удалить все свойства кроме type, name, fields, symbols, items, values, size
2. Из полей record оставить только name и type (убрать default, doc, aliases, order)
3. Заменить именованные типы на fullname при повторном использовании
4. Убрать пробелы

Fingerprint вычисляется как 64-bit Rabin hash от PCF — используется в Single Object Encoding (урок 05) для идентификации схемы по 8-байтовому значению.

Сравнение с другими системами типов

Ключевые выводы

1. 8 примитивных типов: null, boolean, int, long, float, double, bytes, string — каждый с фиксированным binary encoding
2. 6 сложных типов: record (named struct), enum (indexed symbols), array (block-encoded list), map (string keys only), union (tagged choice), fixed (byte array)
3. Named types (record, enum, fixed) имеют namespaces и aliases для schema evolution
4. Avro IDL — человекочитаемая альтернатива JSON-схемам, компилируется в JSON
5. Логические типы — семантическая надстройка: decimal, date, timestamps, uuid. Физический тип не меняется
6. Parsing Canonical Form — нормализованная схема для вычисления 64-bit Rabin fingerprint