Deep Connector의 추출 코드를 검토하면서 작업을 가져오는 조건과 결과를 확정하는 조건을 나눠 읽었다. 작업을 처음 점유할 때의 행 잠금만으로는 나중에 돌아온 워커의 쓰기까지 막을 수 없기 때문이다. 결과를 확정할 때도 DB에 기록된 현재 소유자를 확인해야 한다.

아래 순서는 지연 상황을 설명하려고 만든 가정이며 실제 장애 회고가 아니다. 예제는 소유권 조건을 축약한 메모리 모델로, 실제 제품 코드나 다중 인스턴스 DB 실험을 실행한 결과와 구분한다.

임대 만료와 워커 종료의 차이​

워커 A가 문서 하나를 점유하고 추출을 시작했다고 하자. A가 임대(lease)를 갱신하지 못해 만료 시각을 넘기면 워커 B가 같은 작업을 다시 점유할 수 있다. 그동안 A의 추출 요청은 아직 실행 중일 수 있다.

이때 lease는 다른 워커가 작업을 인계받을 조건이지, A의 프로세스를 종료하는 명령이 아니다. B가 결과를 확정한 뒤 A가 돌아오더라도 A의 결과를 현재 결과로 받아들이지 않아야 한다. 여기서 소유권 펜싱은 현재 소유자가 아닌 워커의 DB 상태 변경을 거절하는 규칙을 뜻한다.

작업 점유와 결과 확정의 분리​

점유 함수인 claimOne()은 트랜잭션 안에서 후보 행에 pessimistic_write 잠금을 요청하고 skip_locked를 지정한다. 후보는 새로 발견한 문서, 재시도 시각이 된 문서, 추출 중이지만 lease가 만료된 문서다. PostgreSQL의 SKIP LOCKED는 즉시 잠글 수 없는 행을 건너뛰므로 여러 소비자가 큐 형태의 테이블에서 작업을 가져올 때 쓸 수 있다.

행을 선택한 뒤에는 조건부 UPDATE로 점유 가능 상태를 다시 확인한다. 정확히 한 행을 변경했을 때 새 소유자 토큰과 만료 시각을 기록하고 시도 횟수를 늘린 것으로 인정한다. 이 트랜잭션은 문서 다운로드나 추출이 끝날 때까지 유지되지 않는다.

완료 함수 complete()는 문서 ID만으로 갱신하지 않는다. 문서 ID, extraction_owner_token, 현재 상태 extracting이 모두 일치해야 결과 경로와 체크섬을 기록하고 상태를 indexed로 바꾼다. 갱신 함수 renew()와 실패 함수 fail()에도 같은 소유권 조건이 있다.

검토한 구현에서 소유자 토큰은 기본적으로 UUID이며, 크기를 비교하는 단조 증가 번호가 아니다. 저장된 토큰과 요청 토큰의 일치 여부로 소유자를 구분한다. 따라서 모든 외부 저장소가 이 토큰으로 오래된 쓰기를 거절한다고 해석해서는 안 된다.

만료 시각만으로 거절하지 않는 완료 조건​

complete()와 renew()의 조건에는 lease 만료 시각 비교가 없다. 만료됐더라도 아직 다른 워커가 재점유하지 않았고 상태와 토큰이 그대로라면 기존 워커의 완료나 갱신이 허용될 수 있다. 반대로 B가 재점유해 토큰이 바뀌었다면 A는 예전 토큰으로 완료할 수 없다.

이 차이를 생략하면 “만료된 워커의 모든 요청은 거절된다”라는 잘못된 설명이 된다. 이 구현에서 만료 시각은 재점유 후보를 정하고, 결과 갱신 시점의 토큰과 상태는 완료 권한을 정한다.

순서를 고정한 설명용 모델​

다음 Python 코드는 DB 한 행을 사전으로 표현한다. 최초 점유와 만료 후 재점유, 완료 시 토큰과 상태 비교만 남겼으며 재시도, 트랜잭션, 타이머, 파일 쓰기는 구현하지 않았다. 함수 호출을 순서대로 실행하므로 실제 동시성이나 DB 잠금 동작을 검증하는 코드가 아니다.

def new_row():
    return {"status": "discovered", "owner": None,
            "expires": None, "result": None}


def claim(row, owner, now, lease=10):
    eligible = row["status"] == "discovered" or (
        row["status"] == "extracting" and row["expires"] <= now
    )
    if not eligible:
        return False
    row.update(status="extracting", owner=owner, expires=now + lease)
    return True


def complete(row, owner, result):
    if row["status"] != "extracting" or row["owner"] != owner:
        return False
    row.update(status="indexed", owner=None, expires=None, result=result)
    return True


row = new_row()
assert claim(row, "A", now=0)
assert not claim(row, "B", now=9)
assert claim(row, "B", now=10)
stale_during_b = complete(row, "A", "A-result")
assert not stale_during_b
assert row["owner"] == "B" and row["result"] is None
winner = complete(row, "B", "B-result")
late_after_b = complete(row, "A", "A-result")
assert winner and not late_after_b
assert row["result"] == "B-result"
print("A completion while B owns:", stale_during_b)
print("B completion:", winner)
print("A completion after B finishes:", late_after_b)
print("Stored result:", row["result"])

row = new_row()
assert claim(row, "A", now=0)
now = 11
assert now > row["expires"]
expired_without_reclaim = complete(row, "A", "A-result")
assert expired_without_reclaim
print("Expired A without reclaim:", expired_without_reclaim)

코드를 lease_model.py로 저장하고 python3 lease_model.py로 실행하면 된다. Python 3.9.6에서 위 코드 전체를 실행해 모든 assertion이 통과했으며 표준 출력은 다음과 같았다.

A completion while B owns: False
B completion: True
A completion after B finishes: False
Stored result: B-result
Expired A without reclaim: True

B가 추출 중일 때 A를 거절한 결과는 토큰 비교가 필요하다는 점을 보여준다. B가 완료한 뒤에는 토큰뿐 아니라 상태도 달라져 A의 완료 조건이 성립하지 않는다. 마지막 줄은 만료만으로 완료를 거절하지 않는 구현상의 차이를 확인한 결과다.

타이머로 취소되지 않는 외부 작업​

실제 워커는 다운로드, 추출, 미러 파일 쓰기를 각각 withLease()로 감싼다. 각 단계 시작 전에 한 번 갱신하고 이후에는 Math.max(100, Math.floor(leaseMs / 3)) 밀리초를 지연값으로 타이머를 예약한다. 이 값은 정확한 실행 간격을 보장하지 않으며 Node.js 공식 문서도 타이머 콜백의 정확한 실행 시각을 보장하지 않는다고 명시한다.

주기 갱신이 실패하거나 예외를 던지면 lost 플래그를 설정한다. 다만 이미 시작한 work()를 즉시 취소하지는 않는다. 외부 작업이 반환되면 진행 중인 갱신을 기다린 뒤 소유권 상실을 오류로 처리한다.

주기 갱신은 작업 중 lease를 연장하지만, 늦은 완료를 거절하는 최종 조건은 DB UPDATE에 남아 있어야 한다. 워커가 갱신에 성공한 직후라도 다음 쓰기까지 소유권이 유지된다고 가정할 수 없다.

DB 결과와 파일 쓰기의 서로 다른 보호 범위​

