pandas_udf 타입 — SCALAR/GROUPED_MAP/GROUPED_AGG의 서로 다른 입출력 계약
Delta Lake Schema Enforcement/Evolution 및 PySpark pandas_udf 타입 공식 문서 종합 (웹 리서치, 2026) — Delta Lake 공식 블로그(schema-enforcement, schema-evolution) + Apache Spark 공식문서(pyspark.sql.functions.pandas_udf) Apache Spark 공식문서 pyspark.sql.functions.pandas_udf
이 모듈을 다 읽으면
- SCALAR/GROUPED_MAP/GROUPED_AGG 세 타입이 각각 어떤 입력을 받아 어떤 출력을 내는지 설명할 수 있다
- spark-learn-49에서 다룬 applyInPandas가 실제로는 GROUPED_MAP 계열의 후속 API임을 설명할 수 있다
spark-learn-49에서 Arrow 기반 UDF 최적화와 UDAF 대안으로 applyInPandas()를 다뤘던 것을 전제로, 그 밑바탕이 되는 pandas_udf의 세 가지 타입이 입출력 형태에서 어떻게 다른지를 정리한다.
SCALAR — Series를 받아 같은 길이의 Series를 반환
SCALAR는 가장 기본적인 타입으로, 스칼라를 스칼라에 매핑하거나 벡터를 같은 길이의 벡터에 매핑하는 것과 같다 — pandas.Series를 입력으로 받아 같은 길이의 pandas.Series를 반환한다. spark-learn-49에서 다룬 일반 스칼라 UDF의 Arrow 가속(pythonUDF.arrow.enabled)이 바로 이 SCALAR 타입에 해당하는 경우다.
핵심 포인트
- SCALAR: pandas.Series 입력 → 같은 길이의 pandas.Series 반환 (spark-learn-49의 일반 스칼라 UDF Arrow 가속이 이 타입)
GROUPED_MAP — 그룹 하나를 통째로 받아 임의 형태로 반환
GROUPED_MAP은 세 타입 중 가장 유연하다 — 그룹 하나에 해당하는 pandas.DataFrame 전체를 입력으로 받고, 임의의 형태(행 수·컬럼 구성이 달라져도 됨)로 수정되거나 완전히 새로운 DataFrame을 반환할 수 있다. spark-learn-49에서 UDAF 대안으로 소개한 groupBy().applyInPandas()의 split-apply-combine 패턴이 바로 이 GROUPED_MAP 타입의 후속·구체 구현이다 — '그룹별로 쪼개고(split), pandas 함수를 적용하고(apply), 다시 합친다(combine)'는 동작이 이 타입의 자유로운 입출력 형태 덕분에 가능해진다.
핵심 포인트
- GROUPED_MAP: 그룹 하나의 전체 pandas.DataFrame을 입력받아 임의 형태(행 수·컬럼 구성 변경 가능)로 반환 — 세 타입 중 가장 유연
- spark-learn-49의 groupBy().applyInPandas() split-apply-combine 패턴이 이 GROUPED_MAP의 후속·구체 구현
GROUPED_AGG — 여러 값을 하나의 스칼라로 집약
GROUPED_AGG는 pandas.Series를 입력으로 받아 스칼라 하나를 반환한다 — 그룹이나 윈도우 안의 한 컬럼을 나타내는 하나 이상의 pandas.Series로부터 스칼라 값 하나로의 집계를 정의한다. 다만 이 타입은 부분 집계(partial aggregation)를 지원하지 않는다는 제약이 있다 — 즉 셔플 전에 미리 일부만 계산해두는 최적화(combiner 역할)를 못 쓰고, 전체 그룹 데이터가 다 모인 뒤에야 계산이 이뤄진다는 뜻이다.
핵심 포인트
- GROUPED_AGG: 하나 이상의 pandas.Series(그룹/윈도우 내 컬럼) 입력 → 스칼라 하나로 집계
- 부분 집계(partial aggregation)를 지원하지 않음 — 셔플 전 미리 일부 계산하는 combiner 최적화를 못 씀, 전체 그룹이 다 모여야 계산