# GitNexus KuzuDB Graph Schema: A Complete Technical Guide

> Explore the GitNexus KuzuDB graph schema. Learn how this hybrid model stores code elements in dedicated tables and efficiently routes relationships through a single edge table called CodeRelation.

- Repository: [Abhigyan Patwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus)
- Tags: technical-guide
- Published: 2026-03-08

---

**GitNexus uses a hybrid KuzuDB graph schema that stores code elements in dedicated node tables while routing all relationships through a single generic edge table called `CodeRelation`.**

The KuzuDB graph schema powers GitNexus's ability to map complex codebases across multiple programming languages. Defined entirely in [`gitnexus/src/core/kuzu/schema.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/kuzu/schema.ts), this schema creates a type-safe graph structure that supports both structural relationships and semantic vector search.

## Core Components of the GitNexus KuzuDB Graph Schema

### Node Tables: Code Element Entities

The schema defines **dedicated node tables** for every code element type, providing strongly-typed storage for repository entities. Core tables include `File`, `Folder`, `Function`, `Class`, `Interface`, `Method`, `CodeElement`, `Community`, and `Process`.

Beyond these core entities, the KuzuDB graph schema supports **18 language-specific tables** for multi-language repositories. These include `Struct`, `Enum`, `Macro`, `Trait`, `Impl`, `Namespace`, `Package`, `Module`, and other constructs required for C, C++, Rust, Go, Java, C#, and additional languages.

Each node table schema includes element-specific columns such as `startLine`, `endLine`, `isExported`, `filePath`, and `content`, enabling precise source-code mapping.

### The CodeRelation Edge Table

All relationships in the GitNexus KuzuDB graph schema flow through a **single generic relation table** named `CodeRelation`. This hybrid approach simplifies the graph model while maintaining expressiveness.

The `CodeRelation` table stores edge metadata including:
- `type`: The relationship category
- `confidence`: Numerical confidence score
- `reason`: Explanation for the relationship
- `step`: Process step identifier

**Supported relationship types** include:
- `CONTAINS` – Hierarchical containment
- `DEFINES` – Definition relationships
- `IMPORTS` – Dependency imports
- `CALLS` – Function/method invocations
- `EXTENDS` – Inheritance relationships
- `IMPLEMENTS` – Interface implementations
- `MEMBER_OF` – Membership associations
- `STEP_IN_PROCESS` – Workflow step relationships

The schema definition in [`gitnexus/src/core/kuzu/schema.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/kuzu/schema.ts) includes a comprehensive `CREATE REL TABLE` statement enumerating every allowed `FROM … TO …` pair across all node tables.

### Semantic Search with CodeEmbedding

The KuzuDB graph schema includes a dedicated **`CodeEmbedding`** table for vector storage, isolating high-dimensional embeddings from the main graph structure to avoid copy-on-write overhead.

Key characteristics:
- Stores `nodeId` references and 384-dimensional `FLOAT` vectors
- Supports Kuzu's HNSW index with cosine similarity for fast approximate nearest neighbor search
- Enables semantic code search across the repository graph

## Schema Definition and Creation Order

### DDL Statements in schema.ts

The [`gitnexus/src/core/kuzu/schema.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/kuzu/schema.ts) module exports complete DDL strings for every component:

- `FILE_SCHEMA`, `FUNCTION_SCHEMA`, `CLASS_SCHEMA`, etc. – Individual node table creation statements
- `RELATION_SCHEMA` – The massive relationship table DDL connecting all node types
- `EMBEDDING_SCHEMA` – Vector table definition
- `CREATE_VECTOR_INDEX_QUERY` – HNSW index creation with cosine metric

### Ordered Execution with SCHEMA_QUERIES

The schema guarantees correct initialization through **`SCHEMA_QUERIES`**, an ordered array that executes DDL in dependency-safe sequence:

1. **Node table creation** – All `CREATE NODE TABLE` statements execute first
2. **Relation table creation** – `CREATE REL TABLE` runs after nodes exist
3. **Embedding table creation** – Vector storage initialization
4. **Index creation** – HNSW vector index built last

