omnigraph 딥다이브
— 데이터에도 브랜치가 필요한 순간

1프로젝트 한줄 요약

omnigraph는 타입이 있는 그래프를 로컬 디스크나 객체 저장소에 보관하고, 그래프 전체의 버전을 브랜치로 관리하는 데이터베이스입니다. 문서를 벡터로 찾고, 단어로 찾고, 관계를 따라 좁히는 작업도 같은 쿼리 실행 환경에서 조합합니다.

예를 들어 Source는 실험 보고서, Claim은 검증할 주장, Supports는 “이 자료가 이 주장을 뒷받침한다”는 연결입니다. “지연 시간이 줄었다는 주장의 근거를 찾아라”는 질문은 문자열 검색을 넘어 관계 탐색이 됩니다.

여러 에이전트가 같은 지식을 읽되, 각자의 변경은 브랜치에서 검토한 뒤 그래프 전체에 반영하도록 만드는 것이 핵심입니다.

// schema.pg: 공식 빠른 시작의 근거 그래프
node Source {
  slug: String @key
  title: String
}
node Claim {
  slug: String @key
  statement: String
}
edge Supports: Source -> Claim

이 선언을 읽는 출발점은 crates/omnigraph-compiler/src/schema/schema.pest와 crates/omnigraph-compiler/src/schema/parser.rs입니다. 스키마를 파일로 선언하는 이유는 문서화뿐 아니라 쿼리 검사와 데이터 검증이 동일한 모델을 사용하게 하기 위해서입니다.

초보자가 먼저 구분할 세 가지

학습 목표는 데이터베이스를 통째로 재구현하는 것이 아닙니다. 먼저 작은 쿼리 하나가 어떤 타입 검사를 거쳐 어떤 스냅샷을 읽는지, 변경 하나가 언제부터 다른 독자에게 보이는지 설명할 수 있으면 충분합니다.

2왜 주목받는가

2026-10-23 선정 기준은 GitHub Trending Rust Weekly #8입니다. 스타 1,679와 포크 237은 관심의 크기를 보여주지만 채택 규모나 성능의 증거는 아닙니다. 아래의 주목 요인은 README의 지향점과 구현을 연결한 해석이며, 유입 경로를 측정한 통계가 아닙니다.

① 에이전트의 기억을 “수정 가능한 공유 상태”로 본다

README는 장시간 동작하는 여러 에이전트가 타입이 있는 세계 모델을 공유하는 워크로드를 내세웁니다. 단순 대화 기록 저장과 달리, 관계·키·변경 이력을 유지해야 합니다. 브랜치는 서로 다른 작업의 제안을 분리하고, 병합은 승인한 결과를 한 상태로 합치는 수단입니다.

구현에서도 crates/omnigraph/src/exec/merge.rs가 공통 조상·원본·대상 스냅샷을 비교하고, 합칠 후보에 제약 검증을 적용합니다. 브랜치는 이름만 붙인 복사본에 머무르지 않습니다.

② 검색 세 종류를 같은 스냅샷에서 조합한다

벡터 검색은 의미가 비슷한 대상을, 전문 검색은 단어가 맞는 대상을, 그래프 탐색은 관계를 만족하는 대상을 찾습니다. 검색 시스템을 따로 두면 동기화와 결과 결합을 앱이 맡아야 합니다. omnigraph는 nearest, bm25, rrf와 탐색을 실행 계획 안에서 다룹니다.

다만 “검색을 통합했다”가 “모든 검색을 정확 탐색으로 수행한다”는 뜻은 아닙니다. 근사 벡터 검색의 후보 수와 탐색 범위에는 비용·재현율의 절충이 있고, 인덱스 상태에 따른 거부 조건도 있습니다. 이 구분 자체가 좋은 학습 주제입니다.

③ 데이터의 정본과 검색 가속 장치를 분리한다

로컬 파일과 S3 계열 저장소를 같은 설계로 다루면서, 인덱스·캐시가 늦어져도 논리적인 데이터 의미를 바꾸지 않도록 경계를 세웁니다. 이 원칙은 docs/dev/invariants.md에 명시되어 있고, 쓰기와 인덱스 조정 경로가 분리되어 있습니다.

