09. 질의 접근 경로 — 어떤 질의가 어떤 인덱스를 타는가

이 문서가 답하는 질문

• 이 스키마에 존재하는 인덱스의 완전한 목록은 무엇인가?
• 대표적인 질의 형태 각각이 어떤 인덱스를 타는가?
• 어떤 접근이 순차 스캔인가, 그리고 그게 의도인가 아닌가?
• 계획을 직접 확인하려면 무엇을 실행하는가?

정본: engine/sql/bootstrap.sql(고정 인덱스), engine/src/catalog/types.rs / vector/mod.rs / compat/ddl.rs / typeql/schema.rs(런타임 인덱스), engine/src/cypher/compile.rs(생성 SQL).

1. 인덱스 전수 목록

부트스트랩 인덱스 (engine/sql/bootstrap.sql)

없는 인덱스 (문제가 되는 것)

런타임 생성 인덱스

엣지 타입 테이블의 (src)/(dst) 인덱스는 중복 생성될 수 있다 — create_type_inner가 익명으로 하나씩 만들고(engine/src/catalog/types.rs:429-430), TypeQL ensure_has_type은 e_<tid>_src / e_<tid>_dst라는 이름으로 만든다 (engine/src/typeql/schema.rs:542-543). $has는 카탈로그에 직접 INSERT되어 create_type_inner를 거치지 않으므로 실제 중복은 없지만, 두 경로가 나뉘어 있다.

2. 질의 형태별 접근 경로

Q1. 한 홉 확장 — MATCH (a:P)-[:K]->(b:P)

컴파일된 SQL (engine/src/cypher/compile.rs:900-904):

CROSS JOIN LATERAL (
  SELECT u.nbr, u.eid FROM og_data.og_adj adj1,
         LATERAL unnest(adj1.nbr, adj1.eid) AS u(nbr, eid)
   WHERE adj1.src = a0.id AND adj1.dir = 'o'::"char" AND adj1.etype = ANY($types)
) u1

힙 페이지 접근: 해당 (src, etype, dir)의 세그먼트 수만큼. 차수 ≤ 256이면 1개.

Q2. 라벨 스캔 — MATCH (a:P) WHERE a.val = 42

컴파일러가 v_<tid> 뷰를 만든다(engine/src/cypher/views.rs:93-138). 뷰는 구체 테이블들의 UNION ALL이므로, 각 분기에서:

벤치 하네스가 이 인덱스를 명시적으로 만드는 이유다(bench/harness.py:359).

주의: og_create_index(graph, type, prop)는 og_subtypes(tid)를 돌며 각 구체 테이블에 인덱스를 만든다(engine/src/catalog/types.rs:608-613). 나중에 만들어진 서브타입에는 인덱스가 안 붙는다.

Q3. 서브타입 판정 — og_is_subtype(sub, sup) / og_subtypes(root)

SELECT DISTINCT d.type_id
  FROM og_catalog.type_label a
  JOIN og_catalog.type_label d
    ON d.graph_id = a.graph_id AND d.lft >= a.lft AND d.rgt <= a.rgt
 WHERE a.type_id = $1

(engine/src/catalog/labeling.rs:197-202)

type_label_lft_idx는 여기서 쓰일 수 있지만 range_idx가 항상 최소한 같거나 낫다 (추가 컬럼 rgt가 인덱스 내 필터를 가능하게 하므로 힙 접근이 줄어든다).

Q4. 타입별 인스턴스 스캔 — og_nodes(root)

SELECT n.id, n.type_id FROM og_data.og_node n
 WHERE n.type_id IN (SELECT og_subtype_ids(og_nodes.root))

(engine/sql/access.sql:56-57)

og_node_type_idx (type_id, id) — type_id 등호(또는 IN) + id가 인덱스에 있어 index-only scan이 가능하다. (type_id)만이 아니라 (type_id, id)인 이유다.

Q5. id로 노드 하나 — og_node_json(id)

SELECT ty.type_id, ty.name, ty.storage_table
  FROM og_data.og_node n JOIN og_catalog.type ty ON ty.type_id = n.type_id
 WHERE n.id = og_node_json.id;
EXECUTE format('SELECT to_jsonb(x) FROM %s x WHERE x.id = $1', t.storage_table) ...;
SELECT jsonb_object_agg(p.name, raw -> p.column_name) FROM og_catalog.property p
 WHERE p.type_id = t.type_id AND raw ? p.column_name AND ...;

(engine/sql/access.sql:208-235)

전부 인덱스를 타지만 서브질의가 네 개다. LANGUAGE plpgsql이므로 인라인되지 않고, 행마다 한 번씩 돈다. to_jsonb(x)는 vector(N)이나 큰 __ext가 있으면 TOAST를 펼친다. → PERF-08

Q6. 미선언 프로퍼티 필터

