Apache Avro Reference

Avro 스키마, 타입, 스키마 진화 규칙 레퍼런스

18개 결과

Apache Avro Reference 소개

Apache Avro 스키마 레퍼런스는 Apache Kafka, Hadoop 생태계 전반에서 사용되는 Avro 직렬화 시스템을 체계적으로 정리한 검색형 참조 자료입니다. Avro는 JSON 형식의 스키마로 데이터 구조를 정의하여 고처리량 이벤트 스트리밍 파이프라인에서 폭넓게 활용됩니다. 이 레퍼런스는 null, boolean, int, long, float, double, bytes, string 등 모든 기본 타입과, record, enum, array, map, union, fixed 등 모든 복합 스키마 타입을 실제 JSON 예제와 함께 제공합니다.

데이터 엔지니어, 백엔드 개발자, 아키텍트에게는 스키마 진화(Schema Evolution) 섹션이 특히 유용합니다. 이 레퍼런스는 세 가지 호환성 모드를 명확히 설명합니다. Forward Compatibility(새 스키마로 쓴 데이터를 이전 코드가 읽는 경우), Backward Compatibility(이전 스키마로 쓴 데이터를 새 코드가 읽는 경우), Full Compatibility(양방향 모두 보장). Schema Resolution 규칙 — writer 스키마와 reader 스키마 간 필드 매칭 방식 — 도 예제 중심으로 간결하게 정리되어 있습니다.

논리 타입(Logical Types) 섹션은 기본 타입 위에 의미론적 레이어를 추가하는 Avro의 특수 타입들을 다룹니다. epoch 이후 일수를 int로 저장하는 date 타입, 밀리초를 long으로 저장하는 timestamp-millis 타입, precision과 scale로 고정소수점을 표현하는 decimal 타입이 포함됩니다. 타입, 스키마, 진화, 논리타입 4개 카테고리로 구분되어 있어 개발 중이나 Kafka 토픽 스키마 설계 시 빠른 참조가 가능합니다.

주요 기능

null, boolean, int/long, float/double, bytes/string 등 6가지 Avro 기본 타입 전체 JSON 예제 제공
record, enum, array, map, union, fixed 등 6가지 복합 스키마 타입과 실용적인 코드 예제
Forward, Backward, Full Compatibility 세 가지 스키마 진화 모드 설명 및 실무 규칙
writer/reader 스키마 간 필드 매칭을 설명하는 Schema Resolution 규칙 정리
date, timestamp-millis, decimal 논리 타입과 precision/scale 사용법
개발 중 빠른 조회를 위한 검색 및 카테고리 필터 기능
스키마 정의에 바로 복사해 쓸 수 있는 구문 하이라이트 JSON 코드 예제
완전 무료, 회원가입 불필요, 첫 로딩 후 오프라인 사용 가능

자주 묻는 질문

Apache Avro란 무엇이고 어떤 상황에 사용하나요?

Apache Avro는 JSON으로 정의된 스키마를 사용해 데이터를 효율적인 이진 형식으로 직렬화하는 프레임워크입니다. Apache Kafka 파이프라인(Schema Registry 연동), Hadoop 기반 데이터 레이크, 스키마 유효성 검증이 필요한 시스템에서 널리 사용됩니다. 특히 시간이 지남에 따라 데이터 구조를 변경해야 하는 스키마 진화가 필요한 경우에 적합합니다.

Avro의 record, map 타입은 어떻게 다른가요?

record는 Avro에서 구조체(struct/object)에 해당하며, 각각 타입이 지정된 이름 있는 필드들로 구성됩니다. map은 키가 항상 문자열이고 값이 동일한 타입인 키-값 저장소입니다 (예: {"type":"map","values":"int"}). Avro에는 별도의 struct 키워드가 없으며, 구조화된 객체에는 모두 record를 사용합니다.

Avro에서 nullable 필드를 어떻게 정의하나요?

Avro에서 union 타입은 ["null","string"]처럼 JSON 배열로 표현합니다. 이는 필드가 null이거나 문자열일 수 있다는 의미입니다. null을 기본값으로 하려면 배열의 첫 번째에 "null"을 두어야 합니다(기본값은 첫 번째 타입과 일치해야 하기 때문). 예: {"name":"email","type":["null","string"],"default":null}.

Forward Compatibility와 Backward Compatibility의 차이는 무엇인가요?

Backward Compatibility는 새 코드(새 스키마)가 이전 코드로 작성된 데이터를 읽을 수 있음을 의미합니다. 필드를 추가하거나(기본값 필요) 삭제할 수 있습니다. Forward Compatibility는 이전 코드가 새 코드로 작성된 데이터를 읽을 수 있음을 의미합니다. Full Compatibility는 양방향 모두를 보장하므로 모든 필드 추가 및 삭제에 기본값이 필요합니다.

Avro 논리 타입은 어떻게 동작하나요?

Avro 논리 타입은 기본 타입에 logicalType 속성을 추가하여 의미론적 의미를 부여합니다. 예를 들어 {"type":"int","logicalType":"date"}는 달력 날짜를 Unix epoch(1970-01-01) 이후 일수로 저장합니다. decimal 논리 타입은 bytes 또는 fixed 타입에 precision과 scale을 추가합니다. Avro 라이브러리는 이 논리 타입을 LocalDate나 BigDecimal 같은 언어 네이티브 타입으로 변환합니다.

Avro의 Schema Resolution이란 무엇인가요?

Schema Resolution은 writer 스키마와 reader 스키마가 다를 때 Avro가 데이터를 읽는 방식입니다. 필드는 이름으로 매칭됩니다(위치가 아님). writer에만 있는 필드는 무시됩니다. reader에만 있는 필드는 해당 필드의 기본값이 사용됩니다. 기본값이 없는 필수 필드가 writer 스키마에 없으면 역직렬화가 실패합니다.

Kafka Schema Registry에서 Avro는 어떻게 사용되나요?

Confluent Schema Registry는 Kafka 토픽에서 사용되는 Avro(및 Protobuf/JSON Schema) 스키마를 중앙에서 관리합니다. 프로듀서는 메시지 발행 전 스키마를 등록하고, 컨슈머는 ID로 스키마를 조회하여 메시지를 역직렬화합니다. Registry는 호환성 규칙(backward, forward, full)을 강제하여 스키마 변경이 기존 컨슈머를 깨뜨리지 않도록 합니다. Kafka의 Avro 메시지는 5바이트(매직 바이트 + 스키마 ID)로 시작합니다.

Avro record에서 기본값이 있는 필드를 어떻게 정의하나요?

Avro record 스키마에서 각 필드에 "default" 속성을 추가할 수 있습니다. 기본 타입의 경우 기본값은 해당 타입과 일치해야 합니다(int라면 "default":0). union 타입의 경우 기본값은 배열의 첫 번째 타입과 일치해야 하므로, null을 기본값으로 하려면 배열에 "null"을 먼저 두어야 합니다. 예: {"name":"score","type":["null","int"],"default":null} 또는 {"name":"count","type":"int","default":0}.