이 저장소의 교육적 가치는 기능 수보다, 정답을 결정하는 상태와 속도를 높이는 상태를 구분하는 방법에 있습니다.

비슷한 선택지와 비교하기

이 표는 처리량 순위가 아닙니다. 비교의 기준 모델은 pgvector 공식 저장소, Neo4j 공식 개념 문서, Lance 버전 관리 문서에서 확인할 수 있습니다. 같은 데이터·하드웨어의 직접 성능 비교는 제시하지 않습니다.

3기술 스택 전체 지도

루트 Cargo.toml은 22개 워크스페이스 멤버를 선언합니다. 기본 빌드 대상은 엔진·CLI·서버 세 패키지입니다. 엔진의 디렉터리는 crates/omnigraph, Cargo 패키지 이름은 omnigraph-engine, Rust 라이브러리 이름은 omnigraph이므로 명령과 경로에서 이름이 다르게 보입니다.

백엔드·데이터 처리

표에서 4.9처럼 보이는 선언은 일반적으로 정확한 고정값이 아닙니다. Cargo의 호환 범위 안에서 잠금 파일이 4.11.2를 선택할 수 있습니다. 반대로 Lance의 =13.0.0은 정확히 그 버전을 요구합니다. Cargo.lock에는 전이 의존성용 object_store 0.13.2와 reqwest 0.13.4도 있으므로, 이름 하나당 버전 하나라고 가정하면 안 됩니다.

사용자·앱과 만나는 계층

crates/omnigraph-server/Cargo.toml의 aws 기능은 기본값이 꺼져 있으며, 선택적으로 AWS Secrets Manager 기반 토큰 소스를 더합니다. 이것은 루트 Lance 의존성의 AWS 저장소 기능과 별개입니다.

인프라·빌드·검증

• 런타임 이미지: 루트 Dockerfile의 기본 이미지는 public.ecr.aws/debian/debian:bookworm-slim. 빌드 완료된 실행 파일을 복사하고 일반 사용자 omnigraph로 시작합니다.
• 컨테이너 실행: OMNIGRAPH_BIND=0.0.0.0:8080, 포트 8080, /healthz 상태 점검, tini 설치와 별도 진입 스크립트가 있습니다.
• 빌드 도구: Rust와 Protocol Buffers 컴파일러 protoc. CI는 protobuf-compiler와 libprotobuf-dev를 설치합니다.
• 정적 검사: .github/workflows/ci.yml에 Clippy·포맷·문서·의존성·금지 API 검사와 테스트 소유권 검사가 있습니다.
• 테스트 분리: 일반 워크스페이스 테스트, GQT 언어 사례, 결정적 시뮬레이션 DST를 서로 다른 실행 맥락으로 다룹니다. CI의 cargo-nextest는 0.9.143으로 고정됩니다.

# 공식 소스 빌드 문서의 예시. 테스트 전용 플래그를 대체한다.
RUSTFLAGS= cargo build --release --locked \
  -p omnigraph-cli \
  -p omnigraph-server \
  -p omnigraph-azure-admission

.cargo/config.toml의 --cfg tokio_unstable은 테스트의 시드 기반 스케줄링에 사용됩니다. 공식 릴리스 빌드는 환경의 RUSTFLAGS로 이를 대체합니다. “unstable 설정이 있으니 nightly 제품이다”라고 읽으면 잘못된 결론입니다.

4아키텍처 심화 분석

이 그림은 crate 간 책임을 묶어 그린 논리 구조입니다. 각 상자가 반드시 별도 프로세스라는 뜻은 아닙니다. CLI는 엔진을 내장해 로컬 그래프를 열 수 있고, 원격 대상에서는 서버 API로 요청을 보냅니다. 서버는 적용된 클러스터 구성을 바탕으로 여러 그래프를 제공합니다.

패턴 1. 타입으로 실행의 입장권을 만든다

읽기의 출발점인 Session::query_with_head()는 crates/omnigraph/src/exec/query_doors.rs에 있습니다. 먼저 설정을 정하고 capture_read_view()로 스냅샷과 카탈로그를 함께 잡은 뒤, 이름이 있는 쿼리를 컴파일합니다. 반환하는 그래프 커밋 ID도 실제로 읽은 스냅샷에서 가져옵니다.

