Ontology Performance — M3 Step 3

본 가이드는 Epic #1232 M3 Step 3 에서 도입된 ontology 성능 최적화를 다룹니다.

PG 인덱스 3종

_PG_POST_MIGRATIONS 에 추가된 핫패스 인덱스 (모두 CREATE INDEX IF NOT EXISTS — idempotent):

인덱스	컬럼	핫패스
`idx_ontology_classes_workspace_pack_layer`	`(workspace_id, pack_id, layer)`	`GET /classes?workspace_id=&pack_id=&layer=` 스코프 쿼리
`idx_ontology_properties_class_id_name`	`(class_id, name)`	Designer Property fetch + nested PUT diff
`idx_ontology_relations_source_target_layer`	`(source_class_id, target_class_id, layer)`	Relation list 필터 + Designer edge fetch

기존 partial unique index (M2 Step 1) 와 함께 동작.

OntologyInstanceRepo 에 신규 메서드:

ensure_edge_collection() — onto_edges_relations edge collection (idempotent)
ensure_graph() — gend-ontology GRAPH 등록 (edge collection + 모든 onto_<class> vertex 매핑)

GRAPH 우선 — db.has_graph("gend-ontology") True 시 FOR v IN 1..@depth ANY @start GRAPH "gend-ontology" 진정한 multi-hop
Fallback — graph 미등록 / GRAPH AQL 실패 시 M2 Step 3 의 onto_<class> 내 _from/_to 매치
둘 다 실패 — 빈 neighbors (graceful, logger.warning)

기존 M2 Step 3 코드와 호환 — graph 미등록 환경에서도 traverse 정상 동작.

services/ontology/observability.py::start_gauge_refresh_loop — asyncio.Task 로 lifespan startup 에서 spawn, shutdown 에서 cancel.

# main.py lifespan
gauge_task = asyncio.create_task(start_gauge_refresh_loop())
# ...
gauge_task.cancel()
await gauge_task  # CancelledError graceful

GAUGE_REFRESH_INTERVAL_SECONDS = 1800 (30분). 개별 refresh 실패는 다음 주기에 회복 (loop 가 모든 예외 catch 후 sleep).

tests/load/endpoints/ontology-baseline.js — 3 endpoint:

함수	endpoint	SLO 목표
`listOntologyClasses(token)`	`GET /api/v1/ontology/classes`	p95 < 200ms
`getOntologyClass(token, classId)`	`GET /api/v1/ontology/classes/{id}`	p95 < 100ms
`createOntologyVersionSnapshot(token, label)`	`POST /api/v1/ontology/versions/snapshot`	p95 < 1s

본 PR 은 baseline 측정용 — 회귀 가드는 별도 M3 Step 4 또는 후속 PR 에서 SLO threshold 강화.

파일	범위
`apps/api/tests/test_ontology_performance.py`	인덱스 3종 _PG_POST_MIGRATIONS 등록 + IF NOT EXISTS, edge collection / GRAPH idempotent, traverse GRAPH 우선 + fallback, scheduler cancel, k6 script 존재 — 9
`apps/api/tests/test_ontology_metrics.py`	M3 Step 2 회귀 유지