02_api — SQL 함수 계약 색인

이 문서가 답하는 질문

• 이 데이터베이스의 "API"는 정확히 무엇인가?
• 공개 SQL 함수는 총 몇 개이고, 각각 어디에 정의되어 있는가?
• 어떤 함수가 STABLE이고 어떤 함수가 VOLATILE인가? 병렬 실행이 가능한가?
• 함수 이름만 알 때, 어느 문서를 봐야 하는가?

1. 사실 — 이 프로젝트의 1차 계약면

Ontological의 API는 REST가 아니라 PostgreSQL 함수 시그니처다. 확장을 설치하면(CREATE EXTENSION ontological CASCADE) 세 종류의 객체가 public 스키마에 생성된다.

부가 표면(1차 계약면 위에 얹힌 얇은 층)은 두 개뿐이다.

결정(Decision): 모든 기능은 평문 SQL에서 도달 가능해야 한다. Studio와 Bolt는 이 표면 위의 편의 계층이지 특권 경로가 아니다 (docs/api.md:3, bolt/src/main.rs:3).

2. 휘발성 / 병렬 안전성 표기 규칙

pgrx #[pg_extern(...)] 속성이 그대로 CREATE FUNCTION 절이 된다.

필수(Required) 해석 규칙: 속성이 없으면 PostgreSQL CREATE FUNCTION의 기본값이 적용된다 — 즉 VOLATILE, PARALLEL UNSAFE. 아래 표에서 "기본값"이라고 적힌 칸은 이 의미다.

금지(Forbidden): 아래 표에 없는 휘발성 값을 추정해서 쓰지 말 것. STRICT 여부는 소스에 strict가 명시된 함수만 확인되었다. 그 외 함수의 STRICT 여부는 pgrx의 자동 추론에 달려 있어 소스만으로는 미확인이다.

3. Rust 타입 → SQL 타입 대응 (코드에서 확인)

4. 전체 함수 색인 (78 × Rust + 13 × SQL + 7 뷰)

정렬은 카테고리 → 이름. "휘발성"·"병렬" 칸은 §2 규칙으로 읽는다.

4.1 그래프 · 타입 DDL → 01_graph_ddl.md

4.2 데이터 DML → 02_data_dml.md

4.3 Cypher → 03_cypher.md

4.4 TypeQL → 04_typeql.md

4.5 순회 · 통계 → 05_traversal_and_stats.md

4.6 벡터 · 하이브리드 검색 → 06_vector_search.md

4.7 에이전트 인터페이스 → 07_agent_interface.md

4.8 상호운용 · RDF → 08_interop_and_rdf.md

4.9 Neo4j 호환 → 09_neo4j_compat.md

CREATE INDEX / CREATE CONSTRAINT 계열은 SQL 함수가 아니라 Cypher DDL 문으로 진입한다 — engine/src/compat/ddl.rs:18. db.* / apoc.* 프로시저는 CALL ... YIELD로만 진입한다 — engine/src/compat/procs.rs:80.

4.10 SQL로 정의된 함수/뷰 (engine/sql/access.sql)

5. 실행 중인 데이터베이스에서 직접 확인하기

문서가 코드보다 뒤처졌을 가능성이 늘 있으므로, 정답은 항상 서버다.

-- Every public og_* function, exactly as installed.
SELECT p.proname || '(' || pg_get_function_arguments(p.oid) || ') -> '
                 || pg_get_function_result(p.oid) AS signature,
       p.provolatile,   -- i = immutable, s = stable, v = volatile
       p.proparallel,   -- s = safe, r = restricted, u = unsafe
       p.proisstrict
  FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
 WHERE n.nspname = 'public' AND p.proname LIKE 'og\_%'
 ORDER BY 1;

SELECT ontological_version();

6. 금지 / 필수

• 금지: 이 색인에 없는 og_* 함수를 존재한다고 가정하고 호출 코드를 작성하지 말 것. 본 색인은 #[pg_extern] 속성 전수 조사 결과다.
• 금지: og_catalog.* / og_data.* 테이블에 직접 INSERT / UPDATE하지 말 것. 쓰기 경로는 레지스트리·타입 테이블·양방향 인접 세그먼트를 한 트랜잭션에서 함께 갱신한다(engine/src/storage/mod.rs:1 모듈 주석, spec 001 FR-012). 직접 쓰면 og_check_integrity()가 잡아내는 불일치가 생긴다.
• 필수: 사용자 입력은 반드시 params jsonb 인자로 전달할 것. Cypher/TypeQL 질의 텍스트에 값을 문자열 연결하지 말 것(spec 003 FR-026).
• 필수: og_vector_search(filter), og_enable_rls(policy_expr), og_map_table(source_table)는 SQL 조각을 그대로 받는다. 이 세 인자에는 신뢰할 수 없는 입력을 절대 넣지 말 것 — 12_improvements_api.md API-05 참조.

7. 관련 문서

• 오류 체계 전반 → 11_errors.md
• API 계약 개선 포인트 → 12_improvements_api.md
• 원문 영문 요약 → docs/api.md