Semantic Templating
Bridge the gap between Graph Data and LLM Reasoning.
To make your graph data useful for an LLM, it must be converted from raw properties and IDs into semantic natural language. Raphtory uses a powerful Jinja2-based templating system to define how nodes and edges should be "narrated" for retrieval.
The Narrative Transformation
In a standard database, a node might look like this:
ID: 1024, Type: Person, Props: {name: "John", dob: 1985...}
Through Semantic Templating, it becomes: "John is a 39-year-old financial analyst based in London. He has been a customer since 2018."
Defining Node Templates
Node templates allow you to define a specific narrative for each node type. You can use logic (if/else) and filters to handle different shapes of data.
Defining Edge Templates
Edges represent the "History" and "Actions" between entities. Their templates often focus on the direction and temporal nature of the relationship.
Technical Context Variables
When the template is rendered, the following variables are available:
| Variable | Description | Example |
|---|---|---|
name | The unique ID of the node/edge. | "100092401" |
node_type | (Node Only) The defined type of the node. | "Person" |
layers | (Edge Only) List of layers this relationship exists on. | ["transfer"] |
properties | Dictionary of the latest properties. | properties.email |
history | (Edge Only) Sorted list of timestamps for events on this edge. | history[0] |
src / dst | (Edge Only) The source and destination node objects. | src.properties.name |
Best Practices for LLM Clarity
1. Computed Properties
Don't just provide timestamps; provide Duration or Age. LLMs are often bad at temporal math, so calculate the "Years of relationship" inside the template using Jinja filters.
2. Semantic Labels
Use human-readable labels for categories. Instead of category_id: 4, map it to Risk Level: Critical.
3. Contextual Density
Don't include every property. Only include what the LLM needs for reasoning. High KYC dates or internal IDs often create noise that distracts from the core patterns.
Implementation
The templates are registered when initializing the GraphServer: