PostgreSQL 01003 오류 원인과 해결 방법 완벽 가이드

01003
2026년 05월 28일 | DBMS Error 가이드

이 글에서 다루는 내용

01003 에러의 원인 분석, 해결 SQL, 예방 방법을 실무 관점에서 정리합니다.

01003 null value eliminated in set function 는?

PostgreSQL 에러 코드 01003은 WARNING: null value eliminated in set function 메시지로 출력되며, 엄밀히는 에러가 아닌 경고(WARNING) 입니다. SUM(), AVG(), COUNT(column), MAX(), MIN() 등의 집계 함수(set function)를 사용할 때, 대상 컬럼에 NULL 값이 포함되어 있고 해당 NULL이 계산에서 자동으로 제외될 때 발생합니다. SQL 표준에 따라 집계 함수는 NULL을 무시하고 동작하는 것이 정상이지만, 개발자나 운영자가 이 사실을 인지하지 못할 경우 데이터 정합성 문제로 이어질 수 있어 PostgreSQL이 경고를 통해 명시적으로 알려주는 것입니다.

주요 발생 원인

1. 집계 함수 대상 컬럼에 NULL 값이 존재하는 경우

가장 흔한 원인입니다. 테이블 설계 시 특정 컬럼에 NOT NULL 제약을 걸지 않아 NULL이 저장된 상태에서 AVG(), SUM() 등을 사용하면 해당 경고가 발생합니다. 예를 들어 주문 금액(order_amount) 컬럼에 일부 레코드가 NULL인 상태에서 평균을 구하면, NULL 행은 계산에서 제외되어 실제 평균값이 왜곡될 수 있습니다.

2. LEFT JOIN 또는 OUTER JOIN 사용 후 집계 처리

LEFT JOIN, RIGHT JOIN, FULL OUTER JOIN을 사용하면 매칭되지 않는 쪽의 컬럼 값이 NULL로 채워집니다. 이 상태에서 JOIN 결과를 집계하면, 의도하지 않은 NULL이 집계 함수에 전달되어 경고가 발생합니다. 조인 결과에 NULL이 포함됐다는 사실을 놓치기 쉽기 때문에 실무에서 특히 주의가 필요합니다.

3. 서브쿼리 또는 CASE 표현식에서 NULL 반환

서브쿼리나 CASE WHEN 구문에서 특정 조건에 맞지 않는 경우 명시적으로 NULL을 반환하거나, ELSE 절을 생략하여 묵시적으로 NULL이 반환되는 경우가 있습니다. 이 결과를 바로 집계 함수에 넘기게 되면 NULL이 제거되면서 경고가 발생하고, 집계 결과가 예상과 달라질 수 있습니다.

해결 방법

원인 1 해결: COALESCE 또는 NULLIF를 사용해 NULL을 기본값으로 치환

집계 전에 COALESCE()를 사용하여 NULL을 명시적인 기본값(0, 빈 문자열 등)으로 치환하면 경고를 제거하고 의도한 대로 계산할 수 있습니다.

-- 문제가 되는 쿼리 (order_amount에 NULL이 있을 경우 경고 발생)
SELECT AVG(order_amount) AS avg_amount
FROM orders;

-- 해결책 1: COALESCE로 NULL을 0으로 치환
SELECT AVG(COALESCE(order_amount, 0)) AS avg_amount
FROM orders;

-- 해결책 2: NULL 행 자체를 필터링 (NULL을 0으로 취급하지 않고 제외)
SELECT AVG(order_amount) AS avg_amount
FROM orders
WHERE order_amount IS NOT NULL;

-- 실제 NULL 개수를 사전에 확인하는 쿼리
SELECT
    COUNT(*) AS total_rows,
    COUNT(order_amount) AS non_null_rows,
    COUNT(*) - COUNT(order_amount) AS null_rows
FROM orders;

> 실무 팁: COUNT()와 COUNT(column) 의 차이를 항상 명심하세요. COUNT()는 NULL 포함 전체 행 수를, COUNT(column)은 NULL을 제외한 행 수를 반환합니다.

원인 2 해결: OUTER JOIN 결과에서 NULL 처리

-- 문제가 되는 쿼리 (LEFT JOIN으로 인해 NULL 발생)
SELECT
    c.customer_id,
    SUM(o.order_amount) AS total_amount
FROM customers c
LEFT JOIN orders o ON c.customer_id = o.customer_id
GROUP BY c.customer_id;

-- 해결책 1: COALESCE로 NULL인 금액을 0으로 치환
SELECT
    c.customer_id,
    SUM(COALESCE(o.order_amount, 0)) AS total_amount
