---
title: "Apache Avro: jak zdarzenie z hali dociera do Kafki bez zgubionego pola"
url: "https://majchrzycki.com/blog/apache-avro-event-driven-kafka-profil"
description: "Apache Avro: schemat w JSON, zgodność czytelnika i pisarza, rejestr schematów przy Kafce. Architektura, cechy, przykład w firmie z ERP i WMS, ograniczenia."
---

# Apache Avro: jak zdarzenie z hali dociera do Kafki bez zgubionego pola

21 października 2026·8 min czytania·[Krzysztof Majchrzycki](https://majchrzycki.com/o-mnie)

Temat: [Open Source AI](https://majchrzycki.com/blog/filar/open-source-ai)

**Avro jest formatem, który w architekturze zdarzeniowej pilnuje jednej rzeczy: że to, co system magazynowy wysłał, system sprzedaży przeczyta — także wtedy, gdy między wysłaniem a odczytem ktoś dodał pole.** Robi to przez schemat zapisany w JSON, formalne reguły zgodności czytelnika i pisarza oraz rejestr schematów, w którym każda wersja ma numer. Dla firmy, która łączy ERP, WMS i sklep strumieniem zdarzeń w Apache Kafka, Avro jest umową między działami zapisaną w formacie, a nie w mailu.

Ten profil pokazuje, jak Avro działa od środka, gdzie przewyższa JSON i Protobuf, a gdzie oddaje pole Parquet. Piszemy go dla architekta integracji, zespołu utrzymującego Kafkę i menedżera, który odpowiada za to, żeby trzy systemy mówiły o zamówieniu to samo. Pojęcie formatu pliku (data format) i jego relację do formatu tabeli wyjaśnia [poradnik o formatach plików i tabel](https://majchrzycki.com/blog/co-to-jest-format-tabeli-poradnik-dla-firm).

## Co dziś nie działa

> — _Import zamówień ze sklepu do WMS-a stanął w sobotę o 6:00._ — _Co się zmieniło?_ — _Sklep dodał pole „rabat\_procent”. Nasz parser tego nie znał._ — _Przecież dodanie pola nie powinno nic psuć._ — _Nie powinno. Ale nikt nie zapisał, co znaczy „nie powinno”._ _(Umowa między sklepem a magazynem istniała. W głowie programisty, który odszedł w marcu.)_

W firmie od 50 do 300 osób systemy rozmawiają ze sobą zwykle przez pliki i interfejsy budowane punkt–punkt: eksport z ERP do WMS, drugi eksport z ERP do sklepu, trzeci ze sklepu do systemu kurierskiego. Każde połączenie ma własną, niespisaną definicję rekordu. Dodanie jednego pola po jednej stronie to loteria po drugiej. A kiedy połączeń jest dziesięć, każdy nowy wymóg działu sprzedaży — „chcemy widzieć rabat na zamówieniu” — kosztuje tydzień uzgadniania i trzy weekendy awarii.

Architektura zdarzeniowa (event-driven architecture) zamienia dziesięć połączeń na jeden strumień: każdy system publikuje zdarzenia („zamówienie złożone”, „paleta wydana”, „zwrot przyjęty”), a każdy zainteresowany je czyta. To działa pod jednym warunkiem — kształt zdarzenia musi być umową, której ktoś pilnuje. Tym kimś jest Avro z rejestrem schematów.

## Architektura wewnętrzna: schemat, bajty, kontener

[Specyfikacja Avro](https://avro.apache.org/docs/1.12.0/specification/) (aktualne wydanie 1.12.2 z sierpnia 2026, sprawdzono 21.10.2026) opisuje cztery elementy, które warto rozumieć, zanim ktoś w zespole powie „po prostu użyjmy Avro”.

**Schemat w JSON.** Schemat to dokument JSON: typy proste (`null`, `boolean`, `int`, `long`, `float`, `double`, `bytes`, `string`) i złożone (`record`, `enum`, `array`, `map`, `union`, `fixed`). Pole może mieć wartość domyślną — i to ta wartość domyślna decyduje, czy dodanie pola będzie zmianą zgodną. Unia `["null", "string"]` to sposób zapisu pola opcjonalnego. Schemat czyta człowiek i maszyna, więc może leżeć w repozytorium obok kodu i podlegać przeglądowi jak każda inna zmiana umowy.

**Kodowanie binarne bez znaczników.** W danych nie ma nazw pól ani typów. Pisarz zapisuje wartości w kolejności ze schematu, czytelnik odczytuje je w tej samej kolejności, bo zna schemat. Dlatego rekord Avro jest mały — i dlatego bez schematu jest nieczytelnym ciągiem bajtów. To nie wada, to konstrukcja: schemat musi być dostępny, więc nie da się go „zgubić po drodze”.

**Plik kontenerowy (Object Container File).** Gdy zdarzenia zapisuje się do pliku, a nie wysyła pojedynczo, Avro pakuje je w kontener: nagłówek z magicznymi bajtami, metadanymi (wymagany `avro.schema`, opcjonalny `avro.codec`) i szesnastobajtowym znacznikiem synchronizacji, a potem bloki rekordów rozdzielone tym znacznikiem. Znacznik pozwala podzielić duży plik między wiele procesów bez czytania go od początku. Kodeki `null` i `deflate` są wymagane; `snappy`, `zstandard`, `bzip2` i `xz` opcjonalne.

**Kodowanie pojedynczego obiektu (single-object encoding).** Gdy rekord leci sam — przez kolejkę, przez HTTP — nie ma nagłówka pliku, w którym leżałby schemat. Avro definiuje więc format: dwubajtowy marker, ośmiobajtowy odcisk schematu (CRC-64-AVRO) i dane. Odczytujący znajduje schemat po odcisku. W praktyce w ekosystemie Kafki tę rolę pełni rejestr schematów z własnym formatem ramki, o czym niżej.

Element

Co robi

Dlaczego ma znaczenie dla firmy

Schemat JSON

definiuje pola, typy, wartości domyślne

umowa między działami, którą można przejrzeć i wersjonować

Kodowanie binarne

wartości bez nazw pól

mały komunikat; schemat zawsze musi być pod ręką

Plik kontenerowy

schemat w nagłówku, bloki ze znacznikiem

archiwum zdarzeń czytelne po latach, dzielone między procesy

Kodowanie pojedynczego obiektu

odcisk schematu przed danymi

zdarzenie w locie da się rozpoznać bez pliku

## Rozwiązywanie schematu: umowa, która przeżywa zmiany

Serce Avro to reguły rozwiązywania schematu czytelnika i pisarza (reader/writer schema resolution). Pisarz zapisał rekord według swojego schematu. Czytelnik ma swój — być może starszy, być może nowszy. Specyfikacja mówi, co się dzieje:

-   Pola dopasowuje się **po nazwie**, nie po pozycji. Przesunięta kolumna z pierwszej scenki nie ma tu racji bytu.
-   Pole, które pisarz zapisał, a czytelnik go **nie zna**, jest pomijane. Sklep może dodać `rabat_procent`, a WMS, który o rabatach nie wie, czyta dalej.
-   Pole, którego czytelnik **oczekuje**, a pisarz nie zapisał, dostaje wartość domyślną ze schematu czytelnika. Jeśli wartości domyślnej nie ma — odczyt kończy się błędem. To jest miejsce, w którym zmiana staje się niezgodna.
-   Dozwolone są **promocje typów**: `int` na `long`, `float` lub `double`; `long` na `float` lub `double`; `float` na `double`; `string` na `bytes` i odwrotnie. Zmiana `string` na `int` nie jest promocją — jest zerwaniem umowy.
-   Dla `enum` nieznany symbol przyjmuje wartość domyślną czytelnika, jeśli ją zdefiniowano; dla `union` gałąź pisarza dopasowuje się do pierwszej zgodnej gałęzi czytelnika.

Z tych reguł wynikają trzy polityki zgodności, które rejestr schematów egzekwuje przy rejestracji nowej wersji:

Polityka

Co gwarantuje

Co wolno zmienić

Wstecz (backward)

nowy czytelnik przeczyta stare dane

dodać pole z wartością domyślną, usunąć pole

W przód (forward)

stary czytelnik przeczyta nowe dane

dodać pole, usunąć pole z wartością domyślną

Pełna (full)

oba kierunki

dodać lub usunąć tylko pola z wartością domyślną

**Rejestr schematów przy Kafce.** Według [dokumentacji Confluent](https://docs.confluent.io/platform/current/schema-registry/fundamentals/serdes-develop/index.html) każdy komunikat w Kafce zaczyna się bajtem magicznym (0), czterobajtowym identyfikatorem schematu i dopiero potem danymi Avro. Producent przy pierwszym wysłaniu rejestruje schemat i dostaje identyfikator; konsument po identyfikatorze pobiera schemat i rozwiązuje go względem swojego. Rejestr obsługuje Avro, Protobuf i JSON Schema, a jego API implementują też otwarte alternatywy — Apicurio Registry i Karapace. Najważniejsze jest to, że rejestr **odrzuca** rejestrację schematu niezgodnego z polityką. Umowa między działami ma wreszcie strażnika, który nie wyjeżdża na urlop.

Schemat działania Avro z rejestrem schematów między trzema systemami firmy. Sklep, ERP i WMS publikują zdarzenia do Kafki; każde zdarzenie niesie identyfikator schematu z rejestru. Rejestr trzyma wersje schematu i odrzuca zmianę niezgodną z polityką. Trzy przypadki: dodanie pola z wartością domyślną — przechodzi, stary czytelnik je pomija; dodanie pola bez wartości domyślnej — rejestr odrzuca; zmiana typu z tekstu na liczbę — rejestr odrzuca. Co zostaje przy człowieku: właściciel schematu decyduje o zmianie umowy, polityka zgodności jest decyzją, nie ustawieniem domyślnym. Ocena autora.

Rejestr schematów jako strażnik umowy między działami: co przechodzi, co zostaje odrzucone i kto podejmuje decyzję. Schemat mechanizmu według specyfikacji Avro i dokumentacji rejestru; podział ról to ocena autora.

## Unikalne cechy — i miejsce Avro w stosie danych

Cecha

Co daje

Gdzie to widać

Schemat podróżuje z danymi

zdarzenie zawsze da się odczytać poprawnie

nagłówek pliku, identyfikator w rejestrze

Formalne reguły zgodności

zmiana schematu jest przewidywalna i sprawdzalna

polityka w rejestrze, przegląd schematu jak kodu

Mały rekord

tani transport i składowanie strumienia

brak nazw pól w danych

Niezależność od języka

ERP w Javie, sklep w Pythonie, WMS w C# czytają to samo

biblioteki Avro dla wielu języków, tryb generyczny bez generowania kodu

Wsparcie narzędzi strumieniowych

gotowe konektory i serializatory

Kafka Connect, Debezium, Flink, Spark, Hudi Streamer

Rola w formatach tabel

manifesty Apache Iceberg są plikami Avro

lista plików czytana w całości, rekord po rekordzie

Ostatni wiersz pokazuje, dlaczego spór „Avro czy Parquet” jest źle postawiony: nawet format tabeli zbudowany na Parquet używa Avro tam, gdzie czyta się całe rekordy po kolei. Avro i Parquet to dwie cegły o różnym kształcie, a nie dwa konkurencyjne budynki. Rozwinięcie tego porównania znajdziecie w tekście [Parquet czy Avro: kolumna, kiedy czytacie; wiersz, kiedy piszecie](https://majchrzycki.com/blog/parquet-vs-avro-kiedy-kolumna-kiedy-wiersz).

## Przykład dydaktyczny: trzy systemy, jedna umowa

To przykład ilustracyjny, nie studium klienta — pokazuje mechanizm na typowej firmie, nie opisuje konkretnego wdrożenia.

Firma produkcyjno-handlowa, około 150 osób. Trzy systemy: ERP (zamówienia, faktury, stany księgowe), WMS (lokalizacje, kompletacja, wydania) i sklep B2B z integracją do marketplace. Dziś połączone są sześcioma eksportami plikowymi i dwoma interfejsami, które napisał integrator trzy lata temu. Każda zmiana w jednym systemie wymaga sprawdzenia, które z ośmiu połączeń się przewróci — a sprawdzenie polega na uruchomieniu i czekaniu.

**Stan po przejściu na zdarzenia w Avro.** Każdy system publikuje do Kafki trzy–cztery typy zdarzeń: „zamówienie złożone”, „zamówienie zmienione”, „wydanie zrealizowane”, „zwrot przyjęty”. Każdy typ ma schemat Avro w rejestrze z polityką zgodności „wstecz” i przypisanym właścicielem — osobą z działu, który zdarzenie publikuje. Konsumenci czytają to, co ich dotyczy: WMS czyta zamówienia, ERP czyta wydania i zwroty, warstwa analityczna czyta wszystko i zapisuje do tabel w lakehouse.

**Co robi system.** Rejestr sprawdza każdą nową wersję schematu i odrzuca niezgodną, zanim dotrze do produkcji. Serializatory w konektorach dbają, by każdy komunikat niósł identyfikator schematu. Konsumenci rozwiązują schemat automatycznie: nowe pole `rabat_procent` ze sklepu trafia do analityki, a WMS je pomija, bo go nie potrzebuje. Nikt nie pisze parsera od nowa.

**Co zostaje przy człowieku.** Decyzja, że `rabat_procent` w ogóle powstaje i co znaczy — czy to rabat od ceny katalogowej, czy od ceny po poprzednich rabatach — należy do właściciela schematu z działu sprzedaży. Decyzja o polityce zgodności (czy dopuszczamy usuwanie pól) należy do architekta i jest spisana. Decyzja, kto odpowiada, gdy dwa działy chcą zmienić to samo pole w różny sposób, należy do kierownika operacji. Avro egzekwuje umowę; treść umowy ustalają ludzie.

**Czym to zmierzyć.** Załóżmy, że dziś każda zmiana pola w jednym z systemów wymaga ręcznego sprawdzenia ośmiu połączeń i średnio jednej awarii na kwartał. Po zmianie mierzycie: liczbę awarii importu po zmianie schematu (cel: zero, bo niezgodne zmiany nie przechodzą rejestracji), czas od zgłoszenia nowego pola przez dział do jego obecności w analityce, liczbę połączeń punkt–punkt do utrzymania (z ośmiu do jednego strumienia i trzech konsumentów). Koszt całkowity (Total Cost of Ownership, TCO) nie spada przez sam format — spada, bo osiem umów ustnych zamienia się w cztery spisane schematy z właścicielem. Liczby w Waszej firmie będą inne; mechanizm ten sam.

## Gdzie Avro zaszkodzi albo nie wystarczy

**Analityka kolumnowa.** Raport marży na plikach Avro czyta wszystkie pola każdego rekordu. Zdarzenia do analityki muszą trafić do tabeli na Parquet — Avro w tej roli jest tylko kurierem.

**Rejestr to kolejny komponent z właścicielem.** Rejestr schematów trzeba uruchomić, zabezpieczyć, kopiować i monitorować. Bez niego Avro w Kafce traci swoją główną zaletę. Jeśli nikt nie chce być właścicielem rejestru, to znak, że firma nie jest gotowa na architekturę zdarzeniową — nie na Avro.

**Unie i wartości domyślne łatwo zaprojektować źle.** Pole `["null", "string"]` z domyślnym `null` jest poprawne; pole `["string", "null"]` z domyślnym `null` już nie, bo wartość domyślna musi pasować do pierwszej gałęzi unii. Takie szczegóły nie są trudne, ale wymagają, by schematy przechodziły przegląd jak kod.

**Alternatywy.** Protobuf, gdy te same definicje służą też komunikacji między usługami (gRPC) i zespół programistów już go używa. JSON Schema, gdy czytelność dla człowieka jest ważniejsza niż rozmiar. Rejestr Confluent obsługuje wszystkie trzy, więc decyzja nie zamyka drogi — ale mieszanie formatów w jednym strumieniu to prośba o kłopoty.

## Po czym poznać wartość

Miernik wyniku

Miernik próżności

Awarie importu po zmianie schematu na kwartał

Liczba schematów w rejestrze

Czas od zgłoszenia pola do jego obecności w raporcie

Liczba tematów w Kafce

Liczba połączeń punkt–punkt do utrzymania

Liczba komunikatów na sekundę

Liczba pól bez właściciela i bez definicji

Rozmiar klastra Kafki

Uczciwie: na liczbę awarii wpływa też jakość danych źródłowych i dyscyplina przeglądu schematów. Avro daje narzędzie do egzekwowania umowy — nie zastępuje umowy.

## Pierwszy krok w poniedziałek

1.  Wybierzcie jeden temat Kafki (albo jedno dzisiejsze połączenie plikowe, które najczęściej się przewraca) i spiszcie schemat jego rekordu w Avro — z wartościami domyślnymi dla każdego pola, które bywa puste.
2.  Uruchomcie rejestr schematów z polityką zgodności „wstecz” i zarejestrujcie schemat.
3.  Spróbujcie zarejestrować wersję z nowym polem bez wartości domyślnej. Rejestr ma odmówić. Jeśli przyjął — sprawdźcie politykę.
4.  Wpiszcie przy schemacie imię i nazwisko właściciela z działu biznesowego, nie z IT.

Jeżeli przy punkcie czwartym nikt nie chce się podpisać, zaczęliście od właściwego problemu.

## Co sprawdzić przed decyzją

-   Wersję biblioteki Avro w każdym języku, który u Was publikuje lub czyta zdarzenia; aktualne wydanie to 1.12.2 ([blog projektu](https://avro.apache.org/blog/), sprawdzono 21.10.2026).
-   Który rejestr schematów (Confluent, Apicurio, Karapace), na jakiej licencji i w jakim modelu wdrożenia; czy Wasze konektory Kafka Connect i Debezium go obsługują.
-   Politykę zgodności na każdym temacie — spisaną, nie domyślną.
-   Kto jest właścicielem każdego schematu i jak wygląda przegląd zmiany.

## Najważniejsze w skrócie

-   Avro to format wierszowy ze schematem w JSON, kodowaniem binarnym bez nazw pól i formalnymi regułami rozwiązywania schematu czytelnika i pisarza.
-   W Kafce schemat nie podróżuje z każdym komunikatem — podróżuje jego identyfikator, a rejestr schematów trzyma wersje i odrzuca zmiany niezgodne z polityką.
-   Dodanie pola z wartością domyślną jest zmianą zgodną; dodanie bez wartości domyślnej albo zmiana typu poza promocjami — nie.
-   Avro jest kurierem zdarzeń; do analityki dane trafiają do tabeli na Parquet. Nawet Iceberg używa Avro na manifesty, bo czyta je rekord po rekordzie.
-   Format egzekwuje umowę, ale treść umowy — co znaczy pole, kto jest jego właścicielem, jaka polityka zgodności — to decyzje ludzi.

-   Dane i analityka
-   Open Source AI
-   Kafka
-   Integracja systemów
-   Inżynieria danych

## Nie wiecie, w jakim formacie leżą dane, na których ma pracować AI?

Prezentacja dla zarządu: nazwiemy dane, ich właścicieli i miejsce, w którym powinny leżeć — razem z decyzją o formacie plików i tabel, zanim kupicie platformę albo zatrudnicie zespół. Niezależnie od vendora i partnera.

[Umów prezentację dla zarządu](https://majchrzycki.com/wspolpraca/prezentacja-systemu-ai-dla-zarzadu)

FAQ

## Najczęstsze pytania

Avro czy JSON w Kafce?

JSON jest wygodny na start i czytelny dla człowieka, ale nie niesie typów ani gwarancji zgodności: każdy producent może wysłać inny kształt rekordu. Avro z rejestrem schematów odrzuca niezgodną zmianę przy rejestracji, a komunikat jest mniejszy, bo nie zawiera nazw pól. Jeśli zdarzenia czyta więcej niż jeden system, Avro (albo Protobuf) jest bezpieczniejszym wyborem.

Czy Avro nadaje się do raportów i analityki?

Słabo. Avro zapisuje rekordy wierszowo, więc raport, który potrzebuje dwóch kolumn, czyta wszystkie pola każdego rekordu. Do analityki zdarzenia przetwarza się do tabeli w formacie tabeli (Iceberg, Delta Lake, Paimon) na plikach Parquet. Avro zostaje po stronie strumienia.

Jak przejść z Avro do Parquet w lakehouse?

Zadanie strumieniowe (Flink, Spark, Kafka Connect) czyta rekordy Avro z Kafki ze schematem z rejestru i zapisuje je do tabeli w formacie tabeli, która układa dane w Parquet. Decyzją do podjęcia jest opóźnienie: częstsze zapisy dają świeższe dane i więcej małych plików do kompaktowania.

Który rejestr schematów wybrać?

Confluent Schema Registry jest najszerzej wspierany w narzędziach; Apicurio Registry i Karapace to otwarte alternatywy zgodne z jego API. Decyduje licencja, model wdrożenia (własna infrastruktura czy usługa) i to, czy Wasze konektory i biblioteki go obsługują. Ważniejsze od wyboru narzędzia jest ustawienie polityki zgodności i wskazanie właściciela każdego schematu.

## Czytaj dalej

-   [Parquet czy Avro? Kolumna, kiedy czytacie; wiersz, kiedy piszecie](https://majchrzycki.com/blog/parquet-vs-avro-kiedy-kolumna-kiedy-wiersz)
-   [Data Formats vs Table Formats: fundamenty nowoczesnego data lakehouse](https://majchrzycki.com/blog/co-to-jest-format-tabeli-poradnik-dla-firm)
-   [Apache Parquet: dlaczego raport czyta dwie kolumny, a nie całą tabelę — i co to robi z fakturą za chmurę](https://majchrzycki.com/blog/apache-parquet-ai-os)
-   [Delta Lake, Apache Iceberg czy Apache Hudi? Trzy plany tego samego budynku](https://majchrzycki.com/blog/delta-lake-vs-iceberg-vs-hudi-porownanie-formatow-tabel)