DB가 A의 완료를 거절해도 A가 이미 수행한 파일 쓰기까지 되돌아가지는 않는다. 검토한 워커는 미러 파일을 쓸 때 소유자 토큰을 generation으로 넘기며, 미러 구현은 세대별 파일 경로를 사용한다. A와 B가 같은 결과 파일명을 공유하지 않도록 나누고 DB에는 완료 조건을 통과한 결과의 경로를 기록하는 구조다.

고아 파일 정리도 늦은 워커 자신의 기억만으로 결정하지 않는다. cleanupOrphansFenced()는 행 잠금을 유지한 채 현재 DB 행을 정리 콜백에 전달한다. 워커는 DB가 가리키는 결과 경로와 현재 추출 중인 소유자의 경로를 보존 대상으로 지정한다.

여기에는 주의할 구현 세부도 있다. processOne()은 complete()가 반환한 불리언을 분기 조건으로 사용하지 않고 정리 단계로 이어간다. 따라서 processOne()의 true를 해당 워커의 결과가 DB에 채택됐다는 뜻으로 읽으면 안 된다.

세대별 경로와 정리 시 행 잠금이 있다고 해서 파일 시스템 작업 전체가 DB 트랜잭션에 포함되는 것은 아니다. 오래된 워커가 뒤늦게 파일을 쓰거나 파일 정리와 쓰기가 엇갈리는 상황은 별도 검증이 필요하다. lease만으로 외부 작업의 정확히 한 번 실행을 보장한다고 말할 수 없는 이유다.

이번 검토의 근거와 남은 검증​

제품의 lease 저장소, 워커, 미러 구현과 관련 단위 테스트 소스를 읽고 앞의 설명용 모델을 실행했다. 저장소 테스트는 가짜 쿼리 빌더로 잠금 설정 호출과 소유권 조건을 확인한다. 워커 테스트에는 A를 멈춘 사이 B가 완료한 뒤 A를 재개하고, B의 결과와 실행 중인 C의 파일을 보존하는 시나리오도 있다.

이 테스트의 저장소와 파일은 대역이며 실제 DB나 파일 시스템이 아니다. 이번 작성 환경에는 제품의 Jest 실행 파일이 없어 해당 단위 테스트는 실행하지 않았다. 따라서 직접 실행해 확인한 결과는 앞의 Python 모델에 한정된다.

실제 검증에서는 별도 DB 연결로 점유 경쟁을 만들고, 오래 멈춘 워커를 재개한 뒤 완료 UPDATE의 변경 행 수와 저장된 결과 경로를 함께 확인해야 한다. 공유 파일 시스템에서 쓰기와 정리가 겹칠 때 남는 파일도 확인 대상이다. 이 글은 그 실험의 성공을 주장하지 않는다.

작업을 다시 맡기는 조건과 결과를 받아들이는 조건은 분리해 확인해야 한다. lease 만료는 재점유를 허용하고, 현재 소유자와 상태를 확인하는 UPDATE는 늦게 돌아온 결과의 채택 여부를 결정한다.

References​

• PostgreSQL SELECT의 잠금 절
• Node.js setTimeout의 실행 시각

이 글은 전환 영향검토서와 성능 비교 쿼리 샘플을 함께 읽고 재구성한 기록이다. 자료에 남은 파일 규모 계측과 정적 검토, 용량 추정, 비교 시험 계획을 구분했다. Oracle 26ai와 19c의 비교 부하 시험 결과나 최종 운영 전환 승인을 보고하는 글은 아니다. 고객사, 실제 계정과 스키마 식별자, 내부 작업 날짜 및 배포 정보는 제외했다.

버전 선택과 전환 승인의 분리​

영향검토서는 외부 요구가 없다면 26ai를 유지하는 편이 변경 위험이 작다고 판단했다. 이미 26ai를 기준으로 구현한 시스템을 바꿀 때의 회귀 위험을 평가한 것이지, Oracle 19c 자체가 불안정하다는 결론은 아니었다. 고객의 요구사항이 바뀌면 검토의 초점도 달라진다. 19c에서 필요한 기능을 유지하려면 무엇을 고쳐야 하는지, 어떤 시험을 통과해야 운영에 사용할 수 있는지를 정해야 한다.

기존 26ai DDL에는 빈 스키마 적용과 내부 일관성 검증을 통과한 기록이 있었다. 그 기록은 19c 호환성이나 실제 부하에서의 응답시간을 보장하지 않는다. 요구사항으로 목표 버전이 정해지는 것과 시험 결과로 전환을 승인하는 것은 별도 판단이다.

계측한 파일 크기와 아직 모르는 DB 성능​

두 자료를 읽을 때 먼저 구분해야 할 것은 숫자의 출처였다.

파일 계측에서는 고유 상품 하나가 매핑 한 행과 같지 않다는 점이 드러났다. 문서가 검색용 unit으로 나뉘고 metadata가 unit마다 복제된다면 DB의 물리 행 수는 그만큼 늘어난다. 따라서 원본 건수만으로 용량이나 응답시간을 판단할 수 없다.

용량 추정에는 상품 구성과 문서 재사용률이 유지된다는 가정이 들어갔다. unit별 복제 시나리오도 전체 metadata를 각 unit에 저장한다는 보수적 가정이었다. 이 글에서는 고객 데이터의 정확한 건수와 용량을 공개하지 않으며, 다른 숫자로 바꿔 실측 예시처럼 제시하지도 않는다.

UTF-8 JSON 원문 크기를 UTF-16LE로 환산한 값 역시 실제 Oracle CLOB segment 크기는 아니다. 본문 CLOB, 리비전, 인덱스, 로그와 블록 여유 공간은 별도로 고려해야 한다. 자료에 따르면 파일을 직렬화해 크기를 재는 실험은 수행됐지만, 그 결과가 버전별 쿼리 속도를 뜻하지는 않는다.

JSON 저장 타입 변경과 애플리케이션 호환성​

이번 비교 대상은 Oracle RDB의 JSON 저장과 CLOB 본문 검색이다. 이 구성에서 임베딩 저장과 벡터 검색은 Qdrant가 담당하므로 Oracle 벡터 기능의 버전 비교는 범위에서 제외했다.

Oracle 26ai의 네이티브 JSON 타입은 OSON 바이너리 형식을 사용해 텍스트 JSON의 반복 파싱을 피한다. 19c 전환 기준안은 JSON을 CLOB에 저장하고 IS JSON 제약을 적용하는 방식이었다. Oracle 공식 문서는 LOB JSON 저장에 BLOB을 권장하지만, 영향검토서는 기존 CLOB 처리 코드의 재사용을 고려해 CLOB을 초기 후보로 두고 BLOB은 후속 비교 대상으로 남겼다. CLOB이 가장 빠르다고 확인해서 선택한 안은 아니었다.

변경 범위를 셀 때도 기준을 구분해야 했다. 검토 대상 DDL에는 JSON 컬럼이 29개였고, 이후 애플리케이션 코드에서 확인한 범위는 18개 테이블의 32개 컬럼이었다. 두 숫자는 서로 다른 기준의 목록이며, 변경 명세와 회귀 시험 대상은 실제 전환할 코드에 맞춰 다시 대조해야 한다.

DDL만 바꾸면 ORM의 타입 매핑이나 기동 시 보정 DDL에서 네이티브 JSON 정의가 다시 사용될 수 있다. 쓰기 직렬화, 읽기 역직렬화, 빈 객체와 빈 배열의 기본값, SQL NULL과 JSON null의 의미를 함께 확인해야 한다. 특히 RETURNING ... INTO로 CLOB을 돌려받는 경로는 자료에서도 별도 실측이 필요한 항목이었다. 쿼리 샘플은 이 호환성 확인용 INSERT를 일반 저장 경로와 구분해 제시했다.

