# Understanding the Key Relationships in the Code-Graph-RAG Graph Schema

> Explore the vital relationships within the Code-Graph-RAG graph schema, from containment to call graphs, connecting your code's structure in a Protocol Buffers knowledge graph.

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

---

**The Code-Graph-RAG graph schema defines 17 distinct relationship types—from containment hierarchies to call graphs—that connect nodes representing projects, packages, modules, classes, and functions within a Protocol Buffers-based knowledge graph.**

The **vitali87/code-graph-rag** repository transforms software codebases into navigable semantic graphs using a strictly typed Protocol Buffers schema. At the heart of this system lies the `Relationship` message defined in [`codec/schema.proto`](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema.proto), which enumerates exactly how different code entities interconnect to enable sophisticated retrieval-augmented generation (RAG) over source code.

## Containment Hierarchy Relationships

The schema models physical and logical nesting through four primary containment edges. These relationships form the hierarchical backbone of the graph, connecting high-level organizational units down to individual files and modules.

- **CONTAINS_PACKAGE**: Connects a **Project** node to a **Package** node, representing that a project logically contains one or more packages.
- **CONTAINS_FOLDER**: Links a **Project** to a **Folder**, modeling directory structures within the codebase.
- **CONTAINS_FILE**: Associates a **Folder** (or Project) with a **File**, representing file system containment.
- **CONTAINS_MODULE**: Connects a **Folder** or **Package** to a **Module**, indicating that a specific module lives within that organizational boundary.

## Definition and Inheritance Relationships

These edges capture object-oriented semantics, type definitions, and polymorphic behavior. They enable the graph to represent not just structure, but meaning and inheritance chains.

- **DEFINES**: A versatile relationship connecting **Module**, **Class**, or **Interface** nodes to the entities they define, including **Function**, **Method**, **Class**, **Enum**, or **Type** nodes.
- **DEFINES_METHOD**: Specifically links a **Class** or **Interface** to a **Method** it declares, distinguishing it from other definition types.
- **INHERITS**: Creates edges between **Class** nodes to represent class inheritance hierarchies (source inherits from target).
- **IMPLEMENTS**: Connects a **Class** to an **Interface** that it implements.
- **OVERRIDES**: Links a **Method** to another **Method** in a parent class that it overrides, enabling analysis of polymorphic behavior.

## Dependency and Interaction Relationships

These relationships model cross-module dependencies, external library usage, and runtime interactions. They are critical for understanding coupling and building accurate call graphs.

- **IMPORTS**: Connects a **Module** to another **Module** or **ExternalModule** that it imports or depends upon.
- **CALLS**: Represents function invocation by linking a **Function** or **Method** to another **Function** or **Method** it calls at runtime.
- **DEPENDS_ON_EXTERNAL**: Links a **Project** or **Package** to an **ExternalPackage** representing third-party dependencies.
- **IMPLEMENTS_MODULE**: Connects a **ModuleImplementation** to a **ModuleInterface** it fulfills, supporting module system semantics.

## Resource Access and Export Relationships

The schema captures I/O operations and public API surfaces through relationships that model how code interacts with external resources and what it exposes to consumers.

- **EXPORTS**: Connects a **Module** or **Package** to a **Resource** (such as a symbol or public identifier) that it makes available to external code.
- **EXPORTS_MODULE**: Specifically links a **Package** to a **Module** it exports as part of its public API.
- **READS_FROM**: Indicates that a **Function** or **Method** reads data from a **File** or **Resource**.
- **WRITES_TO**: Indicates that a **Function** or **Method** writes data to a **File** or **Resource**.

## Relationship Schema Implementation

All relationship types are formally declared in the `RelationshipType` enum within [`codec/schema.proto`](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema.proto) at lines 115–136:

```proto
enum RelationshipType {
  RELATIONSHIP_TYPE_UNSPECIFIED = 0;
  CONTAINS_PACKAGE = 1;
  CONTAINS_FOLDER = 2;
  CONTAINS_FILE = 3;
  CONTAINS_MODULE = 4;
  DEFINES = 5;
  DEFINES_METHOD = 6;
  IMPORTS = 7;
  INHERITS = 8;
  OVERRIDES = 9;
  CALLS = 10;
  DEPENDS_ON_EXTERNAL = 11;
  IMPLEMENTS_MODULE = 12;
  IMPLEMENTS = 13;
  EXPORTS = 14;
  EXPORTS_MODULE = 15;
  READS_FROM = 16;
  WRITES_TO = 17;
}

```

