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

> Explore the vital code graph schema relationships in Code-Graph-RAG. Understand 30+ edge types like CONTAINS PACKAGE, CALLS, INHERITS, HAS VULNERABILITY, and HAS SMELL for better code analysis.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: deep-dive
- Published: 2026-09-08

---

**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:

```proto
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`](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema_pb2.py) enable programmatic construction of relationship edges. To create a `CALLS` relationship between two functions:

```python
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:

```python
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:

```cypher
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`](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema_pb2.py) | Generated Python bindings for protobuf message construction. |
| [`codebase_rag/graph_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py) | Loads `.pb` files and hydrates graph objects for analysis. |
| [`codebase_rag/graph_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_updater.py) | Constructs and updates `Relationship` instances during codebase ingestion. |
| [`codebase_rag/graph_cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_cli.py) provide utilities for loading the protobuf index into Memgraph and executing relationship queries.