grep 검색에서 나눠 볼 비용​

문서 grep은 metadata의 JSON 조건과 본문 CLOB의 정규식 검색을 함께 사용한다. 본문은 두 버전 모두 CLOB이고, 비교에서 주의할 변화는 metadata 저장 형식과 JSON 조건의 처리 비용이다. 반환 행 수가 적어도 조건을 평가한 후보 행 수까지 적다는 뜻은 아니다.

JSON 필터와 정규식의 비용을 고정된 배수로 곱해 응답시간을 예측해서는 안 된다. 실제 비용은 후보 행 수, 필터 선택도, 선택된 인덱스와 실행계획에 따라 확인해야 한다. 영향검토서가 인용한 벤더 벤치마크의 배수도 이 시스템의 26ai 대비 19c 성능 저하율로 옮겨 쓸 수 없다.

쿼리 샘플에는 JSON 조건이 없는 grep 대조군도 포함됐다. 다만 제시된 SQL끼리는 조인과 반환 컬럼에도 차이가 있어, 시간 차이를 전부 JSON 파싱 비용으로 해석하기 어렵다. 파싱 영향을 더 좁혀 비교하려면 조인, 반환 컬럼, 정렬과 바인드 조건을 맞추고 실제 스캔 행 수도 함께 기록해야 한다. 이는 샘플을 실행하기 전에 보완할 실험 조건이지, 파싱 병목을 확인한 결과가 아니다.

실제 저장 경로를 닮은 비교 시험​

성능 비교 쿼리 샘플에서 중요한 수정은 부분 갱신 SQL을 실제 저장 방식에 맞춘 것이었다. 애플리케이션은 최종 metadata 객체를 만든 뒤 전체 값을 다시 저장했으므로, JSON_MERGEPATCH만 비교하면 다른 동작을 시험하게 된다. 샘플은 이 부분 갱신을 제외하고 metadata 전체 저장과 본문을 함께 갱신하는 경로를 구분했다.

문서를 특정하지 않는 조회도 컬렉션 조건은 유지하도록 설계했다. 실제 API와 다른 전체 테이블 조회로 부하를 키우지 않기 위해서다. 컬렉션 범위 Bulk UPDATE는 실제 서비스 경로가 아닌 비교 전용 SQL이며, 성능시험 전용 DB에서 실행하고 매회 롤백하는 조건이다. 커밋 비용을 재는 시험은 운영 데이터가 없는 별도 시험 스키마에서 수행해야 한다.

500행 배치는 애플리케이션이 ORM에 전달하는 저장 단위를 반영한다. 시험 도구의 array binding이나 executemany가 실제 ORM의 SQL 생성과 네트워크 왕복을 그대로 재현한다는 뜻은 아니다. DB 단위 시험 뒤에 실제 드라이버와 ORM을 거치는 요청도 측정해야 한다.

인덱스 기준선과 최적화안의 분리​

DDL에 JSON Search Index가 없다는 사실만으로 실제 DB에도 없다고 단정할 수 없었다. 애플리케이션의 기동 보정 로직이 인덱스 생성을 시도하고 실패하면 일반 JSON 조건 조회로 폴백했기 때문이다. 시험 전에 실제 인덱스의 존재와 상태를 확인해야 하는 이유다.

먼저 같은 인덱스 조건에서 버전별 기준선을 측정하고, 함수 기반 인덱스를 추가한 최적화안은 별도 결과로 기록하도록 설계했다. 한쪽에만 인덱스를 추가하고 버전 차이라고 보고하면 개선 원인을 구분할 수 없다. 고정 JSON 경로는 함수 기반 인덱스의 후보가 되지만, 임의 metadata 키 전체를 미리 같은 방식으로 인덱싱하기는 어렵다. Oracle 공식 문서도 인덱스 이름이 실제 실행계획에 나타나는지 확인하도록 안내한다.

검색 인덱스는 읽기 지연만으로 평가할 수 없다. 동기화 방식에 따른 쓰기와 커밋 비용, 갱신한 데이터가 검색에 반영되는 지연도 함께 비교해야 한다.

DB 실행시간 이후까지 이어지는 측정​

시험 계획은 동일 데이터 스냅샷과 하드웨어, 문자셋, 통계, 커넥션 풀 및 동시성을 맞추는 것을 전제로 했다. 쿼리 샘플은 각 케이스를 3~5회 warm-up한 뒤 최소 30회 측정하고 평균과 P50, P95, P99를 기록하도록 제안했다. 이 반복 횟수는 실행 기록이 아니라 계획이며, 특히 P99를 안정적으로 판단하려면 충분한 표본과 반복 부하를 추가로 확보해야 한다.

측정은 DB가 첫 결과를 돌려준 시점에서 끝나지 않는다. CLOB을 끝까지 읽고 JSON을 역직렬화한 뒤 응답을 만들 때까지의 시간과 커넥션 점유시간을 기록해야 한다. DB CPU와 읽기량, 반환 바이트, 애플리케이션 CPU와 메모리를 함께 보면 지연이 늘어난 구간을 좁힐 수 있다.

영향검토서에는 읽기 API P95 증가를 26ai 대비 20% 이내로 제한하고, 검색 API P99 증가는 30% 이내로 제한하는 초기 제안이 있었다. 업로드와 파싱 처리량은 26ai의 90% 이상을 제안했다. 이 수치는 고객과 합의한 SLA도, 시험을 통과한 결과도 아니다. 실제 승인에는 성능 기준 합의와 함께 기능 정합성, 검색 최신성, 삭제 시 잠금, 이관시간과 롤백 검증이 필요하다.

개발 완료 이후의 전환 판단​

영향검토서는 개발 공수를 9~15영업일로 산정했지만, 전체 성능 시험과 운영 전환 리허설, DBA 반입 및 컷오버 일정은 별도로 분리했다. 개발 범위에 일부 실측 확인이 포함돼 있어도 전체 전환 승인에 필요한 검증을 대신하지는 않는다.

이관 계획의 expdp VERSION=19도 실행 성공을 뜻하지 않는다. 자료는 네이티브 JSON 컬럼 처리 여부를 시험 이관으로 확인하고, 필요하면 별도 직렬화 경로를 검토하도록 남겼다. 롤백 역시 접속 대상을 원래 DB로 되돌리는 것으로 끝나지 않는다. 19c에서 새로 발생한 쓰기를 어떻게 원본에 반영할지 정하지 않으면 복귀 과정에서 데이터가 유실될 수 있다.

이번 검토에서 확보한 것은 전환 성공의 증명이 아니라, 바뀐 요구사항에 맞춰 확인할 변경 범위와 시험 조건이었다. 파일 계측은 데이터 구조를 설명하고, 용량 추정은 준비할 시험 규모를 정하는 데 쓰이며, 비교 쿼리는 아직 모르는 성능을 확인하는 수단이다. 19c 채택 요구를 실제 운영 승인으로 이어가려면 그 사이에 남은 호환성, 부하, 이관과 복구 시험 결과가 필요하다.

References​

• Oracle 26ai JSON Data Type
• Oracle 19c Considerations When Using LOB Storage for JSON Data
• Oracle 19c Indexes for JSON Data

