# Which TextSplitter to Use for GraphRAG in Semantica?

> Discover the best TextSplitter for GraphRAG in Semantica. Use the graph_based splitter to preserve topology and inject metadata for enhanced retrieval.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Use the `graph_based` TextSplitter method for GraphRAG in Semantica, as it preserves graph topology and injects node/edge metadata into each chunk.**

For Graph Retrieval-Augmented Generation (GraphRAG) workloads, chunking strategy directly impacts retrieval quality. The Semantica library provides purpose-built splitting methods that align chunk boundaries with knowledge graph structures. This article explains how to configure and implement the correct **TextSplitter for GraphRAG in Semantica** based on the actual source code implementation.

## How Semantica's TextSplitter Architecture Works

The splitting functionality in Semantica is unified under the `TextSplitter` class in [`semantica/split/splitter.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/split/splitter.py). This class acts as a factory that dispatches to specialized chunker implementations based on the `method` parameter.

The `graph_based` method specifically uses `GraphBasedChunker` to:

- Respect node and edge groupings during chunking
- Prevent relationships from being split across chunk boundaries
- Inject **graph metadata** into each `Chunk` object via the `metadata` dictionary

Other relevant methods include `entity_aware` (for named-entity continuity) and `relation_aware` (for complete triple preservation), but `graph_based` is the explicit choice for full graph-structure alignment.

## Why Graph-Based Splitting Matters for GraphRAG

Traditional text splitters like recursive character or token-based approaches ignore semantic relationships. In [`semantica/split/splitter.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/split/splitter.py), the `GraphBasedChunker` implementation solves this by accepting an external graph that guides chunking decisions.

Key benefits for GraphRAG pipelines:

- **Topology preservation**: Nodes that are densely connected in the source graph tend to appear together in chunks
- **Metadata propagation**: Each chunk receives `graph_nodes` and `graph_edges` keys in its `metadata` field
- **Sub-graph retrieval**: Downstream RAG components can use the metadata to locate and traverse the relevant graph neighborhood

## Configuring the Graph-Based TextSplitter

### Basic Usage with TextSplitter Class

```python
from semantica.split import TextSplitter

raw_text = """
Apple Inc. was founded by Steve Jobs, Steve Wozniak, and Ronald Wayne.
The company pioneered the personal computer, the iPod, the iPhone,
and the iPad. Its ecosystem includes hardware, software, and services.
"""

splitter = TextSplitter(
    method="graph_based",      # Specifies GraphBasedChunker

    chunk_size=500,            # Target size in characters/tokens

    chunk_overlap=100,         # Context overlap between chunks

)

chunks = splitter.split(raw_text)

for i, chunk in enumerate(chunks, 1):
    print(f"Chunk {i}:")
    print(f"  text: {chunk.text[:80]!r}...")
    print(f"  metadata: {chunk.metadata}")   # Contains graph_nodes, graph_edges

```

Source: [`README.md`](https://github.com/semantica-agi/semantica/blob/main/README.md) line 627 and [`docs/reference/split.md`](https://github.com/semantica-agi/semantica/blob/main/docs/reference/split.md) lines 38-50.

### Direct Function: split_graph_based

For cases where you want explicit graph injection, use the convenience function from `semantica/split/methods`:

```python
from semantica.split.methods import split_graph_based

knowledge_graph = {
    "nodes": ["Apple Inc.", "Steve Jobs", "iPhone"],
    "edges": [
        ("Apple Inc.", "founded_by", "Steve Jobs"),
        ("Apple Inc.", "produces", "iPhone")
    ]
}

chunks = split_graph_based(
    text=raw_text,
    graph=knowledge_graph,      # Graph guides chunking boundaries

    chunk_size=800,
    chunk_overlap=150,
)

for chunk in chunks:
    print(chunk.metadata.get("graph_nodes"))

```

Source: [`semantica/split/split_usage.md`](https://github.com/semantica-agi/semantica/blob/main/semantica/split/split_usage.md) lines 239-241.

## Complete GraphRAG Pipeline Integration

The following example demonstrates end-to-end integration using `TextSplitter` for GraphRAG in Semantica:

```python
from semantica.split import TextSplitter
from semantica.vector_store import VectorStore
from semantica.rag import GraphRAG

# 1. Split with graph-based chunking

splitter = TextSplitter(
    method="graph_based",
    chunk_size=1024,
    chunk_overlap=200
)
chunks = splitter.split(raw_text)

# 2. Index embeddings and metadata

vs = VectorStore(backend="pgvector")
vs.index(chunks)

# 3. Initialize GraphRAG with graph reference

rag = GraphRAG(vector_store=vs, graph=knowledge_graph)

# 4. Query with graph-aware retrieval

answer = rag.ask("Who founded Apple Inc.?")
print(answer)

```

Source: [`semantica/vector_store/vector_store_usage.md`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store_usage.md) lines 953-958.

## Comparing Splitter Methods for Graph Workloads

| Method | Best For | Key Behavior |
|--------|----------|--------------|
| **graph_based** | **GraphRAG** — full pipeline integration | Uses supplied graph to guide chunking; injects complete node/edge metadata |
| **entity_aware** | KG extraction focusing on named entities | Guarantees entity spans never cross chunk boundaries |
| **relation_aware** | Triple-preserving pipelines | Keeps subject-predicate-object groups intact |

For GraphRAG specifically, **only `graph_based`** provides the metadata hooks required for vector-store indexing and subsequent graph traversal during retrieval.

## Key Source Files

| Path | Purpose |
|------|---------|
| [`semantica/split/splitter.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/split/splitter.py) | Core `TextSplitter` class and `GraphBasedChunker` implementation |
| [`semantica/split/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/split/methods.py) | Convenience functions including `split_graph_based` |
| [`semantica/split/split_usage.md`](https://github.com/semantica-agi/semantica/blob/main/semantica/split/split_usage.md) | Usage examples and parameter documentation |
| [`docs/reference/split.md`](https://github.com/semantica-agi/semantica/blob/main/docs/reference/split.md) | Complete method reference and selection guide |

## Summary

- Set `method="graph_based"` in `TextSplitter` for GraphRAG workloads
- Supply a knowledge graph to `split_graph_based()` or via the RAG pipeline to preserve structural relationships
- Access `chunk.metadata["graph_nodes"]` and `chunk.metadata["graph_edges"]` for downstream graph traversal
- The unified `TextSplitter` interface allows method swapping without code changes

## Frequently Asked Questions

### What makes graph_based different from relation_aware splitting?

**graph_based** accepts an external graph structure that actively guides chunk boundaries, while **relation_aware** only ensures complete subject-predicate-object triples remain intact without external graph input. For GraphRAG, you need the metadata injection and topology awareness that `graph_based` provides.

### Can I use graph_based without a pre-constructed knowledge graph?

No. The `graph_based` method requires a graph parameter (dict or graph object) that defines nodes and edges. Without this, the chunker cannot align boundaries to graph structure. Use `entity_aware` or `relation_aware` if you lack a graph but still want some semantic preservation.

### How does graph metadata appear in the chunk output?

Each `Chunk` object from `graph_based` splitting contains a `metadata` dictionary with at least two keys: `graph_nodes` (list of node identifiers present in that chunk) and `graph_edges` (list of edge tuples). These are populated by `GraphBasedChunker` during the split operation.

### Is there a performance cost to graph_based splitting?

Yes. `GraphBasedChunker` performs graph traversal and boundary optimization that adds overhead compared to simple character-based splitting. However, for GraphRAG accuracy, this cost is justified and typically occurs only during indexing, not at query time.