1. crates/omnigraph-compiler/src/query/parser.rs::parse_query()가 Pest 문법으로 문자열을 구문 구조로 바꿉니다.
2. crates/omnigraph-compiler/src/query/typecheck.rs가 바인딩·속성·검색 인자의 타입을 확인하고 검사된 쿼리를 만듭니다.
3. crates/omnigraph-compiler/src/ir/lower.rs::lower_query()가 타입을 유지한 중간 표현 QueryIR로 변환합니다.
4. 플래너 crates/omnigraph-planner/src/gate.rs::accept_query()가 실행 계획을 만들고, 원래 쿼리의 요구를 보존했는지 검사합니다.
5. 엔진 crates/omnigraph/src/engine/bind.rs::bind()가 승인된 계획에 매개변수·검색 벡터를 묶어 실행에 넘깁니다.

// crates/omnigraph-planner/src/validate/mod.rs 발췌
pub struct AcceptedPlan {
    plan: PhysicalPlan,
    evidence: Evidence,
}

// 필드는 비공개이며 역직렬화로 이 타입을 만들지 않는다.
// 검증 성공 뒤 bind()가 AcceptedBoundPlan을 만든다.

배울 점: “검증했으니 조심해서 실행하자”를 관례로 남기지 않고, 실행에 필요한 타입을 검증기만 만들도록 합니다. API 입력의 검증 전·후 타입을 나누는 작은 서비스에도 적용할 수 있는 방식입니다.

검증 범위도 과장하지 않습니다. ValidationScope::ExactSubset은 제한된 쿼리 형태에서 재작성 과정을 재구성해 비교하고, InvariantsOnly는 검색·조건·점수·정렬·잘라내기 등의 불변식을 확인합니다. 후자가 모든 쿼리의 결과 동등성을 증명한다는 뜻은 아닙니다. explain과 실제 실행도 같은 승인 경로를 공유합니다.

최신 커밋에서 보는 작은 최적화

484e334의 주제는 상위 계획이 불필요한 삭제 확인을 생략하도록 하는 것입니다. crates/omnigraph-planner/src/optimizer.rs는 CSV 덮어쓰기 로드의 Validate 노드를 만들 때 다음 조건을 기록합니다. 아래 코드는 핵심 분기의 발췌입니다.

let removal = if overwrite && retained_edge_checks > 0 {
    ValidateRemoval::Scan
} else {
    ValidateRemoval::None
};

간선이 참조하는 기존 노드를 교체하면 사라질 ID를 알아야 관계 무결성을 확인할 수 있습니다. 반면 참조 간선 검사가 없거나, 대상 노드 테이블이 비어 해당 검사가 제거되면 그 스캔이 필요 없습니다. 간선 테이블의 교체도 노드 삭제 탐지가 필요 없는 경우입니다.

결정은 validate_removal 통계와 PhysicalNode::Validate.removal에 남고, crates/omnigraph/src/engine/operators/validate.rs의 LoadJudge로 전달됩니다. 실행기가 저장소 상태를 다시 추측하지 않도록, 무엇을 검사할지 계획이 먼저 결정하고 실행은 그 결정을 따른다는 사례입니다. 정량적인 속도 향상 수치는 이 분기만으로 산출할 수 없습니다.

패턴 2. 준비와 공개를 분리해 그래프를 원자적으로 바꾼다

노드와 간선은 서로 다른 Lance 데이터셋입니다. 노드 테이블만 바뀐 순간을 독자가 볼 수 있다면 간선이 존재하지 않는 노드를 가리킬 수 있습니다. 단일 테이블의 트랜잭션만으로는 그래프 전체의 일관성을 설명할 수 없는 이유입니다.

엔진은 WriteTxn의 기준 스냅샷에서 검증하고 테이블별 변경을 detached commit으로 준비합니다. 이 버전은 내구성 있게 저장되어도 아직 그래프의 정본에서 참조되지 않습니다. 마지막에 카탈로그의 __manifest를 한 번 바꾸어 모든 버전 참조와 스키마·계보를 함께 공개합니다.