DeepConnector의 파일 검색은 사용자 입력과 사전 확장어를 함께 검색하되 점수는 구분한다. 직접 입력한 단어의 일치에는 큰 가중치를 주고, 사전이 보탠 별칭의 일치에는 작은 가중치를 준다. 동의어로 검색 범위를 넓히면서도 원래 검색어를 우선하려는 설계다.

첫 상황은 설계를 설명하기 위한 가정이며 실제 고객 장애가 아니다. 아래 문서와 검색어도 설명용으로 만들었다. 검증에는 특정 구현 스냅샷에서 추출한 실제 스니펫 조립 코드를 사용했고, 검색 서버나 사전 서비스 전체를 실행한 것은 아니다.

검색할 단어와 점수를 매길 단어의 구분​

설명용 문서 코드 SETUP01에 사전이 설치 안내, 설치 설명서, 셋업 가이드를 연결한다고 가정했다. 코드만 검색하면 코드를 적지 않은 안내문은 찾지 못할 수 있다. 별칭도 함께 검색하면 그런 문서를 찾을 여지가 생긴다.

문제는 검색할 단어를 합치는 순간 그 단어의 출처를 잊는 데 있다. 모두 같은 무게로 세면 사용자가 입력한 코드 하나보다 별칭 여러 개가 더 높은 점수를 받을 수 있다. 그래서 파일 검색 서비스는 합쳐진 검색어 목록과 별도로, 사용자가 입력하지 않은 확장어 집합을 유지한다.

// 제품의 검색어 분리 로직을 옮긴 설명용 코드
const searchTerms = [...new Set([...userTerms, ...expandedTerms])];
const expansionTerms = new Set(
  expandedTerms.filter(term => !userTerms.includes(term)),
);

searchTerms는 실제 문자열 검색에 넘길 목록이다. expansionTerms는 일치한 단어에 확장어 가중치를 적용할지 판단할 때 쓴다. 사전이 사용자 입력과 똑같은 문자열을 반환해도 검색 목록에는 한 번만 남고, 확장 전용 집합에서는 빠진다. 직접 입력한 단어가 사전에도 있다는 이유로 가중치가 낮아지지 않는 구조다.

여기서 중복 제거는 문자열 값의 비교다. Set이 의미가 비슷한 단어를 알아서 합쳐 주는 것은 아니며, 이 코드가 대소문자나 형태소까지 정규화하는 것도 아니다.

원래 검색어에 더 큰 가중치​

스니펫은 검색 결과에서 본문 일부를 잘라 보여주는 단위다. SnippetAssembler는 스니펫에 일치한 단어를 중복 없이 모은 뒤 사용자 입력과 확장 전용 일치로 나눠 lexicalScore를 계산한다. 같은 단어의 반복 등장 횟수를 그대로 사용자 일치 개수로 세지는 않는다.

확장어 상한은 MAX_EXPANSION_TERMS = 32이고, 확장어 하나의 가중치는 1 / (MAX_EXPANSION_TERMS + 1)이다. 사용자 일치에는 단어당 1을 더한다. 실제 점수식에는 하이라이트 개수에 따른 보정도 포함된다.

사용자 일치 개수
+ 확장 전용 일치 개수 × 확장어 가중치
+ (하이라이트 개수 / 100) × 확장어 가중치

확장어 일치 항만 보면 상한까지 채워도 사용자 일치 하나보다 작다. 다만 실제 점수에는 하이라이트 보정이 더해지므로, 이 비교만으로 모든 입력에서 순위가 보장된다고 결론 내리면 안 된다. 반복 일치나 하이라이트가 많은 경우까지 보장하려면 별도의 경계 검증이 필요하다.

파일 검색 결과는 lexicalScore 내림차순으로 정렬한다. 점수가 같으면 priority 오름차순, 문서 날짜 내림차순, fileId 사전순으로 비교한다. 이 글의 점수는 파일 검색의 스니펫 점수이며 벡터 검색이나 모든 검색 모드의 통합 순위를 뜻하지 않는다.

실제 조립 코드로 확인한 순위​

실행 예시에서는 검색 엔진이 반환할 일치 위치를 직접 만들고 실제 SnippetAssembler.assemble()에 넣었다. 문서마다 명시적인 본문 구간을 지정해 일치 항목들이 한 스니펫으로 묶이도록 했다. 사전 확장 결과도 고정했으므로, 이 실행이 검증하는 것은 동의어의 적절성이나 검색 엔진의 탐지 능력이 아니라 일치 이후의 점수 계산이다.

실행 결과에서 문서 A의 점수가 문서 B보다 높았다. 점수는 소수점 아래 여섯 자리로 반올림했다.

A  1.000303
B  0.091818

확장어를 상한인 32개까지 채운 별도 입력도 확인했다. 서로 겹치지 않는 확장어가 한 번씩 일치하는 스니펫의 점수는 0.979394였고, 사용자 입력 하나가 일치한 A보다 낮았다. 두 비교는 실제 조립 코드로 실행한 결과이지, 사용자 만족도나 검색 정확도를 측정한 수치가 아니다.

저장소의 회귀 테스트도 사용자 입력 일치 문서를 별칭만 일치하는 문서보다 먼저 반환하는지 확인하도록 작성돼 있다. 이번 검증에서는 그 테스트의 코드와 서비스 연결을 읽고, 조립 코드를 분리 실행했다. 회귀 테스트 전체나 실제 ripgrep 프로세스까지 실행한 것으로 해석해서는 안 된다.

사전이 입력 제한을 바꾸지 않도록​

확장어를 추가하는 시점도 중요하다. 파일 검색 서비스는 사용자 입력을 먼저 검증한 뒤 사전 확장을 적용한다. 사용자가 보낼 수 있는 검색어는 최대 16개이며 이 상한에 사전 확장어는 포함하지 않는다.

사용자 입력 16개에 확장어 2개가 붙는다면 검색기에 넘길 목록은 중복이 없을 때 18개가 된다. 반대로 사용자가 처음부터 17개를 보내면 여전히 SEARCH_INVALID_QUERY로 거부한다. 사전을 켰다고 사용자가 입력할 수 있는 단어 수가 줄어서도, 입력 제한이 느슨해져서도 안 된다.

확장 실패도 원래 검색과 구분한다. 확장 서비스는 분석기나 사전 조회 실패를 빈 확장어 목록과 사유로 반환하는 계약을 갖고 있다. 파일 검색은 그 결과를 받으면 원래 검색어로 계속 진행한다. 파일 검색 호출부가 임의의 예외를 모두 삼키는 방식은 아니므로, 이 동작을 검색 중 어떤 오류가 나도 성공한다는 뜻으로 넓혀 읽으면 안 된다.

더 찾는 기능과 먼저 보여줄 기준​

동의어 사전은 사용자가 입력하지 않은 표현을 검색에 보탠다. 그만큼 결과를 정렬할 때는 직접 입력한 단어와 사전이 추가한 단어를 구분할 필요가 있다.

DeepConnector의 파일 검색에서는 그 구분이 확장 전용 집합과 스니펫 가중치로 이어진다. 사전의 단어 수만 늘리는 대신, 원래 검색어의 우선순위와 사용자 입력 상한, 확장이 없어도 계속할 수 있는 검색 경로를 함께 검토해야 한다.

References​

• MDN의 JavaScript Set 문서

Deep Connector는 루트 중복을 PostgreSQL의 부분 유니크 인덱스와 Oracle의 함수 기반 유니크 인덱스로 막는다. 인덱스가 보장하는 것은 최대 하나다. 루트를 생성하는 작업과 인덱스를 설치하는 작업까지 있어야 제품이 요구하는 상태를 만들 수 있다.

