Code-Graph-RAG Schema Relationships: Complete Guide to the 30+ Edge Types in codec/schema.proto

The Code‑Graph‑RAG schema defines 30 directed relationship types in the RelationshipType enum within codec/schema.proto at lines 1335–1369, modeling containment hierarchies (CONTAINS_PACKAGE), code semantics (CALLS, INHERITS), and quality metrics (HAS_VULNERABILITY, HAS_SMELL).

The Code‑Graph‑RAG system by vitali87/code-graph-rag persists codebases as property graphs using a Protocol Buffer schema. At the heart of this model lies the Relationship message, which leverages the RelationshipType enum to create typed edges between nodes such as Projects, Functions, Classes, and SecurityIssues. These Code‑Graph‑RAG schema relationships power static analysis, cross-reference navigation, and retrieval-augmented generation (RAG) queries against software repositories.

The Relationship Message Structure

According to the source code in codec/schema.proto, every edge in the graph is stored as a Relationship protobuf message containing six fields that capture both connectivity and metadata:

message Relationship {
  RelationshipType type = 1;          // Edge classification enum
  string source_id = 2;               // Primary key of source node
  string target_id = 3;               // Primary key of target node
  google.protobuf.Struct properties = 4; // Optional edge attributes
  string source_label = 5;            // Node label (e.g., "Function")
  string target_label = 6;            // Node label (e.g., "Method")
}

The source_id and target_id fields establish the directed link, while source_label and target_label store the node types for quick indexing without requiring a JOIN operation. The properties field accepts arbitrary key-value data via google.protobuf.Struct, allowing storage of line numbers, confidence scores, or analysis metadata directly on the edge.

Containment and Hierarchy Relationships

The schema uses explicit containment edges to mirror filesystem and module organization. These relationships form the backbone of the graph topology:

• CONTAINS_PACKAGE — Links a Project node to a Package node, representing top-level organizational units.
• CONTAINS_FOLDER — Connects a Project or Package to a Folder, enabling nested directory structures.
• CONTAINS_FILE — Associates a Folder with a File leaf node.
• CONTAINS_MODULE — Links Folders or Packages to Module nodes, representing importable language units.
• CONTAINS_SECTION — Associates Files or Documents with Section nodes (e.g., markdown headings) for documentation-aware RAG.

Definition and Type System Relationships

These edges encode how code entities define or implement other entities, critical for call-graph and inheritance analysis:

• DEFINES — A polymorphic edge where Modules, Classes, Interfaces, Enums, Types, Unions, Patterns, CodeSmells, or SecurityIssues define corresponding child entities (Functions, Methods, Classes, etc.).
• DEFINES_METHOD — A specialized variant linking Class nodes to Method nodes.
• IMPLEMENTS — Connects a Class to an Interface it implements.
• IMPLEMENTS_MODULE — Links a ModuleImplementation to its ModuleInterface contract.
• INSTANTIATES — Records when a Class constructs an instance of another Class via constructor calls.
• IMPLEMENTS_PATTERN — Associates a Method with an ast-grep Pattern match (e.g., specific code idioms).

Inheritance and Polymorphism Relationships

Object-oriented relationships are explicitly modeled to support hierarchy queries:

• INHERITS — Directed edge from a Class or Interface to its parent Class or Interface.
• OVERRIDES — Links a Method to the parent method it overrides, enabling precise polymorphism tracking.
• EXPORTS — Connects a Module or File to exported Functions, Classes, or Variables.
• EXPORTS_MODULE — Represents re-export patterns where one Module forwards another Module.

Dependency and Invocation Relationships

These edges trace runtime and compile-time dependencies between entities:

• CALLS — Indicates a Function or Method invokes another Function, Method, or Class constructor.
• IMPORTS — Records when a Module imports another Module or external dependency.
• DEPENDS_ON_EXTERNAL — Links a Project to an ExternalPackage (third-party libraries).
• REFERENCES — Captures type hints, imports, or symbolic references between entities.
• RESOLVES_TO — Connects a Reference node to its resolved target node after import resolution.

Data Flow and Resource Relationships

For security and data-flow analysis, the schema includes I/O and flow-tracking edges:

• READS_FROM — Indicates a Function or Method reads from a Resource (files, network endpoints).
• WRITES_TO — Indicates a Function or Method writes to a Resource.
• FLOWS_TO — Represents data-flow analysis edges between Functions or Methods.
• RETURNS — Type-level edge from a Function/Method to its return Type annotation.
• ACCEPTS — Type-level edge from a Function/Method to its parameter Type annotations.