crates/omnigraph-catalog/src/lib.rs의 ManifestCoordinator::commit_changes_with_lineage_and_precondition()는 조건을 포함해 publisher를 호출한 뒤 성공한 상태를 설치합니다. crates/omnigraph-catalog/src/commit.rs::overwrite_probed()는 Lance Operation::Overwrite를 사용하며, 선형 공개의 CommitBuilder에는 with_max_retries(0)을 설정합니다. 상위 publisher가 공개 전제조건과 테이블 버전 조건을 재확인하며 경합을 다룹니다.

파일에 새 값이 쓰였다는 사실과, 그 값이 그래프의 정식 상태로 보인다는 사실은 서로 다릅니다.

등록된 테이블의 일반적인 쓰기는 선형 HEAD를 계속 올리는 방식이 아닙니다. 생성 시의 선형 버전을 유지하고, 그래프가 참조할 detached 버전을 만듭니다. 따라서 raw Lance HEAD를 임의로 읽거나 직접 쓰면 그래프의 공개 규약을 우회합니다. docs/dev/invariants.md와 docs/dev/writes.md가 이 금지 경계를 설명합니다.

공개 전 장애가 나면 독자는 이전 상태를 읽습니다. 미공개 버전은 나이가 오래됐다는 이유만으로 삭제하지 않고, 그것을 공개할 수 있는 권한 상태가 사라졌는지까지 확인해 회수합니다. 응답이 유실되어 공개 여부가 불확실한 경우에는 성공·실패를 임의로 단정하거나 쓰기를 무조건 재전송하지 않습니다.

패턴 3. 버전 참조를 공유하고 세 방향으로 병합한다

브랜치는 부모의 정확한 테이블 버전 참조를 상속합니다. 현재 방식에서는 그래프 브랜치마다 노드·간선의 전체 파일을 복제하거나 모든 테이블의 Lance 브랜치를 새로 만들지 않습니다. 이후 각 그래프 브랜치가 만든 detached 버전 체인은 자신의 __manifest 계보가 소유합니다.

crates/omnigraph/src/exec/merge.rs::branch_merge_as_with_options()가 정책과 옵션의 진입점이며, resolve_merge_base()·branch_merge_impl()이 조상 탐색과 병합 흐름을 맡습니다. plan_lineage_merge()는 파일 동일성과 버전 핀 등의 조건을 확인해 변경 후보를 줄이고, 조건을 증명하지 못하면 일반 비교 경로로 돌아갑니다.

엔터티 단위 충돌이므로 “속성 이름이 다르면 Git처럼 자동으로 합쳐질 것”이라고 추측하면 안 됩니다. 데이터가 충돌하지 않아도 유일 키나 간선 제약을 어기면 병합이 실패할 수 있습니다. branch_merge_dry_run()은 분류·검증까지 수행하고 최초 효과 전에 멈춥니다.

패턴 4. 인증은 경계에서, 쓰기 권한은 엔진에서 검사한다

인증은 “누구인가”, 인가는 “이 그래프·브랜치에서 이 행동을 허용하는가”입니다. 서버의 authenticate_bearer_token()은 토큰에서 행위자를 결정합니다. 정적 토큰 경로는 SHA-256 해시를 비교하며, ct_eq()와 전체 항목 순회로 일치 위치에 따른 시간 차이를 줄입니다. 이후 서명 토큰 검증 경로도 존재합니다.

쓰기 권한의 중심은 crates/omnigraph/src/db/omnigraph.rs::enforce()입니다. 정책이 설정되어 있는데 행위자가 없으면 거부하고, 있으면 PolicyChecker::check(action, scope, actor)를 호출합니다. crates/omnigraph/src/exec/mutation.rs::enforce_change()도 이 문을 통과합니다.

단, 정책이 설치되지 않은 내장 개발 환경에서 enforce()는 허용 경로입니다. 또한 현재 ResourceScope를 일반적인 행 단위 RLS로 설명할 근거는 없습니다. 타입에는 그래프·브랜치·대상 브랜치·브랜치 전환 범위가 표현되어 있습니다.

5디렉토리 구조 해부