FROM customers c
LEFT JOIN orders o ON c.customer_id = o.customer_id
GROUP BY c.customer_id;

-- 해결책 2: 주문이 없는 고객을 명시적으로 구분
SELECT
    c.customer_id,
    CASE
        WHEN COUNT(o.order_id) = 0 THEN 0
        ELSE SUM(o.order_amount)
    END AS total_amount,
    COUNT(o.order_id) AS order_count
FROM customers c
LEFT JOIN orders o ON c.customer_id = o.customer_id
GROUP BY c.customer_id;

원인 3 해결: CASE 표현식에서 ELSE 절 명시

-- 문제가 되는 쿼리 (ELSE 절 없이 NULL 묵시적 반환)
SELECT
    AVG(
        CASE
            WHEN product_category = 'ELECTRONICS' THEN sale_price
        END
    ) AS avg_electronics_price
FROM products;

-- 해결책: ELSE 절을 명시하여 NULL 반환 방지
SELECT
    AVG(
        CASE
            WHEN product_category = 'ELECTRONICS' THEN sale_price
            ELSE 0  -- 또는 업무 규칙에 맞는 기본값
        END
    ) AS avg_electronics_price
FROM products;

-- 더 나은 접근: 필터링 방식으로 특정 카테고리만 집계
SELECT
    AVG(sale_price) AS avg_electronics_price
FROM products
WHERE product_category = 'ELECTRONICS'
  AND sale_price IS NOT NULL;

-- FILTER 절 활용 (PostgreSQL 9.4+)
SELECT
    AVG(sale_price) FILTER (WHERE product_category = 'ELECTRONICS') AS avg_electronics_price,
    AVG(sale_price) FILTER (WHERE product_category = 'FURNITURE') AS avg_furniture_price
FROM products
WHERE sale_price IS NOT NULL;

경고 자체를 억제해야 하는 경우 (임시방편, 권장하지 않음)

-- 세션 단위로 경고 메시지를 억제 (근본적인 해결책이 아님)
SET client_min_messages = 'ERROR';

-- 특정 쿼리 실행
SELECT AVG(score) FROM exam_results;

-- 세션 복구
RESET client_min_messages;

> ⚠️ 주의: 경고 억제는 문제를 숨길 뿐 해결하지 않습니다. 운영 환경에서는 반드시 근본 원인을 파악하고 데이터 또는 쿼리를 수정하는 방식으로 대응하세요.

예방 방법

1. 테이블 설계 단계에서 NOT NULL 제약 조건 및 DEFAULT 값 적극 활용

집계 대상이 될 수치형 컬럼(금액, 수량, 점수 등)은 가능한 한 NOT NULL DEFAULT 0 제약을 부여하여 설계 단계에서 NULL 유입을 원천 차단합니다. 이미 운영 중인 테이블이라면 데이터를 정제한 뒤 제약 조건을 추가하는 마이그레이션 작업을 계획하는 것이 좋습니다.

-- 테이블 생성 시 NOT NULL 및 DEFAULT 설정
CREATE TABLE orders (
    order_id     SERIAL PRIMARY KEY,
    customer_id  INT NOT NULL,
    order_amount NUMERIC(12, 2) NOT NULL DEFAULT 0,
    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 기존 테이블에 NOT NULL 및 DEFAULT 추가 (데이터 정제 후)
UPDATE orders SET order_amount = 0 WHERE order_amount IS NULL;
ALTER TABLE orders ALTER COLUMN order_amount SET NOT NULL;
ALTER TABLE orders ALTER COLUMN order_amount SET DEFAULT 0;

2. 집계 쿼리 작성 시 NULL 검증 쿼리를 습관화

운영 쿼리를 작성하기 전, 대상 컬럼의 NULL 분포를 사전에 확인하는 습관을 들입니다. CI/CD 파이프라인이나 데이터 품질 체크 프로세스에 NULL 비율 모니터링 쿼리를 포함시키면 배포 전에 문제를 감지할 수 있습니다.

-- NULL 비율 점검 쿼리 (배포 전 데이터 품질 체크 용도)
SELECT
    column_name,
    COUNT(*) AS total,
    COUNT(column_name) AS non_null_count,
    COUNT(*) - COUNT(column_name) AS null_count,
    ROUND(
        (COUNT(*) - COUNT(column_name))::NUMERIC / NULLIF(COUNT(*), 0) * 100,
        2
    ) AS null_ratio_pct
FROM (
    SELECT order_amount AS column_name FROM orders
) sub;