Each instantiated edge is represented by a `Relationship` message (lines 138–147) that records the `type`, `source_id`, `target_id`, optional `properties`, and the label strings of the participating nodes. This structure ensures type safety while allowing rich metadata attachment.

## Creating Relationships in Python

The schema is compiled into Python bindings available in [[`codec/schema_pb2.py`](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema_pb2.py)](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema_pb2.py). Below is a minimal example demonstrating how to construct nodes and connect them using the **CONTAINS_PACKAGE** relationship:

```python
import codec.schema_pb2 as pb

# Create a Project node

proj = pb.Node()
proj.project.name = "my-awesome-project"

# Create a Package node

pkg = pb.Node()
pkg.package.qualified_name = "my_pkg"
pkg.package.name = "my_pkg"
pkg.package.path = "src/my_pkg"

# Relationship: Project CONTAINS_PACKAGE Package

rel = pb.Relationship(
    type=pb.Relationship.CONTAINS_PACKAGE,
    source_id="project:my-awesome-project",
    target_id="package:my_pkg",
    source_label="Project",
    target_label="Package",
)

# Assemble the GraphCodeIndex

graph = pb.GraphCodeIndex()
graph.nodes.extend([proj, pkg])
graph.relationships.append(rel)

# Serialise to bytes (e.g., for storage or transmission)

data = graph.SerializeToString()

# Deserialise later

restored = pb.GraphCodeIndex()
restored.ParseFromString(data)

```

For a more comprehensive demonstration of multiple relationship types including imports, calls, and inheritance, refer to the test suite in [[`codebase_rag/tests/test_protobuf_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tests/test_protobuf_service.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tests/test_protobuf_service.py).

## Key Files for Graph Schema Management

Three primary files work together to define, generate, and utilize the relationship schema:

| File | Role |
|------|------|
| **[`codec/schema.proto`](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema.proto)** | Defines the complete graph schema, including all node payloads and the `Relationship` enum. |
| **[[`codec/schema_pb2.py`](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema_pb2.py)](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema_pb2.py)** | Auto-generated Python bindings used to construct and manipulate graph objects programmatically. |
| **[[`codebase_rag/services/protobuf_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/protobuf_service.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/services/protobuf_service.py)** | Service layer that creates `GraphCodeIndex` instances from parsed code, populating nodes and relationships according to the schema. |

## Summary

- The Code-Graph-RAG schema defines **17 relationship types** in the `RelationshipType` enum within `codec/schema.proto`.
- **Containment relationships** (CONTAINS_PACKAGE, CONTAINS_FOLDER, etc.) model the physical and logical organization of code.
- **Definition and inheritance relationships** (DEFINES, INHERITS, IMPLEMENTS, OVERRIDES) capture object-oriented semantics and type hierarchies.
- **Dependency relationships** (IMPORTS, CALLS, DEPENDS_ON_EXTERNAL) enable call graph analysis and dependency tracking.
- **Resource relationships** (EXPORTS, READS_FROM, WRITES_TO) model I/O operations and public API surfaces.
- Relationships are instantiated via the `Relationship` message, which stores source/target IDs, types, and metadata.
- The Python implementation uses auto-generated bindings in [`codec/schema_pb2.py`](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema_pb2.py) to build and serialize graph structures.

## Frequently Asked Questions

### What is the source of truth for relationship definitions in Code-Graph-RAG?

The canonical definitions reside in [`codec/schema.proto`](https://github.com/vitali87/code-graph-rag/blob/main/codec/schema.proto) within the `RelationshipType` enum (lines 115–136). This Protocol Buffers file serves as the single source of truth, ensuring consistent graph structure across all language implementations and tooling.

### How does the schema distinguish between a method definition and a general definition?

The schema uses two separate relationship types: **DEFINES** is a general-purpose edge connecting modules, classes, or interfaces to any defined entity (functions, classes, enums, types), while **DEFINES_METHOD** specifically connects classes or interfaces to methods they declare. This distinction enables precise querying of method hierarchies versus general type definitions.

### Can the graph represent external dependencies and I/O operations?

Yes. The **DEPENDS_ON_EXTERNAL** relationship links projects or packages to external dependencies, while **READS_FROM** and **WRITES_TO** capture file and resource I/O operations at the function or method level. These edges enable security analysis and understanding of external system interactions.

### Where can I find examples of multiple relationship types used together?

The repository's test suite in [[`codebase_rag/tests/test_protobuf_service.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tests/test_protobuf_service.py)](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tests/test_protobuf_service.py) contains realistic examples demonstrating import relationships, call graphs, and inheritance chains constructed using the Python protobuf bindings.