omnigraph-gqt*는 설명을 위해 omnigraph-gqt·omnigraph-gqt-core·omnigraph-gqt-served를 묶어 쓴 표기입니다. 실제 폴더 이름에 별표가 들어가지는 않습니다.

첫 독해 경로 세 가지

코드 규모를 읽는 법

커밋 484e334의 확장자별 파일 집계이며 .git은 제외합니다. 테스트·주석·빈 줄을 포함한 물리적 줄 수이므로 제품 구현만의 LOC가 아닙니다. Rust 중 tests 경로는 172,708줄이고 나머지에도 인라인 테스트가 있습니다. Markdown 코드 블록은 이 표에 포함되지 않습니다.

엔진 crate만 203,048줄, 컴파일러 36,951줄, 플래너 28,351줄입니다. 분량의 차이는 중요도의 순위가 아닙니다. 작은 컴파일러 경계부터 읽으면 저장소 호출을 이해하지 않고도 타입·IR 설계를 배울 수 있습니다.

6학습 포인트 (기술별)

Rust: 공유 소유권과 검증된 상태 표현

crates/omnigraph/src/session.rs의 Session은 Arc<Omnigraph>와 요청의 설정·설정 출처를 가집니다. Arc는 엔진을 여러 사용자가 공유하게 하고, 세션 설정은 호출별로 보관합니다. 기준 설정도 따로 있어 reset의 의미를 유지합니다.

작은 실습: Session::from_defaults()·rebind()·detach()의 인자와 반환 타입을 적어 보세요. 엔진 핸들을 다시 열어도 어떤 설정이 남는지, Clone이 대규모 데이터 복제를 뜻하는지 구분하는 연습입니다.

컴파일러: 문법·의미·실행 방법을 나누기

crates/omnigraph-compiler/src/query/query.pest는 표현의 형태를, crates/omnigraph-compiler/src/query/typecheck.rs는 타입과 사용 가능성을, crates/omnigraph-compiler/src/ir/lower.rs는 실행 계층에 전달할 구조를 담당합니다. 문법상 맞는 $source.typo도 스키마에 없는 속성이면 의미 검사에서 거부할 수 있습니다.

작은 실습: 유효한 쿼리와 속성 오타가 있는 쿼리를 나란히 적고, 토큰화·파싱·타입 검사 중 어디서 갈리는지 표시하세요. “문자열이 들어왔다”에서 바로 저장소 호출로 뛰어들지 않는 이유를 설명해 보세요.

자료구조: 문자열 ID를 조밀한 정수로 바꾸기

crates/omnigraph/src/graph_index/mod.rs::TypeIndex는 문자열 ID와 u32 인덱스를 대응시키고, CsrIndex::build()는 간선을 두 배열로 묶습니다. neighbors()의 핵심은 다음처럼 짧습니다.

// CsrIndex::neighbors()의 배열 접근 부분
let start = self.offsets[node as usize] as usize;
let end = self.offsets[node as usize + 1] as usize;
&self.targets[start..end]

작은 실습: 노드 3의 간선 두 개를 추가할 때 배열이 어떻게 바뀌는지 손으로 써 보세요. 이어서 from_parts()가 오프셋의 시작·단조 증가·마지막 위치를 왜 검증하는지 설명하세요. 저장한 가속 자료도 읽을 때 구조 검증이 필요합니다.

쿼리 엔진: 후보를 일찍 줄이는 것과 정답을 잃는 것 구분하기

“먼저 가장 가까운 10개를 찾고, 그중 특정 팀의 문서만 남기기”와 “특정 팀의 문서에서 가까운 10개 찾기”는 다릅니다. 플래너의 필터 위치와 후보 확장 정책은 이 차이를 다룹니다. crates/omnigraph/src/engine/search.rs, crates/omnigraph/src/engine/plan_source.rs, 플래너 crates/omnigraph-planner/src/physical.rs를 함께 읽어야 합니다.

작은 실습: 후보 5개 중 앞의 3개가 팀 필터에서 탈락하는 표를 만들어 보세요. 후보 부족을 막는 재탐색과 ANN 순위 자체의 정확도는 다른 문제라는 점을 표시하세요. 결과 개수가 충분해도 근사 검색이 정확 순위를 보증하지는 않습니다.

