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

22034
2026년 08월 21일 | DBMS Error 가이드

이 글에서 다루는 내용

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

22034 more than one sql json item 는?

PostgreSQL 에러 코드 22034는 more than one sql json item이라는 메시지와 함께 발생하며, SQL/JSON 경로 표현식(Path Expression)이 단일 값을 반환해야 하는 컨텍스트에서 둘 이상의 JSON 항목을 반환했을 때 트리거됩니다. 주로 JSON_VALUE(), JSON_QUERY() 등의 SQL/JSON 함수에서 경로 표현식이 여러 결과를 산출할 경우 발생합니다. PostgreSQL 16 이상에서 SQL 표준 JSON 함수들이 공식 지원되면서 이 에러를 접하는 DBA와 개발자가 늘어나고 있습니다.

주요 발생 원인

1. JSON_VALUE() 함수에서 배열 요소 전체를 반환하려는 경우

JSON_VALUE() 함수는 반드시 스칼라(단일) 값 하나만 반환해야 합니다. JSON 경로 표현식이 배열 내 여러 요소를 선택하거나, 와일드카드([])를 사용해 복수의 값을 추출하려 할 때 이 에러가 발생합니다. 예를 들어 $.items[].price처럼 배열의 모든 원소를 선택하는 경로를 JSON_VALUE()에 전달하면 즉시 에러가 발생합니다.

2. JSON_QUERY() 에서 WITH WRAPPER 없이 복수 결과를 처리하는 경우

JSON_QUERY() 함수도 기본적으로 단일 JSON 객체 또는 배열을 반환합니다. 경로 표현식이 복수의 독립적인 JSON 값을 반환하도록 작성되었으나, WITH ARRAY WRAPPER 옵션 없이 호출하면 에러가 발생합니다. 이 경우 여러 결과를 하나의 JSON 배열로 감싸주는 래퍼 옵션을 활용해야 합니다.

3. 중첩 JSON 구조에서 잘못된 경로 표현식을 사용하는 경우

복잡하게 중첩된 JSON 데이터에서 경로를 잘못 작성하면 의도치 않게 복수의 항목이 선택될 수 있습니다. 특히 .* 또는 [] 같은 와일드카드가 예상보다 넓은 범위의 데이터를 선택할 때 이 에러가 발생합니다. JSON 구조를 충분히 파악하지 않고 범용 와일드카드를 남용하는 것이 실무에서 가장 흔한 실수 중 하나입니다.

해결 방법

원인 1 해결: JSON_VALUE()에서 특정 인덱스로 접근

배열에서 단일 값을 가져올 때는 와일드카드 대신 명시적인 인덱스를 사용합니다.

-- 에러 발생 예제
SELECT JSON_VALUE(
    '{"items": [{"price": 100}, {"price": 200}]}'::json,
    '$.items[*].price'  -- 복수 값 반환 -> 에러!
);

-- 해결: 특정 인덱스 지정
SELECT JSON_VALUE(
    '{"items": [{"price": 100}, {"price": 200}]}'::json,
    '$.items[0].price'  -- 첫 번째 요소만 반환
);
-- 결과: 100

-- 해결: ERROR ON ERROR 대신 NULL ON ERROR로 안전하게 처리
SELECT JSON_VALUE(
    '{"items": [{"price": 100}, {"price": 200}]}'::json,
    '$.items[*].price'
    NULL ON ERROR  -- 에러 대신 NULL 반환
);

원인 2 해결: JSON_QUERY()에 WITH ARRAY WRAPPER 추가

복수의 결과가 필요한 경우 WITH ARRAY WRAPPER 옵션으로 결과를 배열로 묶습니다.

-- 에러 발생 예제
SELECT JSON_QUERY(
    '{"items": [{"price": 100}, {"price": 200}]}'::jsonb,
    '$.items[*].price'  -- 복수 결과 -> 에러!
);

-- 해결: WITH ARRAY WRAPPER 사용
SELECT JSON_QUERY(
    '{"items": [{"price": 100}, {"price": 200}]}'::jsonb,
    '$.items[*].price'
    WITH ARRAY WRAPPER  -- 결과를 [100, 200] 배열로 래핑
);
-- 결과: [100, 200]

-- WITH UNCONDITIONAL ARRAY WRAPPER: 단일 결과도 항상 배열로 반환
SELECT JSON_QUERY(
    '{"price": 100}'::jsonb,
    '$.price'
    WITH UNCONDITIONAL ARRAY WRAPPER
);
-- 결과: [100]

원인 3 해결: jsonb_path_query()로 복수 결과 처리

복수의 JSON 항목이 반드시 필요한 경우, SQL/JSON 함수 대신 jsonb_path_query()를 사용합니다.

-- 복수 결과를 행(row)으로 분리하여 처리
SELECT value
FROM jsonb_path_query(
    '{"items": [{"price": 100}, {"price": 200}, {"price": 300}]}'::jsonb,
    '$.items[*].price'
) AS value;
-- 결과:
-- 100
-- 200
-- 300

-- 집계 함수와 결합 사용 예
SELECT AVG(value::text::numeric) AS avg_price
FROM jsonb_path_query(
    '{"items": [{"price": 100}, {"price": 200}, {"price": 300}]}'::jsonb,
    '$.items[*].price'
) AS value;
-- 결과: 200

-- 실무 테이블 예제
CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    order_data JSONB NOT NULL
);

INSERT INTO orders (order_data) VALUES
('{"items": [{"name": "사과", "price": 1500}, {"name": "바나나", "price": 2000}]}'),
('{"items": [{"name": "딸기", "price": 3000}]}');

-- 각 주문의 모든 상품 가격 조회
SELECT
    o.id,
    item_price.value AS price
FROM orders o,
     jsonb_path_query(o.order_data, '$.items[*].price') AS item_price;

예방 방법

1. ON ERROR 절을 활용한 방어적 코딩 습관화

SQL/JSON 함수를 사용할 때는 항상 NULL ON ERROR 또는 DEFAULT ... ON ERROR 절을 명시하여 예기치 않은 복수 결과로 인한 런타임 에러를 방지하세요. 이 습관은 운영 환경에서 갑작스러운 서비스 중단을 막는 가장 효과적인 방법입니다.

-- 권장 패턴: ON ERROR 절 명시
SELECT JSON_VALUE(
    order_data,
    '$.total_price'
    DEFAULT -1 ON ERROR  -- 에러 시 -1 반환
) AS total_price
FROM orders;

2. JSON 경로 표현식을 배포 전에 반드시 검증

jsonb_path_query_array() 또는 jsonb_path_exists()를 활용해 경로 표현식이 실제 데이터에서 몇 개의 값을 반환하는지 미리 확인하는 테스트 쿼리를 작성하세요. 특히 와일드카드를 포함한 경로 표현식은 실제 프로덕션 데이터 샘플에 대해 반드시 검증 후 배포해야 합니다.

-- 경로가 반환하는 항목 수 확인
SELECT jsonb_array_length(
    jsonb_path_query_array(order_data, '$.items[*].price')
) AS item_count
FROM orders;