타입이 알려진 경우 (engine/src/cypher/compile.rs:989):

(v0.__ext->>'foo') = 'bar'

→ 인덱스 없음. 순차 스캔. __ext에 GIN 인덱스를 만드는 코드가 없다.

타입 미상인 경우 (engine/src/cypher/compile.rs:991):

(og_node_json(n0.id)->>'foo') = 'bar'

→ 인덱스 없음 + 행마다 Q5 전체. 가장 비싼 형태다.

Q7. 벡터 검색

SELECT v.id, ... FROM og_data.v_<tid> v
 WHERE v.p_embedding IS NOT NULL AND (<filter>)
 ORDER BY v.p_embedding <=> $1::vector LIMIT k

(engine/src/vector/mod.rs:126-132)

각 UNION ALL 분기에서 hnsw_<sub>_p_embedding을 탄다 — ORDER BY <거리연산자> LIMIT k 형태가 HNSW가 인식하는 유일한 형태다.

ORDER BY 표현식이 인덱스의 opclass와 일치해야 한다. og_catalog.embedding.metric을 바꿔도 인덱스는 안 바뀌므로(→ 07) 어긋나면 조용히 순차 스캔 + 정렬로 떨어진다.

Q8. 깊은 순회 — og_reach / og_vlp / og_reach_sql

og_reach의 SQL (engine/src/storage/traverse.rs:94-97):

SELECT a.nbr FROM og_data.og_adj a WHERE a.src = ANY($1::int8[]) AND <dir/etype>

프론티어 전체를 한 문장으로 보낸다. 한 SPI 연결, 한 계획을 walk 전체에 재사용한다 (engine/src/storage/traverse.rs:99-106) — 지름이 큰 그래프에서 레벨당 재계획이 같은 walk를 재귀 CTE보다 10배 느리게 만들었던 측정이 이 결정의 근거다.

수치는 docs/deep-traversal.md 참조.

Q9. og_typeql_attribute 뷰 스캔

(engine/sql/access.sql:307-318)

이 뷰를 넓게 스캔하는 것은 비싸다 → PERF-08.

3. 의도된 전체 스캔

아래는 인덱스 부재가 결함이 아니다.

4. 계획 확인 방법

컴파일된 Cypher SQL 보기

SELECT og_cypher_sql('mygraph', $$ MATCH (a:P)-[:K]->(b:P) WHERE a.val = 1 RETURN count(b) $$);

(engine/src/cypher/mod.rs의 og_cypher_sql)

실행 계획

SELECT og_cypher_explain('mygraph', $$ ... $$, true);   -- true = ANALYZE, BUFFERS

(engine/src/cypher/mod.rs:677-682)

비용 추정 + 조언

SELECT og_estimate('mygraph', $$ ... $$);

(engine/src/agent/mod.rs:350-382) — 추정 행 수가 100만을 넘거나 연결되지 않은 패턴이 있으면 문장으로 경고한다.

인덱스가 실제로 쓰이는지

SELECT relname, indexrelname, idx_scan, idx_tup_read, idx_tup_fetch
  FROM pg_stat_user_indexes
 WHERE schemaname IN ('og_data', 'og_catalog')
 ORDER BY idx_scan ASC;     -- idx_scan = 0 인 것이 안 쓰이는 인덱스

이것이 위 1절의 "사용처를 못 찾음" 판정을 당신의 워크로드에서 확인하는 방법이다. 코드를 읽어서 내린 판정이므로, 사용자 SQL이 직접 쓰고 있을 수 있다.

og_adj 세그먼트 실측

SELECT etype, dir, count(*) AS segments, avg(n)::numeric(6,1) AS avg_fill,
       max(n) AS max_fill, sum(n) AS total_neighbours
  FROM og_data.og_adj GROUP BY etype, dir ORDER BY 5 DESC;

금지 / 필수

금지

• 미선언 프로퍼티(__ext)로 필터링하는 질의를 뜨거운 경로에 두는 것.
• 타입 미상 변수(MATCH (n) WHERE n.x = ...)로 프로퍼티를 읽는 것.
• og_typeql_attribute 뷰를 조인의 큰 쪽으로 쓰는 것.
• 인덱스를 추가하면서 이 문서를 갱신하지 않는 것.

필수

• 필터에 쓰이는 프로퍼티는 og_create_index(graph, type, prop)로 인덱스를 만들 것.
• 서브타입을 나중에 추가했으면 og_create_index()를 다시 부를 것. 기존 인덱스는 새 서브타입 테이블에 자동으로 생기지 않는다.
• 벌크 로드 후 ANALYZE. 통계가 없으면 깊은 순회 전환 판단이 "깊이 ≥ 4" 규칙으로 폴백한다(engine/src/cypher/compile.rs:51-54).
• 새 접근 경로를 만들면 이 문서의 1절과 2절에 행을 추가할 것.