검색: 단위가 다른 점수를 합칠 때 순위를 사용하기

bm25의 관련도와 벡터 거리는 같은 숫자 척도가 아닙니다. RRF는 점수를 직접 더하지 않고 각 목록의 순위를 사용합니다. docs/user/search/index.md의 기본값은 k=60입니다. 아래 식의 r은 1부터 시작하는 순위입니다.

RRF(d) = Σ 1 / (60 + r_i(d))

문서 A: 단어 검색 1위, 벡터 검색 5위
문서 B: 단어 검색 4위, 벡터 검색 2위

A = 1/61 + 1/65 ≈ 0.03178
B = 1/64 + 1/62 ≈ 0.03175

작은 실습: 두 검색이 같은 문서를 서로 다른 위치에 둘 때 k를 바꾸며 순위 민감도를 계산하세요. 그래프 필터를 언제 적용하는지도 따로 적어야 합니다. RRF 안의 벡터 검색은 top-k 창이라는 한계가 남습니다.

보안·API: 동일 규칙을 여러 입구에서 유지하기

omnigraph-policy의 PolicyChecker는 엔진과 정책 구현 사이의 경계입니다. 서버의 /mcp 어댑터도 같은 HTTP 처리 계층과 인증·수용 제어를 사용하며, MCP crate 자체가 그래프를 별도로 열어 쓰지 않습니다.

작은 실습: “토큰 없음”, “인증은 됐지만 권한 없음”, “정책이 있는데 엔진 행위자 없음”의 세 사례를 입력→검사 위치→거부 이유 표로 만드세요. HTTP 상태 코드와 내부 오류 타입을 같은 개념으로 섞지 않는 연습입니다.

테스트: 결과만이 아니라 장애 창과 비용도 검증하기

GQT 파일은 --- schema·--- seed·--- query·--- expect 계열 구획으로 입력과 기대 결과를 표현합니다. 일부 사례는 결과 타입과 실행 계획까지 검증합니다. crates/omnigraph-gqt/cases/v2/planner/switch_ran_on_the_report.gqt는 hash_join과 indexed_scan 중 무엇이 실행됐는지도 확인합니다.

DST는 하나의 시드에서 스케줄·시간·ID·저장소 장애를 만들어 실패를 재현합니다. 다만 crates/omnigraph-dst/README.md는 실제 시간의 동시 실행과 프로세스 강제 종료 사례까지 모두 정확 재생된다고 주장하지 않습니다. 재현 가능 범위를 명시하는 태도를 배울 수 있습니다.

좋은 테스트는 정상 결과뿐 아니라, 실패한 순간 무엇이 보이고 어떤 작업이 끝나지 않았는지까지 설명합니다.

작은 실습: crates/omnigraph/tests/detached_commit_matrix.rs의 “테이블 준비 후·공개 전”과 crates/omnigraph/tests/failpoints.rs의 “공개 후·응답 유실” 사례를 비교해 기대 상태를 적으세요. 저장소 요청 비용을 기록한 crates/omnigraph-dst/cost_table.txt와 비교하면 결과의 정당성과 비용 계약도 구분할 수 있습니다.

7하드웨어 / 시스템 요구사항

공식 문서에서 확인할 수 있는 조건

컨테이너 기본 이미지가 Debian bookworm이라고 해서 배포 아카이브도 그 환경에 호환된다는 뜻은 아닙니다. Dockerfile은 빌드된 바이너리를 복사하며, 주석은 이미지와 바이너리의 glibc 조합을 맞추도록 설명합니다. 컨테이너 배포와 아카이브 설치의 조건을 구분하세요.

소스의 기본 예산으로 감 잡기

출처는 crates/omnigraph-compiler/src/settings.rs::DEFINITIONS입니다. 같은 파일이 설정 이름·범위·기본값·환경 변수 대응을 함께 선언하므로, 문서 표와 구현을 비교하기 좋은 구조입니다.

쿼리 하나의 메모리 예산은 서버 프로세스 전체의 메모리 상한이 아닙니다. 예산을 끝까지 쓰는 쿼리가 10개 동시에 실행되면 추적 대상만 산술적으로 약 1.46 GiB입니다. 여기에 캐시·그래프 인덱스·네이티브 버퍼·입력·런타임 비용이 더해집니다. 이 계산은 용량을 보장하는 측정 결과가 아닙니다.