이 글은 구현 코드와 공식 문서를 대조한 설계 설명이다. SQL은 식별자와 구조를 단순화한 개념 예시이며, 글 작성 과정에서 PostgreSQL이나 Oracle에 실행한 실험 결과가 아니다.

루트 식별과 중복 방지의 구분​

루트는 depth = 0인 폴더다. 엔티티의 교차 컬럼 CHECK는 루트의 parent_id가 NULL이어야 하고, 사용자 폴더는 깊이가 1부터 3까지이며 부모 값이 있어야 한다고 정한다. workspace_id와 depth에는 NOT NULL이 선언돼 있다.

이 조건만으로 루트 중복을 막지는 못한다. 같은 워크스페이스에 depth = 0, parent_id = NULL인 행을 추가해도 각 행은 CHECK를 만족하기 때문이다. 반대로 workspace_id 전체에 유니크를 걸면 사용자 폴더까지 워크스페이스당 하나로 제한된다.

필요한 조건은 루트 행만 골라서 workspace_id의 중복을 금지하는 것이다.

PostgreSQL의 부분 유니크 인덱스​

PostgreSQL의 부분 인덱스는 조건에 맞는 행만 인덱스에 포함한다. 여기에 UNIQUE를 붙이면 그 행들 사이에서만 중복을 막는다.

CREATE UNIQUE INDEX uq_folder_root
ON folder (workspace_id)
WHERE depth = 0;

folder는 설명용 테이블 이름이며, workspace_id가 NOT NULL이라는 전제다. 같은 워크스페이스의 루트 행은 동일한 키를 사용하므로 중복될 수 없고, depth > 0인 폴더는 이 인덱스의 제한을 받지 않는다. 다른 워크스페이스의 루트는 키가 다르므로 함께 존재할 수 있다.

실제 PostgreSQL 마이그레이션은 기존 루트 인덱스를 삭제하고, workspace_id에 WHERE depth = 0 조건을 붙인 부분 유니크 인덱스를 만든 뒤, 루트 표시용 중복 컬럼을 제거한다. 이 마이그레이션 자체가 없는 루트를 생성하는 것은 아니다.

Oracle의 함수 기반 유니크 인덱스​

Oracle 구현은 같은 중복 방지 조건을 표현식으로 옮긴다.

CREATE UNIQUE INDEX uq_folder_root
ON folder (
  CASE WHEN depth = 0 THEN workspace_id END
);

루트 행에서는 CASE가 workspace_id를 반환하고, 나머지 행에서는 NULL을 반환한다. Oracle의 일반 B-tree 인덱스는 키 전체가 NULL인 행을 저장하지 않는다. 이 예시는 표현식 하나만 인덱스 키로 쓰므로 루트가 아닌 행은 인덱스에서 빠진다.

결과적으로 루트 행끼리만 워크스페이스 키를 비교한다. 여기서도 workspace_id의 NOT NULL이 중요하다. 루트의 워크스페이스 값까지 NULL을 허용하면 그 행도 키가 없는 행으로 빠져 중복 방지 대상에서 제외된다.

두 SQL은 같은 업무 규칙을 표현하지만, 설치 과정까지 같은 것은 아니다.

최초 테이블 생성 뒤의 인덱스 설치​

Oracle 구현은 기존 스키마를 정리하는 시작 업그레이드와 루트 인덱스 생성을 나눈다. 시작 업그레이드는 예전 루트 표시 컬럼을 정리하고, 없는 루트를 시드하며, 깊이와 부모의 CHECK를 맞춘다. 루트의 함수 기반 유니크 인덱스 생성은 별도 부트스트랩 서비스가 맡는다.

이 구분은 빈 스키마를 처음 만드는 경로에서 필요하다. 명시적으로 동기화를 요청한 빈 Oracle 스키마에서는 TypeORM의 synchronize를 허용하고 시작 업그레이드는 건너뛴다. 시작 업그레이드가 먼저 테이블을 만들면 빈 스키마라는 전제를 바꿔 버리기 때문이다.

그래서 인덱스를 시작 업그레이드에만 넣으면 최초 동기화 경로에서 빠질 수 있다. 구현은 OnApplicationBootstrap에서 테이블 존재 여부를 확인한 뒤 인덱스를 생성하도록 배치한다. NestJS의 이 훅은 모든 모듈이 초기화된 뒤, 연결을 수신하기 전에 실행된다.

다만 테이블 존재 확인은 스키마 전체 검증이 아니다. 테이블이 없으면 이 서비스는 인덱스 생성도 건너뛴다.

재기동 허용과 인덱스 검증의 차이​

부트스트랩 서비스는 생성 중 ORA-00955 또는 ORA-01408을 받으면 오류를 다시 던지지 않는다. 공식 오류 설명에서 ORA-00955는 이미 사용 중인 객체 이름, ORA-01408은 이미 인덱스가 있는 컬럼 목록을 뜻한다.

이 처리는 재기동 때 이미 있는 인덱스를 다시 만들려는 시도를 허용하지만, 원하는 인덱스가 있다는 증거는 아니다. 서비스는 이후 카탈로그를 조회해 인덱스의 표현식이나 유니크 속성을 다시 검사하지 않는다. 특히 같은 이름이 남아 있다는 사실만으로 새 루트 조건과 일치한다고 판단할 수 없다.

기존 중복 데이터를 자동으로 정리하는 코드도 이 서비스에는 없다. 따라서 “재실행해도 일부 중복 생성 오류를 무시한다”와 “어떤 기존 스키마에서도 올바른 인덱스로 복구한다”는 구분해야 한다.

외부 관리 스키마의 책임​

DBA가 스키마를 관리하고 애플리케이션은 데이터만 읽고 쓰는 배포라면 인덱스 설치도 스키마 관리 절차에 포함해야 한다. Oracle 루트 인덱스 서비스는 외부 관리로 판정되면 카탈로그 조회와 인덱스 생성을 건너뛴다. 이때 애플리케이션이 만들지 않는다는 이유로 인덱스가 불필요해지는 것은 아니다.

서비스가 사용하는 USER_TABLES는 현재 사용자가 소유한 테이블을 보여준다. 다른 계정의 테이블을 읽을 권한과 그 테이블을 소유한다는 사실은 다르므로, 조회 결과가 없다는 이유만으로 생성에 나서면 안 된다.

외부 관리 설정을 모든 시작 작업의 차단 스위치로 해석하는 것도 위험하다. 확인한 코드에서는 TYPEORM_SYNCHRONIZE=true를 명시하고 테이블 수 조회가 성공하면, 테이블이 있는 경우 시작 업그레이드 플래그를 다시 켜는 분기가 있다. 루트 인덱스 서비스의 외부 관리 가드는 그대로지만, 별도 시작 업그레이드의 DDL과 DML까지 무조건 제외된다고 말할 수는 없다.

외부 관리 배포에서는 동기화 설정과 시작 업그레이드 실행 여부를 함께 확인하고, 담당 관리 절차에서 루트 인덱스의 정의를 검증해야 한다.

최대 하나와 최소 하나의 별도 검증​

유니크 인덱스는 루트가 없는 상태를 위반으로 보지 않는다. 없는 루트를 채우는 시드나 생성 로직이 따로 필요하고, 생성 시점에 존재했다는 사실만으로 이후에도 루트가 항상 남는다고 보장할 수는 없다.

