문제 해결

이 문서가 답하는 질문

• 이 오류 메시지는 무엇을 뜻하는가?
• 증상별로 어디부터 확인해야 하는가?
• 무엇이 실제 오류이고 무엇이 "조용한 실패"인가?

이 문서의 규칙

• 여기 인용된 오류 문자열은 전부 저장소 코드에서 확인된 것이다. 파일:라인이 붙어 있다.
• 코드에 없는 오류는 이 문서에 없다. 처음 보는 메시지를 만나면 grep -rn "<메시지 조각>" engine/src 로 출처를 먼저 찾을 것.
• 조용한 실패를 별도로 표기했다. 이 시스템에서 가장 잡기 어려운 부류다.

0. 진단 1단계 — 어느 층인가

# 컨테이너
docker ps --filter name=ontological-dev

# PostgreSQL
docker exec ontological-dev bash -lc 'pg_isready -h localhost -p 28816'

# 확장
psql -h localhost -p 28816 -d og -tAc "SELECT ontological_version()"

# Studio
curl -s http://localhost:7474/api/health

# Bolt
docker exec ontological-dev bash -lc 'pgrep -af ontological-bolt'
docker exec ontological-dev bash -lc 'tail -20 /tmp/ontological-bolt.log'

# Studio 로그 (호스트)
tail -50 /tmp/ontological-studio.log

로그 위치를 다시 정리하면 — Bolt 로그는 컨테이너 안, Studio 로그는 호스트다 (02_startup_and_teardown.md 참조).

1. 설치 · 기동

2. 그래프 · 타입

3. Cypher

결과가 비어 있는데 오류가 없다

이 시스템은 진단 함수를 별도로 제공한다 (spec 008):

SELECT jsonb_pretty(og_explain_error('default', $$ ... $$));   -- 파싱/컴파일 오류의 구조화된 설명
SELECT jsonb_pretty(og_diagnose_empty('default', $$ ... $$));  -- 왜 비었는가
SELECT jsonb_pretty(og_estimate('default', $$ ... $$));        -- 예상 카디널리티
SELECT og_cypher_sql('default', $$ ... $$);                    -- 컴파일된 SQL
SELECT jsonb_pretty(og_cypher_explain('default', $$ ... $$, false));  -- 계획

Studio는 이 셋을 POST /api/diagnose 하나로 묶어 노출한다 (portal/server/index.js:233-253).

og_diagnose_empty / og_estimate는 Studio에서 실패해도 null로 대체되어 전체 응답을 막지 않는다 (portal/server/index.js:238-243).

알려진 미지원

bolt/README.md:74-75가 명시한다: UNION과 shortestPath는 psql 경로와 Bolt 경로에서 동일하게 실패한다. 지원 범위의 권위는 docs/cypher.md이며, 스펙 상태표는 README.md에 있다.

4. TypeQL

spec 010은 partial 상태다. tests/typeql/run.py는 미지원 항목을 실패가 아니라 unsupported로 표시한다 (tests/typeql/run.py:39-46).

5. 순회 · CSR

CSR 결과가 최신 데이터와 다르다

오류가 아니라 설계다. CSR 스냅샷은 빌드 시점에 얼어붙는다 (docs/deep-traversal.md:257-259, engine/src/storage/traverse.rs:21-23). 트리거 캡처가 없다. og_csr_drop() 후 다시 og_csr_build() 할 것.

CSR 결과에 보이면 안 될 행이 있다

역시 설계다. CSR 경로는 RLS를 참조하지 않는다 (docs/deep-traversal.md:260-261). RLS가 필요하면 og_reach(힙 BFS)를 쓸 것. Cypher 컴파일러가 CSR로 라우팅하지 않는 이유가 이것이다 (docs/deep-traversal.md:269-272).

깊은 순회가 끝나지 않는다

가변 길이 매치가 방문집합 BFS로 재작성되지 못하는 형태면 trail을 열거한다 — degree^k 행이다. 재작성이 막히는 조건 (docs/deep-traversal.md:201-215):