Code Quality and Security Relationships

The schema supports static analysis by linking code entities to quality metrics:

• HAS_SMELL — Connects Functions, Classes, or Methods to CodeSmell nodes (detected anti-patterns).
• HAS_VULNERABILITY — Links code entities to SecurityIssue nodes for vulnerability tracking.
• EXPOSES — Indicates a Class or Module publicly exposes a Member via its public API surface.
• LINKS_TO — General-purpose edge for documentation links or arbitrary cross-references.

Working with Relationships in Python

The generated Python bindings in codec/schema_pb2.py enable programmatic construction of relationship edges. To create a CALLS relationship between two functions:

from codec import schema_pb2 as schema

# Construct a relationship: my_func calls helper_func

calls_rel = schema.Relationship(
    type=schema.Relationship.CALLS,
    source_id="pkg.module.my_func",
    target_id="pkg.module.helper_func",
    source_label="Function",
    target_label="Function",
)

# Serialize to binary for storage

binary_data = calls_rel.SerializeToString()

To persist the relationship into a graph index file:

from codec import schema_pb2 as schema

index = schema.GraphCodeIndex()
index.relationships.append(calls_rel)

# Write to protobuf binary file

with open("codegraph.pb", "wb") as f:
    f.write(index.SerializeToString())

Querying Relationships in Memgraph

Once loaded into Memgraph (the supported graph database), relationships enable complex Cypher queries. To find all functions called by my_func that have security vulnerabilities:

MATCH (src:Function)-[r:CALLS]->(tgt:Function)
WHERE src.name = "my_func"
MATCH (tgt)-[:HAS_VULNERABILITY]->(vuln:SecurityIssue)
RETURN src.name, tgt.name, vuln.severity

Key Source Files for Relationship Handling

File	Role
codec/schema.proto	Defines the Relationship message and RelationshipType enum (lines 1335–1369).
codec/schema_pb2.py	Generated Python bindings for protobuf message construction.
codebase_rag/graph_loader.py	Loads .pb files and hydrates graph objects for analysis.
codebase_rag/graph_updater.py	Constructs and updates Relationship instances during codebase ingestion.
codebase_rag/graph_cli.py	Command-line interface for dumping and querying relationship edges.

Summary

• 30 relationship types are defined in the RelationshipType enum within codec/schema.proto at lines 1335–1369.
• Containment edges (CONTAINS_PACKAGE, CONTAINS_FILE) model filesystem and module hierarchies.
• Semantic edges (CALLS, INHERITS, IMPLEMENTS) enable call-graph and inheritance analysis.
• Quality edges (HAS_SMELL, HAS_VULNERABILITY) link code entities to static analysis findings.
• Data-flow edges (READS_FROM, WRITES_TO, FLOWS_TO) support security and resource tracking.
• Python bindings in codec/schema_pb2.py allow programmatic creation and serialization of relationships.
• Memgraph integration enables Cypher queries against the relationship graph for RAG applications.

Frequently Asked Questions

What is the RelationshipType enum in the Code-Graph-RAG schema?

The RelationshipType enum is a Protocol Buffer enumeration defined at lines 1335–1369 of codec/schema.proto that specifies 30 possible edge types for the graph. Each variant (such as CALLS, INHERITS, or CONTAINS_FILE) represents a directed semantic relationship between two code entities, allowing the system to model everything from filesystem containment to method overriding and security vulnerability detection.

How do I create a relationship instance in Python using the schema?

Import the generated schema_pb2 module from the codec package and instantiate the Relationship class. Set the type field using the enum (e.g., schema.Relationship.CALLS), provide unique source_id and target_id strings, and specify source_label and target_label for the node types. Finally, call SerializeToString() to produce binary data for storage in a .pb file.

What is the difference between DEFINES and DEFINES_METHOD relationships?

DEFINES is a polymorphic relationship used when a Module, Class, Interface, Enum, Type, or other container defines any child entity (Functions, Classes, Patterns, etc.). DEFINES_METHOD is a specialized edge reserved exclusively for Class nodes defining Method nodes, providing a more specific semantic link that simplifies inheritance and override detection queries.

Which graph database does Code-Graph-RAG use for relationship queries?

The system is designed to integrate with Memgraph, a high-performance in-memory graph database. The Relationship protobuf structure maps directly to Memgraph nodes and edges, allowing Cypher queries that traverse the source_id and target_id connections. The CLI tools in codebase_rag/graph_cli.py provide utilities for loading the protobuf index into Memgraph and executing relationship queries.

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