Spark에서 .option("someKey", "someValue") 와 같이 정의되지 않은 옵션을 줘도 에러가 나지 않는 이유

아래 글은 Apache Spark에서 데이터를 읽거나 쓸 때, .option("key", "value") 형태로 임의 옵션을 넘기면 왜 에러가 나지 않고 무시될 수 있는지, 그리고 MongoDB Spark 커넥터처럼 버전에 따라 옵션 이름이 달라질 때 어떤 일이 생기는지 간단히 정리한 포스트입니다.

---

0. 배경

Spark에서는 DataFrameReader(또는 DataFrameWriter)를 사용할 때
예) 

df = (
    spark.read
        .format("mongodb")
        .option("uri", "mongodb://...")
        .option("pipeline", '[{ "$project": {...} }]')  # 예: 파이프라인 옵션
        .load()
)

 

이런 식으로 .option("key", "value")로 설정값을 넣습니다.
하지만 정의되지 않은 옵션이나 버전마다 다른 키명을 사용할 경우, Spark가 해당 옵션을 모르겠다며 즉시 에러를 내지 않고 그냥 무시해버리는 상황이 발생할 수 있습니다.

 

1. Spark의 옵션 전달 구조

(1) Spark 자체가 옵션 키를 직접 검증하지 않는다

Spark Core 레벨에서 .option("someKey", "someValue")는 내부적으로 (String -> String) 매핑을 만들어,
해당 DataSource(커넥터)로 그대로 전달합니다.
Spark는 “이 옵션이 맞는지 틀린지”를 미리 판단하지 않습니다.

(2) DataSource(커넥터) 쪽에서만 유효성 검사

실제로 MongoDB Spark 커넥터나 CSV/JSON 리더 등이 “이 옵션을 지원하느냐 마느냐”를 결정합니다.

• 만약 커넥터가 pipeline 옵션을 인식하면 쓰고,
• 인식하지 못하는(정의되지 않은) 옵션이면 무시하고 별도 에러 메시지를 주지 않는 구현이 많습니다.

따라서 키 이름이 틀리거나, 커넥터 버전이 달라서 옵션 이름이 바뀌었거나, 그냥 오탈자를 넣더라도 Spark는 문제삼지 않고 넘어가는 거죠.

 

2. MongoDB Spark 커넥터 버전에 따른 예시

 

예를 들어,

• 구 버전 커넥터에서는 aggregation.pipeline 라는 키를 써야하고
• 최신 버전에서는 pipeline 키로 받도록 바뀌었다고 가정합니다.

만약 최신 버전에 맞춰 예시 코드를 봤는데, 내 프로젝트의 커넥터 버전이 낮아서 pipeline 키를 인식하지 못한다면, 아래처럼 작성해도:

df = (
    spark.read.format("mongodb")
    .option("uri", "mongodb://...")
    .option("pipeline", '[{ "$project": {...} }]')  # <- 커넥터가 모르는 옵션
    .load()
)

 

이 옵션은 무시될 뿐, 스파크가 “pipeline이라는 옵션은 지원되지 않습니다”라는 에러를 내주지 않습니다. 결과적으로 파이프라인이 적용되지 않은 채로 데이터를 읽게 됩니다(또는 스키마 충돌을 일으킬 수도 있고요).

이렇게 filtering하는 pipeline 옵션 (select (Projection)을 무시하고 전체 필드를 다 불러옴

위 예시는 pipeline옵션이 몽고 커넥터의 버전(mongodb spark connector10.1.1) 에 없는 옵션값이어서

제대로 select 기능이 동작하지 않고 전체 필드를 다 불러오는 것을 볼 수 있습니다.
(스파크 몽고 커넥터 option 구성 참고 : https://www.mongodb.com/ko-kr/docs/spark-connector/v10.1/batch-mode/batch-read-config/)

 

✔️좌) 제대로 몽고커넥터 버전에 맞는 option명시 ✔️우) 몽고커넥터 무시하고 pipeline으로 잘못된 옵션 명시

 

 