배포 검증에서는 올바른 인덱스가 설치됐는지 확인한 뒤, 루트가 없는 워크스페이스도 별도로 조회해야 한다. 중복 루트 입력과 일반 폴더 입력, 루트 부재 상태를 나눠 확인하는 것은 이 규칙을 검증하기 위한 제안이며, 여기서 실행한 테스트 목록은 아니다.

워크스페이스 루트 하나라는 제품 규칙에는 중복 방지, 루트 생성, 스키마 설치 책임이 함께 들어 있다. SQL 문법을 데이터베이스마다 바꾸는 것만으로는 부족하고, 각 작업의 실행 조건까지 맞아야 한다.

References​

• PostgreSQL 공식 문서, Partial Indexes
• Oracle Database 19c SQL Language Reference, CREATE INDEX
• NestJS 공식 문서, Lifecycle events
• Oracle 공식 오류 문서, ORA-00955
• Oracle 공식 오류 문서, ORA-01408
• Oracle Database 19c Reference, USER_TABLES

Deep Connector를 온프레미스 환경에 옮기던 중 만난 문제다. 오류를 수정해 이미지를 다시 만들었는데도 기동 로그에는 같은 ORA-01031: insufficient privileges가 남았다. 하나를 고칠 때마다 다른 조건이 드러났다. 결국 오류를 처리하는 코드보다 먼저 살펴봐야 했던 것은 “이 계정에서 무엇이 보이는가”였다.

이 글은 당시 개발 기록을 재구성한 회고다. 고객사, 작업 날짜, 실제 계정명과 배포 식별자는 제외했다. 아래 계정과 테이블 이름은 설명용 가명이며 SQL은 진단 예시다. 글 작성 과정에서 운영 환경이나 Oracle 재현 실험을 다시 실행한 것은 아니다.

권한 오류가 아니라 존재 판정부터​

기동 코드의 의도는 단순했다. 필요한 테이블을 확인하고, 없으면 생성한다. 개발 환경에서는 애플리케이션이 테이블을 소유하고 DDL도 실행할 수 있어서 자연스러운 흐름이었다.

테이블 존재 여부 조회
  -> 있으면 계속 기동
  -> 없으면 CREATE TABLE

다른 환경에서는 DBA가 스키마를 미리 만들고 애플리케이션 계정에는 필요한 데이터 접근 권한만 부여할 수 있다. 이때 존재 판정을 잘못하면, 이미 있는 테이블을 만들려는 코드가 실행된다. 마지막에 보이는 오류는 권한 부족이지만 앞에서 잘못 내린 판단은 테이블 부재다.

권한을 더 주는 방식으로 접근하면 불필요한 생성 시도 자체는 남는다. 먼저 테이블이 없다고 판단한 조회를 확인해야 했다.

대소문자가 만든 첫 번째 오판​

Oracle은 따옴표로 감싸지 않은 식별자를 대문자로 해석한다. 예를 들어 다음 DDL의 테이블 이름은 카탈로그에 APP_SETTINGS로 저장된다.

CREATE TABLE app_settings (
  id NUMBER PRIMARY KEY
);

반면 아래 조회에서 'app_settings'는 식별자가 아니라 문자열 리터럴이다. 대문자로 저장된 이름을 이 조건으로 찾으면 일치하지 않는다.

SELECT table_name
FROM user_tables
WHERE table_name = 'app_settings';

당시 기록에는 이 차이 때문에 존재 확인이 실패하고 생성 경로로 넘어간 과정이 남아 있다. DDL의 이름 규칙과 애플리케이션의 식별자 처리를 맞추는 수정이 필요했다.

그렇다고 대소문자만 맞추면 끝나는 문제는 아니었다. 이름을 비교하기 전에, 조회 대상에 그 테이블이 들어오는지부터 따져야 했다.

USER_TABLES는 내가 접근할 수 있는 테이블 목록이 아니다​

설명용 계정으로 구조를 줄이면 다음과 같다.

DATA_OWNER   테이블 소유 계정
APP_CLIENT   애플리케이션 접속 계정

APP_CLIENT가 DATA_OWNER의 테이블을 조회할 권한이 있다고 해서 그 테이블의 소유자가 되는 것은 아니다. Oracle의 USER_TABLES는 현재 사용자가 소유한 테이블을 보여준다. 접근 가능한 테이블을 보여주는 ALL_TABLES와 범위가 다르다.

앱이 APP_CLIENT로 접속한 뒤 USER_TABLES에서 대상 테이블을 찾으면 결과가 없을 수 있다. 테이블이 없어서가 아니라 다른 계정이 소유하고 있기 때문이다.

-- 애플리케이션이 사용하는 계정으로 실행하는 진단 예시
SELECT USER FROM dual;

SELECT owner, table_name
FROM all_tables
WHERE LOWER(table_name) = 'app_settings';

두 조회를 함께 보면 접속 사용자와 접근 가능한 테이블의 소유자를 비교할 수 있다. 같은 이름의 테이블이 여러 스키마에 있을 수 있으므로, 결과를 확인한 뒤에는 의도한 소유자까지 조건에 넣어야 한다.

여기서도 결과가 없다는 이유만으로 테이블이 없다고 단정하면 안 된다. ALL_TABLES 역시 현재 사용자에게 접근 가능한 테이블만 보여준다. 객체 부재와 접근 권한 부족을 구분하려면 DBA의 확인이 필요할 수 있다.

CURRENT_SCHEMA를 바꿔도 소유자가 되지는 않는다​

소유자와 접속 사용자가 다르면 CURRENT_SCHEMA 변경이나 시노님을 떠올리기 쉽다. 둘 다 객체 이름을 해석하는 문제를 풀 때 유용하다.

-- 실제 계정명이 아닌 설명용 예시
ALTER SESSION SET CURRENT_SCHEMA = DATA_OWNER;

하지만 이 설정은 접속 사용자를 바꾸지 않는다. 추가 권한을 부여하지도 않는다. 소유자를 생략한 객체 이름을 어느 스키마에서 찾을지 바꾸는 것과, USER_TABLES가 보여주는 소유 관계는 별개다.

시노님도 마찬가지다. 다른 스키마의 테이블을 편하게 참조할 이름을 만들 수 있지만, 그 테이블이 접속 계정의 소유가 되는 것은 아니다.

당시 존재 판정은 여전히 USER_TABLES를 보고 있었다. 데이터 조회의 이름 해석을 고쳐도 기동 점검은 계속 테이블이 없다는 결론에 도달했다.

예외를 삼키는 수정도 같은 전제에 묶였다​

다음 시도는 생성에 실패하더라도 테이블이 이미 있으면 계속 기동하는 방식이었다. 하지만 “이미 있다”는 재확인에 같은 카탈로그 조회를 쓰면 결과도 같다.

CREATE TABLE 실패
  -> 기존 테이블인지 다시 확인
  -> USER_TABLES에서는 여전히 찾지 못함
  -> 오류 전파

기동 DDL을 실행하는 함수도 하나가 아니었다. 한 경로의 예외 처리를 고쳤다고 다른 스키마 초기화 경로까지 바뀌는 것은 아니었다. 같은 오류 번호만 따라가다 보니, 수정한 함수가 실제 실패 지점인지와 그 함수의 조회 전제가 맞는지를 따로 확인해야 했다.

이 시점부터 질문을 바꿨다. “어떤 오류를 무시할까”가 아니라 “이 배포에서 스키마를 관리하는 주체는 누구인가”를 먼저 정리했다.

