Avro 확장

Avro 확장

avro 확장은 DuckDB가 Apache Avro 파일을 읽을 수 있게 해줘요. Avro 파일을 테이블처럼 바로 쿼리할 수 있어요.

출처: 문서

본문

avro 확장은 DuckDB가 Apache Avro 파일을 읽을 수 있게 해줘요.

avro 확장은 2024년 말 커뮤니티 확장으로 릴리스됐고, 2025년 초에 코어 확장이 됐어요.

read_avro 함수

이 확장은 read_avro라는 단일 DuckDB 함수를 추가해요. 이 함수는 이렇게 사용할 수 있어요.

FROM read_avro('⟨some_file⟩.avro');

이 함수는 Avro 파일의 내용을 DuckDB 테이블로 노출해요. 그런 다음 임의의 SQL 구문을 사용해 이 테이블을 추가로 변환할 수 있어요.

파일 I/O

read_avro 함수는 DuckDB의 파일 시스템 추상화에 통합되어 있어서, 예를 들어 HTTP나 S3 소스에서 직접 Avro 파일을 읽을 수 있어요. 예를 들어:

FROM read_avro('https://blobs.duckdb.org/data/userdata1.avro');
FROM read_avro('s3://⟨your-bucket⟩/⟨some_file⟩.avro');

그냥 "작동"해요.

단일 읽기 호출에서 여러 파일을 glob하거나 파일 목록을 함수에 전달할 수도 있어요.

FROM read_avro('some_file_*.avro');
FROM read_avro(['some_file_1.avro', 'some_file_2.avro']);

파일 이름에 유용한 정보가 들어 있다면(안타깝게도 흔한 일이죠) filename 인자를 read_avro에 전달할 수 있어요.

FROM read_avro('some_file_*.avro', filename=true);

그러면 결과 집합에 Avro 파일의 실제 파일 이름을 포함하는 추가 컬럼이 생겨요.

스키마 변환

이 확장은 Avro 스키마를 DuckDB 스키마로 자동 변환해요. 재귀적 타입 정의(DuckDB가 지원하지 않는)를 제외한 모든 Avro 타입을 변환할 수 있어요.

타입 매핑은 Avro가 NULL을 다루는 "독특한" 방식을 제외하면 매우 직관적이에요. 다른 시스템과 달리 Avro는 NULL을 예를 들어 INTEGER 범위의 가능한 값으로 취급하지 않고, 실제 타입과 특별한 NULL 타입의 조합으로 NULL을 표현해요. DuckDB는 어떤 값이든 NULL이 될 수 있다는 점에서 다르죠. 물론 DuckDB도 UNION 타입을 지원하지만, 이는 작업하기 상당히 번거로워요.

이 확장은 가능한 경우 Avro 스키마를 단순화해요. 어떤 타입과 특별한 null 타입의 Avro union은 null이 아닌 타입으로만 단순화돼요. 예를 들어 union 타입 ["int","null"]의 Avro 레코드는 DuckDB INTEGER가 되고, 때때로 NULL이 되는 것뿐이에요. 마찬가지로 단일 타입만 포함하는 Avro union은 포함된 타입으로 변환돼요. 예를 들어 union 타입 ["int"]의 Avro 레코드도 DuckDB INTEGER가 돼요.

이 확장은 또한 Avro 스키마를 "평평하게(flatten)" 만들어요. Avro는 테이블을 최상위 "record" 필드로 정의하는데, 이는 DuckDB STRUCT 필드와 같아요. 더 편리한 처리를 위해 이 확장은 단일 최상위 레코드의 항목을 최상위 컬럼으로 변환해요.

구현

내부적으로 이 확장은 "공식" Apache Avro C API를 사용해요. 메모리에서 Avro 파일을 읽을 수 있도록 약간의 패치를 가했어요.

제한 사항 및 향후 계획

  • 이 확장은 현재 단일(대형) Avro 파일을 읽거나 파일 목록을 읽을 때 병렬 처리를 사용하지 않아요. 후자의 경우 병렬 처리 지원 추가가 로드맵에 있어요.
  • 현재 프로젝션 또는 필터 푸시다운 지원이 없지만, 이 역시 이후 단계에서 계획돼 있어요.
  • Avro 라이브러리 의존성 문제로 현재 DuckDB의 Wasm 또는 Windows-MinGW 빌드에 대한 지원이 없어요. 결국 해결할 계획이에요.
  • 위에서 언급했듯이 DuckDB는 Avro가 가진 재귀적 타입 정의를 표현할 수 없으며, 이는 바뀌기 어려워요.
  • 사용자가 별도의 Avro 스키마 파일을 제공할 수 있는 지원이 없어요. 이는 바뀌기 어려워요. 지금까지 본 모든 Avro 파일에는 스키마가 내장되어 있었어요.
  • 현재 DuckDB의 다른 리더들이 지원하는 union_by_name 플래그에 대한 지원이 없어요. 이는 향후 계획돼 있어요.

더 알아보기 (Learn more)

  • Apache Avro 공식 문서에서 Avro 형식을 더 자세히 살펴볼 수 있어요.