• 경로 변수 바인딩 MATCH p = ...
• 관계 변수 바인딩 -[e:K*1..3]->
• 중복이 관측 가능한 프로젝션 — count(x), sum, avg, 사용자 정의 집계
• 질의 어디든 WITH가 있음

또한 손익분기(Σ degreeⁱ > |V|) 미만이면 재작성하지 않는다. 그 판단은 플래너 통계에서 읽으며, 통계가 없으면 깊이만 보고 판단한다 (docs/deep-traversal.md:216-226).

조치 순서:

-- 1. 통계부터
ANALYZE og_data.og_adj;
ANALYZE og_data.og_node;
ANALYZE og_data.og_edge;

-- 2. 컴파일 결과에서 og_vlp 인지 og_reach 인지 확인한다
SELECT og_cypher_sql('default', $$ MATCH (a)-[:K*1..6]->(b) RETURN count(DISTINCT b) $$);

-- 3. 질의를 재작성 가능한 형태로 바꾼다 — DISTINCT 를 쓰거나 WITH 를 제거

폭주 중인 질의 종료:

SELECT pid, now() - query_start AS running_for, left(query,120)
  FROM pg_stat_activity WHERE state <> 'idle' AND datname = current_database();
SELECT pg_cancel_backend(<pid>);

statement_timeout을 미리 걸어두는 것이 근본 대책이다 — 03_configuration.md.

6. 벡터 · 임베딩

백엔드가 임베딩 요청 중에 응답하지 않는 현상은 버그가 아니라 구조다. og_genai_encode는 블로킹 HTTP 클라이언트를 쓴다 (engine/Cargo.toml:25-29). pg_stat_activity에서 해당 백엔드는 실행 중으로 보인다.

7. 식별자 고갈

engine/src/id.rs:31-32의 주석: "Panics (→ ereport(ERROR) via pgrx) on overflow so a silently truncated id can never reach storage." — 잘린 id가 저장되는 일은 없다.

할당 워터마크 확인:

SELECT a.type_id, t.name, a.next_id
  FROM og_data.og_id_alloc a
  JOIN og_catalog.type t ON t.type_id = a.type_id
 ORDER BY a.next_id DESC LIMIT 20;

8. Studio

9. Bolt 게이트웨이

Bolt 경로 자체를 확인하는 정식 방법은 tests/neo4j-movies/run.py다 — raw 핸드셰이크로 어느 포트가 Bolt를 말하는지 검사한다 (04_testing_and_ci.md §5).

10. 테스트 · 벤치마크

11. 조용한 실패 모음 — 오류가 나지 않는 실패

이 절이 이 문서에서 가장 중요하다. 아래 항목들은 성공한 것처럼 보인다.

12. PostgreSQL 로그에서 이 확장을 찾기

확장이 PostgreSQL 로그에 남기는 것은 거의 없다. 실측:

즉 기동·종료·스키마 변경·재정리 같은 수명주기 이벤트에 대한 로그가 없다. 운영 관측은 og_data.og_audit와 pg_stat_*에 의존해야 한다. → 10_improvements_ops.md OPS-18

-- 서버 로그 위치
SHOW log_directory;
SHOW log_destination;
SHOW logging_collector;

금지 / 필수

금지 (Forbidden)

• 이 문서에 없는 오류 메시지를 지어내지 말 것. 출처는 grep -rn 으로 확인할 것.
• agree: false인 벤치마크 셀의 숫자를 근거로 조치하지 말 것.
• CSR이 오래된 답을 준다고 버그로 처리하지 말 것 — 설계다.
• 무결성 위반 상태에서 계속 쓰지 말 것.

필수 (Required)

• 문제를 만나면 §0의 5개 층 확인부터 할 것.
• 조용한 실패(§11) 목록을 정기 점검 항목에 포함할 것.
• Cypher 문제는 og_cypher_sql → og_explain_error → og_diagnose_empty 순으로 좁힐 것.
• 재현 절차를 남길 때는 og_data.og_audit의 해당 행을 함께 첨부할 것.