This ordering prevents "table not found" errors during repository indexing, as implemented in the connection pool at [`gitnexus/src/mcp/core/kuzu-adapter.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/core/kuzu-adapter.ts).

## Working with the Schema: Practical Examples

### Initializing the Database

Use the Kuzu adapter to initialize the schema in your target database:

```typescript
import { initKuzu, executeQuery } from './gitnexus/src/mcp/core/kuzu-adapter.js';
import {
  SCHEMA_QUERIES,
  CREATE_VECTOR_INDEX_QUERY,
} from './gitnexus/src/core/kuzu/schema.js';

const dbPath = '/tmp/gitnexus-db/kuzu.db';
const repoId = 'my-repo';

// Initialize connection pool (opens DB read-only)
await initKuzu(repoId, dbPath);

// Execute schema creation in dependency order
for (const ddl of SCHEMA_QUERIES) {
  await executeQuery(repoId, ddl);
}

// Create HNSW vector index for semantic search
await executeQuery(repoId, CREATE_VECTOR_INDEX_QUERY);

```

### Inserting Code Elements

Insert a function node with its metadata:

```typescript
const INSERT_FUNCTION = `
  CREATE (:Function {
    id: $id,
    name: $name,
    filePath: $filePath,
    startLine: $start,
    endLine: $end,
    isExported: $exported,
    content: $content,
    description: $desc
  })
`;

await executeQuery(repoId, INSERT_FUNCTION, {
  id: 'fn-123',
  name: 'authenticateUser',
  filePath: 'src/auth.ts',
  start: 15,
  end: 42,
  exported: true,
  content: 'function authenticateUser(...) { ... }',
  desc: 'Validates user credentials against database',
});

```

### Querying Relationships

Traverse `CALLS` relationships between functions:

```typescript
const CALLS_QUERY = `
  MATCH (caller:Function)-[r:CodeRelation {type: 'CALLS'}]->(callee:Function)
  WHERE caller.id = $callerId
  RETURN callee.name AS functionName, 
         callee.filePath AS location, 
         r.confidence AS confidence
`;

const results = await executeQuery(repoId, CALLS_QUERY, { 
  callerId: 'fn-123' 
});
console.log('Functions called by fn-123:', results);

```

### Performing Semantic Search

Execute vector similarity search using the embedding table:

```typescript
import { EMBEDDING_TABLE_NAME } from './gitnexus/src/core/kuzu/schema.js';

// Assume queryVector is a Float32Array[384] generated from your embedding model
const SEMANTIC_SEARCH = `
  CALL ANN('knn', '${EMBEDDING_TABLE_NAME}', '${queryVector}', 
           topK := 5, metric := 'cosine')
`;

const similarNodes = await executeQuery(repoId, SEMANTIC_SEARCH);
console.log('Semantically similar code elements:', similarNodes);

```

## Summary

- **GitNexus implements a hybrid KuzuDB graph schema** that stores code elements in type-specific node tables while routing all relationships through a single `CodeRelation` edge table.
- **The schema supports 27+ node types** including core entities (`File`, `Function`, `Class`) and 18 language-specific tables for multi-language repository analysis.
- **Relationship types** include `CONTAINS`, `DEFINES`, `CALLS`, `IMPORTS`, `EXTENDS`, `IMPLEMENTS`, `MEMBER_OF`, and `STEP_IN_PROCESS`.
- **Semantic search capabilities** are provided through the `CodeEmbedding` table with 384-dimensional vectors and HNSW index support using cosine similarity.
- **Schema initialization follows a strict order** defined in `SCHEMA_QUERIES`: node tables first, then relations, then embeddings, preventing dependency errors during database setup.

## Frequently Asked Questions

### What file defines the KuzuDB graph schema in GitNexus?

The complete schema definition resides in [`gitnexus/src/core/kuzu/schema.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/kuzu/schema.ts). This TypeScript module exports all DDL statements, table names, and the ordered `SCHEMA_QUERIES` array used to initialize the database.

### How does GitNexus handle relationships between different code elements?

GitNexus uses a **single generic relation table** named `CodeRelation` that connects all node types. Rather than creating separate edge tables for each relationship type, the schema stores the relationship category in a `type` property within the `CodeRelation` table, supporting values like `CALLS`, `IMPORTS`, and `CONTAINS`.

### Can GitNexus analyze repositories in programming languages other than TypeScript?

Yes. While GitNexus is written in TypeScript, its **KuzuDB graph schema includes 18 language-specific node tables** designed to support C, C++, Rust, Go, Java, C#, and other languages. These tables extend the core schema to capture language-specific constructs like `Struct`, `Enum`, `Macro`, `Trait`, and `Module`.

### How does the schema support semantic code search?

The schema includes a dedicated **`CodeEmbedding` node table** that stores 384-dimensional floating-point vectors for code elements. Combined with the `CREATE_VECTOR_INDEX_QUERY` that builds an HNSW index using cosine similarity, this enables fast approximate nearest neighbor searches for semantic code retrieval across the repository graph.