.cargo/config.toml은 Cargo가 띄우는 개발 프로세스에 LANCE_MEM_POOL_SIZE=1073741824(1 GiB)를 제공합니다. 이 값은 제품 바이너리에 영구히 박히는 설정이 아니며, 위의 쿼리별 예산과도 다른 풀입니다.

CSR 배열만 보면 한 방향에서 대략 4 × (노드 수 + 1) + 4 × 간선 수바이트입니다. 노드 100만·간선 1,000만이면 약 42 MiB이지만, 이는 u32 배열 두 개만의 산술값입니다. 문자열 ID 사전·역방향·타입별 구조·구축 임시 메모리는 포함하지 않습니다.

처음에는 기존 64비트 개발 기기와 수십 개 노드로 흐름을 익히고, 이후 데이터·질의·동시성을 고정해 측정하세요. 기본 쿼리 실습에 임베딩 API나 클라우드 저장소를 먼저 연결할 필요는 없습니다. Azure 쓰기는 admission 래퍼가 필요한 별도 검증 프리뷰 범위입니다.

8직접 해볼 수 있는 실습 과제

아래 명령은 docs/user/quickstart.md의 CLI 계약에 맞춘 실습 예시입니다. omnigraph CLI가 설치된 환경에서 별도의 로컬 연습 디렉터리를 사용하세요. 출력 설명은 예상 결과와 확인 기준이며, 소스 커밋의 동작을 이해하기 위한 것입니다.

각 과제의 완료 기준은 명령이 끝나는 것이 아니라, 결과가 왜 그렇게 나왔는지 소스와 연결해 설명하는 것입니다.

{"type":"Claim","data":{"slug":"lower-latency","statement":"마이그레이션 뒤 지연 시간이 줄었다."}}
{"type":"Source","data":{"slug":"load-test","title":"부하 테스트 보고서"}}
{"type":"Source","data":{"slug":"production-metrics","title":"운영 지표"}}
{"edge":"Supports","from":"load-test","to":"lower-latency"}
{"edge":"Supports","from":"production-metrics","to":"lower-latency"}

omnigraph init --schema schema.pg graph.omni
omnigraph load --data evidence.jsonl --mode overwrite --target ./graph.omni

query sources_for_claim($claim: String) {
  match {
    $source: Source
    $claim_node: Claim { slug: $claim }
    $source supports $claim_node
  }
  return { $source.title as source }
  order { source asc }
}

omnigraph query sources_for_claim --query queries.gq \
  --params '{"claim":"lower-latency"}' --format table --target ./graph.omni

{"type":"Source","data":{"slug":"independent-benchmark","title":"독립 벤치마크"}}
{"edge":"Supports","from":"independent-benchmark","to":"lower-latency"}

omnigraph branch create review/add-benchmark --target ./graph.omni
omnigraph load --data benchmark.jsonl --mode append \
  --branch review/add-benchmark --target ./graph.omni
omnigraph query sources_for_claim --query queries.gq \
  --params '{"claim":"lower-latency"}' --branch main --target ./graph.omni
omnigraph query sources_for_claim --query queries.gq \
  --params '{"claim":"lower-latency"}' \
  --branch review/add-benchmark --target ./graph.omni
omnigraph branch merge review/add-benchmark --into main \
  --dry-run --json --target ./graph.omni
omnigraph branch merge review/add-benchmark --into main --target ./graph.omni

# title-main.jsonl
{"type":"Source","data":{"slug":"load-test","title":"부하 테스트 요약"}}

# title-review.jsonl
{"type":"Source","data":{"slug":"load-test","title":"수정된 부하 보고서"}}

omnigraph branch create review/title --target ./graph.omni
omnigraph load --data title-main.jsonl --mode merge \
  --branch main --target ./graph.omni
omnigraph load --data title-review.jsonl --mode merge \
  --branch review/title --target ./graph.omni
omnigraph branch merge review/title --into main \
  --dry-run --json --target ./graph.omni

9관련 기술 심화 학습 로드맵

