Skip to content

Commit d2e0c0a

Browse files
mdroidianmdroidian
authored
ENG-1405 - Update Reified Relation Documentation (#801)
* Update migration wording to stored terminology * Update stored-relations.md using h2 instead of h1 * Update migration-to-stored-relations.md
1 parent 6b5fbb3 commit d2e0c0a

5 files changed

Lines changed: 217 additions & 0 deletions

File tree

‎apps/website/app/(docs)/docs/roam/navigation.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,14 @@ export const navigation: NavigationList = [
2525
title: "Creating relationships",
2626
href: `${ROOT}/creating-discourse-relationships`,
2727
},
28+
{
29+
title: "Stored relations",
30+
href: `${ROOT}/stored-relations`,
31+
},
32+
{
33+
title: "Migration to stored relations",
34+
href: `${ROOT}/migration-to-stored-relations`,
35+
},
2836
{
2937
title: "Exploring",
3038
href: `${ROOT}/exploring-discourse-graph`,

‎apps/website/app/(docs)/docs/roam/pages/creating-discourse-relationships.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ One of the main features of the Discourse Graph extension is the ability to **cr
99

1010
The extension has an in-built [grammar](./grammar) that enables it to recognize when certain patterns of writing and outlining are meant to express particular discourse relations (e.g., support, oppose, inform) between discourse nodes. When it recognizes these patterns, it "writes" them to a formal discourse graph data structure, that you can then use to explore or query your discourse graph.
1111

12+
## Deprecation notice
13+
14+
Pattern-based relations are being deprecated. Please plan to move to [**stored relations**](./stored-relations), which will be the recommended way to define and persist discourse relations. Migration guidance is available in [**Migration to stored relations**](./migration-to-stored-relations).
15+
1216
## Stock Patterns
1317

1418
- Take a look at [Relations Patterns](./relations-patterns)

‎apps/website/app/(docs)/docs/roam/pages/migration-to-stored-relations.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: "Migration to stored relations"
3+
date: "2025-01-01"
4+
author: ""
5+
published: true
6+
---
7+
8+
## Overview
9+
10+
Stored relations make relations load faster and more reliably. To start using them, your graph needs a one-time migration that copies your existing relations into the new format.
11+
12+
This guide covers the migration flow from **Personal Settings**. If you’re new to stored relations, start with the [stored relations overview](./stored-relations).
13+
14+
## Turn on stored relations
15+
16+
1. Open **Personal Settings**
17+
2. Go to the **Home** panel
18+
3. Find **Enable stored relations**
19+
4. Turn the toggle **On**
20+
21+
When you turn this on, you’ll be shown a migration step for your graph.
22+
23+
## Migrate your existing relations
24+
25+
After enabling the toggle, click:
26+
27+
`Migrate all relations`
28+
29+
What to expect:
30+
31+
- It may take a few minutes
32+
- Roam may feel frozen while it runs (this is expected)
33+
- You **can** work in **another Roam window** during the migration
34+
- When it finishes, you can continue working normally
35+
36+
## When should I run migration again?
37+
38+
You only need to run migration again if:
39+
40+
- Relations were created while stored relations were turned off
41+
- Your team is transitioning gradually and some people are still using the older relation method
42+
43+
## Multi-user graphs
44+
45+
Migration runs **per graph**, but the stored relations toggle is **per user**. During rollout, it’s possible for teammates to be in different modes.
46+
47+
If some users are still using the older relation method, running migration again later helps ensure you see the most up-to-date relations.
48+
49+
### What each user sees
50+
51+
#### If you do NOT opt in
52+
53+
- You can keep using **patterns** to create relations
54+
- The overlay will search **only pattern-based** relations
55+
- You **will not** see stored relations
56+
57+
#### If you DO opt in
58+
59+
- You will see **only stored** relations
60+
- You **will not** see pattern-based relations
61+
62+
### Re-running migration (multi-user / mixed mode)
63+
64+
You can run migration **multiple times**.
65+
66+
This matters if:
67+
68+
- Some users are still creating **pattern-based** relations
69+
- Other users have opted into **stored** relations
70+
71+
In that case, opt-in users must re-run migration to “catch up,” otherwise:
72+
73+
- They won’t see new pattern-based relations created since the last migration
74+
75+
#### Important edge case
76+
77+
If you:
78+
79+
1. Delete a **stored** relation that originally came from a pattern, and then
80+
2. Re-run migration
81+
82+
… it will be **re-created** from the still-existing pattern.
83+
84+
### For the technically inclined
85+
86+
Stored relations are implemented as:
87+
88+
- `roam/js/discourse-graph/relations`
89+
90+
Each relation is a **block**, with relation data stored in the block’s **hidden properties**.

‎apps/website/app/(docs)/docs/roam/pages/relations-patterns.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ author: ""
55
published: true
66
---
77

8+
## Deprecation notice
9+
10+
Pattern-based relations are being deprecated. Please plan to move to [**stored relations**](./stored-relations), which will be the recommended way to define and persist discourse relations. Migration guidance is available in [**Migration to stored relations**](./migration-to-stored-relations).
11+
812
## Stock Patterns
913

1014
The extension ships with the ability to recognize three such writing/outlining patterns. Give them a try!

‎apps/website/app/(docs)/docs/roam/pages/stored-relations.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: "Stored relations"
3+
date: "2025-01-01"
4+
author: ""
5+
published: true
6+
---
7+
8+
## Overview
9+
10+
Stored relations change how relationships between discourse nodes are created and managed.
11+
12+
Instead of being inferred from patterns in your Roam graph, **stored relations are created and deleted explicitly** and saved as data. This makes relations faster to query, more reliable, and easier to manage.
13+
14+
Stored relations are the foundation for improved performance and a more usable Discourse context overlay.
15+
16+
## What is a stored relation?
17+
18+
A **stored relation** is an explicit relationship between two discourse nodes (for example, a claim supporting or opposing another claim).
19+
20+
- Created directly in the [**Discourse context overlay**](./discourse-context-overlay)
21+
- Persisted as data in your graph
22+
- Independent of page structure or pattern matching
23+
24+
Once created, stored relations behave consistently across queries, canvases, and overlays.
25+
26+
## Why stored relations?
27+
28+
Stored relations provide several benefits over pattern-based relations:
29+
30+
- **Faster performance**
31+
- Relations are read directly from stored data
32+
- The global Discourse context overlay loads significantly faster
33+
- **More predictable behavior**
34+
- Relations do not disappear due to formatting or structural changes
35+
- Editing text or reorganizing blocks does not affect relations
36+
- **Clearer mental model**
37+
- Relations exist because you created them
38+
- Deleting a relation removes it explicitly
39+
40+
## Creating stored relations
41+
42+
Stored relations are created from the [**Discourse context overlay**](./discourse-context-overlay).
43+
44+
Typical flow:
45+
46+
1. Open the Discourse context overlay for a node
47+
2. Click **Add relation**
48+
3. Select the relation type
49+
4. Select the source and destination nodes
50+
51+
The relation is immediately stored and available to all users who have enabled stored relations.
52+
53+
## Viewing stored relations
54+
55+
When stored relations are enabled:
56+
57+
- The [Discourse Context Overlay](./discourse-context-overlay) shows **only stored relations**
58+
- Queries and canvases resolve relations from stored data
59+
- Pattern-based relations are ignored
60+
61+
This ensures consistent and fast results.
62+
63+
## Editing and deleting stored relations
64+
65+
- Stored relations can be **deleted explicitly** from the Discourse context overlay
66+
- In most cases, editing a relation is equivalent to:
67+
- Deleting the old relation
68+
- Creating a new one
69+
70+
Relation labels are referenced by node identity, so renaming a relation label updates all associated relations automatically.
71+
72+
## Multi-user behavior
73+
74+
Stored relations are shared across the graph:
75+
76+
- All users with stored relations enabled see the same relations
77+
- Users without stored relations enabled will not see them
78+
- Mixed usage is supported temporarily during the transition period
79+
80+
For details on migrating and mixed-mode behavior, see the [**stored relations migration**](./migration-to-stored-relations) documentation.
81+
82+
## Current limitations and notes
83+
84+
- Stored relations are **not inferred** from patterns
85+
- Creating or deleting patterns does not affect stored relations
86+
- Stored relations are currently opt-in during the transition period
87+
88+
These limitations will be removed once stored relations become the default.
89+
90+
## For the technically inclined
91+
92+
Stored relations are implemented as:
93+
94+
- One block per relation
95+
- Located at: `roam/js/discourse-graph/relations`
96+
- Relation data stored in the block’s hidden properties
97+
- Source and destination nodes referenced by UID
98+
99+
This structure allows fast lookup, consistent rendering, and future extensions (metadata, provenance, annotations).
100+
101+
## Future direction
102+
103+
Stored relations will eventually replace pattern-based relations entirely.
104+
105+
Once the transition period ends:
106+
107+
- Stored relations will be the default
108+
- Pattern-based relations will be phased out
109+
- Migration will be handled automatically
110+
111+
Until then, stored relations are available as an opt-in feature for users who want improved performance and reliability.

0 commit comments

Comments
 (0)