CSV Export Format for Loading Data into KuzuDB in GitNexus: Complete Schema Guide

GitNexus exports repository knowledge graphs to KuzuDB using a hybrid schema with dedicated node tables for each code element type and a unified CodeRelation table for all edges, generating RFC 4180-compliant CSV files that use KuzuDB array literal syntax for complex fields.

GitNexus is an open-source tool that extracts knowledge graphs from Git repositories and persists them in KuzuDB, an embeddable graph database. Understanding the CSV export format for loading data into KuzuDB is essential for bulk importing repository analytics, debugging graph structures, or integrating with external data pipelines. The export generator is implemented in csv-generator.ts and derives its column structure from the schema definitions in schema.ts.

Hybrid Schema Architecture for KuzuDB Export

GitNexus employs a hybrid schema design that balances normalization with query performance. Each code-element type receives its own dedicated node table—such as File, Function, or Class—while all relationships are consolidated into a single CodeRelation edge table. This approach allows KuzuDB to enforce type-specific properties on nodes while maintaining a flexible graph structure for edges.

Node Table CSV Specifications

The CSV export generates separate files for each node table defined in schema.ts. All node CSVs follow the same RFC 4180 compliance rules but vary in column structure based on the entity type.

File and Folder Nodes

The File table stores repository files with content truncated at 10 KB to prevent oversized CSV fields:

id,name,filePath,content

The Folder table uses a reduced schema without content fields:

id,name,filePath

Code Element Nodes

Function, Class, Interface, Method, and generic CodeElement tables share a unified schema that captures source location and export status:

id,name,filePath,startLine,endLine,isExported,content

The content field contains the code snippet with surrounding context, or an empty string if unavailable.

Community and Process Nodes

Community nodes—generated by Leiden clustering—include metrics and keyword arrays:

id,label,heuristicLabel,keywords,description,enrichedBy,cohesion,symbolCount

The keywords field uses KuzuDB array literal syntax (e.g., ['parser','ast']) and is quoted as a single CSV field.

Process nodes represent execution flows and reference multiple communities:

id,label,heuristicLabel,processType,stepCount,communities,entryPointId,terminalId

The communities field follows the same array literal format as keywords.

The CodeRelation Edge Table

All graph relationships are exported to a single CodeRelation CSV that links any two node tables via internal IDs:

from,to,type,confidence,reason,step

• from and to: Source and target node IDs.
• type: Relationship type (e.g., CALLS, CONTAINS, IMPORTS).
• confidence: A 0–1 double value used primarily for CALLS edges to indicate static analysis certainty.
• reason: Human-readable explanation of why the edge exists.
• step: Integer sequence number for process-step relationships.

CSV Compliance and Array Syntax

The generator in csv-generator.ts enforces strict RFC 4180 compliance:

• All fields are always quoted using double quotes ("value").
• Internal double quotes are escaped by doubling them ("").
• UTF-8 sanitization removes illegal control characters.
• Line endings are normalized to \n before quoting.

Array handling follows KuzuDB’s literal syntax. Arrays like ['kw1','kw2'] are treated as single string values and wrapped in CSV quotes to prevent delimiter collision.

Generating Export Files with csv-generator.ts

To produce the CSV files programmatically, import generateAllCSVs from csv-generator.ts and pass the knowledge graph and file contents map:

import { generateAllCSVs } from './core/kuzu/csv-generator';
import { KnowledgeGraph } from './core/graph/types';

// Assume `graph` is the in-memory knowledge graph
// and `fileContents` maps absolute paths → file text.
const csvData = generateAllCSVs(graph, fileContents);

// Write each node CSV to a file (example for Node tables)
for (const [tableName, csv] of csvData.nodes.entries()) {
  // e.g. writeFile(`${tableName}.csv`, csv);
  console.log(`--- ${tableName}.csv ---\n${csv.slice(0, 200)}\n`);
}

// Relation CSV
// e.g. writeFile('CodeRelation.csv', csvData.relCSV);
console.log('--- CodeRelation.csv ---\n', csvData.relCSV.slice(0, 200));

The function returns an object containing nodes (a Map of table names to CSV strings) and relCSV (the single edge table CSV).

Bulk Loading CSVs into KuzuDB

Once exported, the CSV files can be bulk-loaded into KuzuDB using the COPY FROM command. Execute these SQL statements in order—node tables first, then the relation table:

COPY File FROM 'File.csv' (HEADER);
COPY Folder FROM 'Folder.csv' (HEADER);
COPY Function FROM 'Function.csv' (HEADER);
COPY Class FROM 'Class.csv' (HEADER);
COPY Interface FROM 'Interface.csv' (HEADER);
COPY Method FROM 'Method.csv' (HEADER);
COPY CodeElement FROM 'CodeElement.csv' (HEADER);
COPY Community FROM 'Community.csv' (HEADER);
COPY Process FROM 'Process.csv' (HEADER);

-- Load edges last after all nodes exist
COPY CodeRelation FROM 'CodeRelation.csv' (HEADER);

The HEADER option tells KuzuDB to skip the first row and use it for column mapping.

Summary

• GitNexus uses a hybrid schema with separate node tables for each code element type and a single CodeRelation table for all edges.
• CSV exports in csv-generator.ts strictly follow RFC 4180: always quoted fields, escaped double quotes, and normalized line endings.
• Array fields (keywords, communities) use KuzuDB literal syntax (['item1','item2']) wrapped as single quoted CSV values.
• The File table truncates content at 10 KB, while code elements include line numbers and export status.
• Bulk load via KuzuDB’s COPY FROM command, importing node tables before the CodeRelation edge table.

Frequently Asked Questions

How does GitNexus handle large file contents in CSV exports?

GitNexus truncates file content at 10 KB during CSV generation to prevent oversized fields. The content column in the File table contains the truncated text, while the filePath column preserves the full reference for external access. This limit is enforced in csv-generator.ts during the string sanitization phase.

What is the correct format for array fields like keywords and communities?

Array fields use KuzuDB array literal syntax rendered as strings: ['kw1','kw2']. The CSV generator wraps this entire expression in double quotes to prevent comma delimiters from splitting the field. For example, a Community node's keywords field appears as "['parser','ast','traversal']" in the CSV file.

Can I modify the CSV schema without breaking KuzuDB imports?

Any schema changes require synchronized updates to both schema.ts and csv-generator.ts. The generator derives column lists directly from schema constants, so modifying the schema definitions automatically propagates to the CSV headers. However, altering table names or array field formats requires corresponding changes to the KuzuDB COPY FROM statements to prevent load failures.

Why does GitNexus use a single CodeRelation table instead of separate edge tables?

GitNexus consolidates all relationships into the CodeRelation table to simplify the graph schema and reduce join complexity. This design allows heterogeneous relationships (e.g., CALLS, CONTAINS, IMPORTS) to coexist in one table with standardized columns (from, to, type, confidence, reason, step), making bulk imports and schema migrations more manageable.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}