Rust를 처음 배우는 독자라면 소유권·참조·열거형·Result·기본 비동기 문법을 먼저 익히세요. 아래 주차는 속도 경쟁이 아니라, 매 단계에서 설명할 수 있어야 하는 결과물을 기준으로 잡았습니다.

매주 읽은 코드의 입력·불변식·실패 결과를 한 장으로 남기면, 다른 데이터 시스템에도 옮겨 쓸 수 있는 설계 지식이 됩니다.

난도가 높을 때의 우회 경로

• 비동기 코드가 어렵다면: 먼저 CsrIndex의 순수 배열 연산과 컴파일러의 타입 구조를 읽습니다.
• 스토리지 용어가 어렵다면: 테이블 버전·그래프 커밋·브랜치 이름을 서로 다른 색으로 그려 봅니다. 같은 숫자라고 같은 객체가 아닙니다.
• 테스트가 너무 많다면: GQT 한 사례의 스키마·입력·기대 행부터 읽고, 이후 그 동작을 구현한 함수로 이동합니다.
• 성능이 궁금하다면: 먼저 요청 수·읽은 바이트·처리 행·메모리 예산을 정합니다. 스타 수나 저장소 크기로 속도를 예측하지 않습니다.

심화 단계에서는 docs/rfcs/0047-search-plan-truth.md와 docs/rfcs/README.md에서 검색 계획의 의미 보존에 관한 설계 논의를 찾아보세요. 현재 규약은 개발 가이드, 결정의 이유는 RFC, 정확한 예외는 코드와 테스트에서 확인하는 습관을 들이는 편이 좋습니다.

10핵심 키워드 사전

헷갈리기 쉬운 세 쌍은 그래프 브랜치와 Lance native ref, 정책 인가와 쓰기 소유권 admission, 결과 개수 충족과 ANN 순위 정확성입니다. 서로 관련은 있지만 같은 계약이 아닙니다.

11참고 링크

공식 저장소와 사용자 문서

• ModernRelay/omnigraph — 공식 저장소와 README
• 분석 기준 커밋 484e334의 파일 트리 — 이후 main의 변경과 구분할 기준
• v0.14.0 릴리스 — 최신 배포판
• 빠른 시작 · 설치·클라이언트 호환
• 스키마 언어 · 쿼리 언어
• 검색과 후보 확장 정책 · 로드 실행 계획 해설
• 병합과 충돌·미리보기 · 배포와 시스템 설정
• 아키텍처 · 설계 불변식 · 테스트 지도
• 공식 Cookbooks — 다른 도메인의 스키마·데이터 예시
• TypeScript SDK — 별도 릴리스의 호환 상태 확인

본문의 핵심 소스 바로 읽기

• Cargo.toml · Cargo.lock — 선언과 실제 버전 비교
• 쿼리 입구 · 계획의 값 바인딩
• AcceptedPlan과 검증 범위 · 최적화와 removal 결정
• ManifestCoordinator · 공개 트랜잭션
• 세 방향 병합 · TypeIndex와 CsrIndex
• 엔진 정책 검사 · 서버 인증과 라우팅
• 설정·기본 예산 · 공개 전 장애 검증 행렬
• CI · 컨테이너 · RFC 목차

기반 기술을 더 공부하려면

• Rust 공식 책 — 소유권·열거형·오류 처리
• Tokio 공식 입문 — 비동기 작업과 공유 상태
• Arrow 열 기반 형식 · DataFusion — 저장 표현과 실행 엔진
• Lance 형식 · 트랜잭션 · 브랜치·태그 형식
• Lance 브랜치 운영 — 단일 데이터셋의 참조와 그래프 전체의 참조를 구분해 읽기
• Cedar 공식 사이트 · MCP 공식 문서

Lance 문서의 데이터셋 버전·태그 개념은 기반 저장 계층을 이해하는 자료입니다. 여러 데이터셋의 그래프 공개 계약은 omnigraph의 카탈로그가 추가하므로, 두 문서를 동일한 수준의 보장으로 읽지 않아야 합니다. 의존성의 실제 동작을 추적할 때는 13.0.0 버전도 함께 확인하세요.

현재 상태 (2026-10-23 확인)