반대로, 옛날 코드에서 aggregation.pipeline라고 썼는데, 최신 커넥터는 이걸 사용하지 않고 pipeline만 지원한다면, 그 값 역시 무시됩니다. 이처럼 커넥터 버전이 바뀌면 옵션 이름이 변할 수 있고, 잘못된 옵션명을 넘기면 Spark는 별도 경고 없이 그대로 무시하는 경우가 대부분입니다.

 

3. 예외: 일부 DataSource는 에러나 경고를 줄 수도 있다

 

모든 커넥터가 “알 수 없는 옵션을 조용히 무시”하는 것은 아닙니다.
CSV(Spark 내장)처럼 일부 포맷은 특정 옵션이 잘못될 시 경고를 주거나, “필수 옵션이 빠졌다”며 에러를 낼 수도 있습니다.
다만, 이런 처리는 DataSource 구현체가 “어떤 옵션 목록을 검사할지” 결정하는 것이고, Spark Core 레벨에서 강제되는 것은 아닙니다.

 

4. 실제 현장에서 생기는 문제점

1. 오탈자 문제Spark가 이를 무시해버리면, 파일을 헤더 없이 읽어 들이고, 사용자는 왜 컬럼명이나 데이터가 깨지는지 한동안 찾아야 하는 상황이 생길 수 있습니다.
2. .option("heaer", "true") # 'header'를 오타로 입력
3. 버전 호환성 문제⭐️⭐️⭐️
   • “문서/블로그 예시 코드”에서는 pipeline 옵션을 쓰라고 했는데, 내가 사용하는 커넥터 버전이 aggregation.pipeline만 지원하면, 설정이 적용되지 않음.
   • 반대로 최신 버전이 pipeline로 바뀌었는데, 옛날 옵션 키를 그대로 쓰면 작동 안 함.
   • Spark 에러가 명확히 나오지 않으니, 사용자가 디버깅에 시간을 많이 쏟을 수 있습니다.

 

5. 요약 및 권장사항

• Spark의 .option(...)는 전역 옵션 전달 방식
  • Spark는 (키, 값)을 받아서 DataSource로 넘길 뿐, 정의되지 않은 키에 대해 에러를 내지 않습니다.
• 커넥터 버전마다 옵션 키가 달라질 수 있음
  • MongoDB Spark 커넥터 등에서는 pipeline, aggregation.pipeline, partitionerOptions.numPartitions 등 옵션 키가 버전에 따라 변경되기도 합니다.
• 권장:
  1. 공식 문서나 소스 코드를 확인해, 해당 버전에 맞는 옵션 키를 사용해야 합니다.
  2. 오탈자 없이 정확히 입력하도록 주의하세요(특히 header vs heaer 같은 실수).
  3. 로그나 코드에서 .option(...) 설정을 점검하고, 정말로 적용됐는지 explain이나 결과값으로 검증해보는 습관이 필요합니다.
     
     

⭐️요약 정리⭐️
✔️ “정의되지 않은 옵션 or 틀린 키”를 써도 Spark는 기본적으로 무시한다.
✔️ 이로 인해 “원하는 설정이 전혀 적용되지 않는” 문제가 발생할 수 있음.
✔️ 버전이 달라지면 옵션 키 이름도 달라질 수 있으므로, 반드시 버전에 맞는 공식 문서를 확인하자.

 

6. 같이 보면 좋은 내용

• MongoDB Spark Connector 문서
• Spark CSV/JSON/Parquet Options
• Spark DataFrameReader / DataFrameWriter .option() 사용 예시와 오탈자 관련 이슈

위 문서를 보며 정확한 옵션 키를 확인하자!!!!!!!!!!!!!!

 

---

 

이상으로 “왜 Spark는 옵션에 엉뚱한 키를 줘도 에러가 없나?” 및 MongoDB 커넥터 버전별 옵션 차이가 빚어내는 문제를 정리해보았습니다. 개발 시엔 작은 오타 하나로도 큰 혼란이 발생하기 쉽기 때문에, 버전을 확인하고 옵션을 정확히 맞춰주는 게 중요하다는 것을 깨달았다.🥲