스키마 관리와 애플리케이션 기동의 분리​

애플리케이션이 스키마를 관리하는 환경이라면 마이그레이션이나 초기화 DDL이 필요할 수 있다. 반대로 DBA가 미리 준비한 외부 스키마에 접속하는 환경에서는 같은 기동 경로를 그대로 적용하기 어렵다.

당시 수정은 소유자가 분리된 외부 스키마를 명시하고, 연결에서 사용할 스키마를 설정하며, 그 모드에서 기동 시 추가 DDL을 실행하지 않는 방향이었다. 소유자를 인식하도록 카탈로그 조회를 모두 바꾸는 방법도 검토했지만, 이 환경에서는 앱이 스키마를 수정하는 주체가 아니었다.

이것이 모든 스키마 검증을 없애도 된다는 뜻은 아니다. 필요한 테이블과 컬럼이 준비됐는지 확인하는 절차는 별도로 필요하다. DDL을 실행하지 않는 것과 올바른 스키마임을 확인하는 것은 다른 일이다. 명시적으로 스키마 동기화를 켜는 설정도 외부 스키마 운영 방식과 충돌하지 않는지 점검해야 한다.

로컬에 재현해야 했던 것은 데이터보다 권한 구조​

코드만 보면 수정이 맞아 보이는 순간이 여러 번 있었다. 확인이 부족했던 것은 실제 연결에서 그 코드가 어떻게 동작하는지였다.

당시에는 로컬 Oracle 컨테이너에 소유 계정과 접속 계정을 분리해 만들고, 애플리케이션 계정에 필요한 데이터 접근 권한을 부여한 환경을 구성했다. 같은 자리에서 수정 전후의 기동 경로와 엔티티 조회를 비교했다.

테이블을 만들고 조회하는 테스트만으로는 부족했다. 다음 조건이 함께 있어야 원래의 실패를 재현할 수 있었다.

• 테이블 소유자와 애플리케이션 접속 사용자가 다르다.
• 애플리케이션 계정은 테이블을 생성할 권한이 없다.
• 테이블은 미리 존재하고 앱에는 필요한 데이터 접근 권한이 있다.
• 실제 연결과 기동 코드를 거쳐 존재 확인과 엔티티 조회를 실행한다.

이 재현은 연결 풀의 세션 설정이 ORM을 거쳐 실제 연결에 적용되는지 확인하는 데도 쓰였다. 가짜 카탈로그 응답으로 분기만 통과시키는 테스트와는 확인하는 대상이 달랐다.

이 글에 새 실측값을 싣지 않은 이유도 같다. 당시 재현 기록과 지금 다시 실행한 결과를 섞으면, 독자는 어느 버전과 환경에서 검증했는지 알 수 없게 된다.

코드 수정은 설정 전달까지 이어져야 했다​

식별자 처리처럼 기존 배포에 영향을 주는 변경은 기본 동작을 유지하고 설정으로 켜도록 만들 수 있다. 그런데 새 기능이 이미지에 들어 있어도 설정이 꺼져 있으면 동작은 달라지지 않는다.

당시에는 설정 템플릿의 주석과 배포 전 검사에 빈틈이 있었다. 새 이미지를 넣는 것만으로 수정이 적용됐다고 생각하기 쉬운 상태였다.

그래서 환경변수를 추가할 때 코드뿐 아니라 템플릿과 사전 검사도 함께 바꾸는 것을 재발 방지 항목으로 남겼다. 특히 외부 스키마를 쓰면서 자동 동기화를 켜는 것처럼 충돌하는 설정은 기동 전에 드러나야 한다.

같은 오류가 다시 나오면​

ORA-01031이 다시 보인다면 곧바로 권한을 추가하거나 예외를 무시하는 코드를 넣기보다, 다음 순서로 조사하려 한다.

1. 애플리케이션이 실제로 접속한 사용자를 확인한다.
2. 대상 테이블의 소유자와 저장된 식별자 표기를 확인한다.
3. 존재 판정이 USER_TABLES와 ALL_TABLES 중 무엇을 조회하는지 확인한다.
4. 실패한 DDL을 실행한 기동 경로와 스키마 관리 주체를 확인한다.
5. 수정 코드뿐 아니라 필요한 설정이 전달됐는지 확인한다.

테이블이 있는데 없다고 판단한 문제를 CREATE 권한으로 풀려고 하면, 잘못된 존재 판정은 그대로 남는다. 이번 경험에서 바뀐 것은 오류를 처리하는 순서였다. 마지막 오류보다 먼저, 실패한 DDL을 실행하게 만든 판단을 확인한다.

References​

• Oracle Database Reference: USER_TABLES: 현재 사용자가 소유한 테이블
• Oracle Database Reference: ALL_TABLES: 현재 사용자가 접근 가능한 테이블
• Oracle SQL Language Reference: ALTER SESSION: CURRENT_SCHEMA의 이름 해석과 권한 범위
• Oracle SQL Language Reference: Database Object Names and Qualifiers: 인용 식별자와 비인용 식별자의 대소문자 규칙

Deep Connector의 평가 집계에서는 평균과 함께 근거를 요구한 행 수, 측정 가능한 근거가 있는 행 수를 구분한다. 이 설계를 검토하면서 작은 데이터를 만들어 집계 함수를 실행해 봤다. 같은 입력도 null과 0을 어떻게 처리하느냐에 따라 평균이 30%, 50%, 75%로 달라졌다.

아래 질문과 점수는 집계 규칙을 확인하려고 만든 설명용 데이터다. 고객 문서나 실제 평가 성적을 사용하지 않았다. 실험은 저장소의 특정 구현 스냅샷에서 가져온 순수 함수만 실행했으며, 검색 엔진이나 LLM을 호출한 성능 실험은 아니다.

점수가 없는 이유부터 분리​

근거 평가에는 질문과 기대 답변만으로 부족할 때가 있다. 어떤 문서의 어느 내용이 답변을 뒷받침하는지도 정답 데이터에 있어야 한다. 검색 결과에 그 근거가 포함됐는지 비교하려면, 기대 근거 자체를 읽고 해석할 수 있어야 한다.

이때 0은 비교를 수행했지만 찾은 근거나 덮은 내용이 없다는 측정값이다. null은 해당 지표의 측정값이 없다는 뜻이다. 근거를 지정했어도 참조를 해석하지 못하면 측정값을 만들지 못할 수 있다.

근거를 아예 지정하지 않은 질문도 별도로 봐야 한다. 문서 이름만으로 검색 순위를 평가하는 질문을 근거 본문 평가에 실패한 질문으로 세면, 서로 다른 평가 대상을 섞게 된다.

근거를 요구하지 않음  -> 이 근거 지표의 평가 대상 아님
근거를 요구했으나 측정 불가  -> 측정값 없음
근거를 측정했으나 못 찾음  -> 측정값 0

모두 화면에서 빈칸처럼 보일 수 있지만, 고쳐야 하는 대상은 다르다. 검색 실패를 조사할 때와 정답 근거의 참조 문제를 조사할 때 같은 작업을 시작해서는 안 된다.

같은 점수 배열로 평균을 바꿔 보기​

설명용 입력에 측정값 1, 0.5, 0을 넣었다. 이어서 근거를 요구했으나 측정하지 못한 행과 근거를 요구하지 않은 행을 하나씩 추가했다. 이 지표만 배열로 꺼내면 다음과 같다.

const values = [1, 0.5, 0, null, null];

평균을 낼 때 null을 전부 0으로 바꾸면 합계는 그대로지만 분모가 늘어난다. 반대로 filter(Boolean)으로 빈 값을 제거하면 측정값 0까지 사라진다. JavaScript에서 0과 null은 둘 다 falsy이기 때문이다.

아래 코드는 이 차이를 보여주는 독립 실행 예시다. 제품 소스 전체를 옮긴 코드가 아니며, 입력은 유한한 0~1 값과 null로 제한했다.

const values = [1, 0.5, 0, null, null];
const mean = xs => xs.length
  ? xs.reduce((sum, value) => sum + value, 0) / xs.length
  : null;

console.log(mean(values.map(value => value ?? 0)));
console.log(mean(values.filter(value => typeof value === "number")));
console.log(mean(values.filter(Boolean)));

실행 결과는 다음 순서였다.

0.3
0.5
0.75

첫 번째 값은 측정하지 못했거나 대상이 아닌 행까지 실패로 센 결과다. 마지막 값은 측정된 실패를 분모에서 지운 결과다. 가운데 값만 이 예시의 측정값 1, 0.5, 0을 모두 보존했다.

검색 결과는 하나도 바꾸지 않았다. 바꾼 것은 평균을 낼 때 포함한 행뿐이다. 다만 typeof value === "number"는 일반적인 입력 검증기가 아니다. NaN이나 무한대도 number 타입이므로, 외부 입력을 받는 코드라면 유한성과 허용 범위를 별도로 확인해야 한다.

평균 옆에 측정 행 수를 붙인 이유​

숫자만 골라 평균을 내더라도 문제가 남는다. 근거를 요구한 질문 중 얼마나 측정했는지 모르면, 높은 평균이 얼마나 좁은 범위를 설명하는지 알 수 없다.

검토한 집계 코드에는 다음 카운터가 있다.

• evidence_rows는 근거 목록에 항목이 하나 이상 있거나 공백이 아닌 기대 근거 본문이 있는 행 수다.
• evidence_measured는 그중 측정 가능한 근거가 있는 행 수다.

근거 목록은 항목 중 하나라도 measurable이면 측정 가능한 행으로 센다. 따라서 이 카운터는 질문 안의 모든 근거가 준비됐다는 보증이 아니다. 단수 근거 본문을 쓰는 경로에서는 본문이 있고 coverage 값이 null이나 undefined가 아니면 측정 가능한 행으로 분류한다. 여기서 coverage 0은 제외하면 안 된다.

설명용 입력을 실제 집계 함수에 넣었을 때, 전체 행은 5개이고 근거를 요구한 행은 4개였다. 그중 측정 가능한 행은 3개였고 평균 coverage는 0.5였다. 표시 함수에도 같은 요약을 넘겼다. 예시에서는 recall과 coverage에 같은 값을 넣어 표시 결과를 비교했다.

근거 50% 찾음 · 50% 덮음 (4행 중 3행만 측정)

이 문구는 “전체 질문에서 근거를 절반 찾았다”와 다르다. 측정된 값의 평균이 50%이고, 근거를 요구한 행 중 측정하지 못한 행이 남아 있다는 뜻이다.

100%여도 측정은 끝나지 않을 수 있다​

별도 입력에서는 근거를 요구하는 행을 세 개 만들었다. 그중 한 행에만 측정값 1을 주고 나머지는 null로 뒀다. 실제 집계 함수와 표시 함수의 결과는 이랬다.

근거 100% 찾음 · 100% 덮음 (3행 중 1행만 측정)

평균 100% 자체가 산술적으로 틀린 것은 아니다. 다만 측정되지 않은 행의 검색 성능까지 설명하지는 못한다. 측정하기 쉬운 항목만 남았다면 평균이 전체 데이터셋을 대표하지 못할 수도 있다.

한 행도 측정하지 못한 경우도 따로 실행했다. 근거를 요구한 행이 하나라면 평균은 null이고 표시 문자열은 근거 1행 중 0행만 측정이었다. 근거를 아예 요구하지 않은 행만 있으면 평균과 근거 요약 문자열이 모두 null이었다. 측정값 0만 있는 경우에는 근거 0% 찾음 · 0% 덮음이 유지됐다.

평균을 표시하지 않는다고 측정 불가 상태까지 숨겨서는 안 된다. 값이 없는 이유를 보여줘야 정답 데이터 준비 문제를 검색 실패로 오해하지 않는다.

recall과 coverage도 같은 평균이 아니다​

근거 recall은 측정 가능한 기대 근거 중 얼마나 찾았는지를 본다. coverage는 검색 결과가 기대 근거 내용을 얼마나 덮는지를 본다. 이 글의 실험에서 두 지표에 같은 숫자를 넣은 것은 집계와 표시를 비교하기 위한 설정이지, 두 지표가 같다는 뜻이 아니다.

검토한 집계 구현도 recall과 coverage에 숫자 값이 있는 행을 각각 세어 평균을 낸다. 두 지표의 평균 분모가 항상 같다고 가정할 수 없고, evidence_measured를 어느 평균의 분모로든 그대로 대입해서도 안 된다.

목록에 측정 가능한 근거가 있는지 세는 조건과 개별 지표 값이 숫자인지 확인하는 조건은 다른 검사다. 카운터와 지표가 일관된지는 값을 만드는 앞단에서도 확인해야 한다.

이 구분을 모든 평가 지표에 일괄 적용해서도 안 된다. 예를 들어 검색 순위의 MRR은 못 찾은 항목을 0으로 계산하는 규칙을 쓸 수 있다. 근거 지표에서 측정값이 없는 행을 제외한다는 이유로, 검색 실패 행을 모든 지표의 분모에서 빼면 안 된다.

이번에 확인한 범위​

저장소의 집계 함수와 표시 함수를 가져와 TypeScript 5.6.3으로 ES2022 대상으로 변환한 뒤 Node.js v22.22.3에서 실행했다. 혼합 입력, 일부만 측정한 입력, 전부 측정 불가인 입력, 근거를 요구하지 않은 입력, 측정값이 0인 입력을 각각 확인했다. 앞의 독립 실행 예시도 별도로 실행했다.

확인한 것은 준비된 입력이 어떤 평균, 카운터, 문자열로 바뀌는지다. 실제 정답 데이터의 정확성, 근거 참조의 해석, 검색 품질, LLM 답변 품질, 브라우저 화면 동작은 이 실험으로 검증하지 않았다. 설명용 입력을 직접 넣었으므로 전체 API 경로의 검증 결과로 볼 수도 없다.

평가 결과를 읽는 순서​

평가 평균을 비교하기 전에 근거를 요구한 행과 측정 가능한 행부터 확인하려 한다. 측정 범위가 달라졌다면 같은 질문을 넣었어도 평균이 설명하는 대상은 달라질 수 있다. 측정 불가 항목을 조사하고, 비교 대상과 조건을 맞춘 뒤 검색 설정의 효과를 판단하는 편이 낫다.

낮은 점수를 고치는 일과 점수를 낼 수 없는 상태를 고치는 일은 다르다. 평가 코드가 그 차이를 보존해야 개발자도 어디부터 고칠지 결정할 수 있다.

References​

• MDN: Falsy: 0과 null의 Boolean 변환
• MDN: Array.prototype.filter(): 필터 조건에 따른 요소 선택
• Introduction to Information Retrieval: Evaluation of unranked retrieval sets: 일반적인 precision과 recall의 정의