ENG-1520 Set reified relations to default for new graphs (#868)

* Refactor relation handling to use stored relations instead of reified relations across multiple components. Updated settings and migration documentation to reflect the transition from legacy pattern-based relations to stored relations. This includes changes in CreateRelationDialog, SuggestionsBody, DiscourseRelationUtil, ResultsTable, and various settings components. Adjusted user settings keys for better clarity and consistency.

* Update INSTALL_CUTOFF date in storedRelations.ts and simplify getStoredRelationsEnabled logic by removing legacy setting handling.

* Update documentation to reflect that new Discourse Graph installs use stored relations by default as of v0.18.0. Adjusted INSTALL_CUTOFF date in storedRelations.ts for consistency.

* Corrected the terminology from "Refied relations" to "Reified relations" in storedRelations.ts. Updated documentation across multiple files to clarify the use of stored relations, including migration guidance and quick start instructions for users transitioning from legacy pattern-based relations. Enhanced clarity and consistency in the descriptions of stored relations and their benefits.

* Updated documentation for extending and personalizing the Discourse Graph. Revised content to clarify the use of stored relations, added sections on legacy pattern relations, and included demo links for creating relation patterns. Adjusted navigation links for consistency across related documentation pages.

* Refactor getInstallDefault to return a boolean value, ensuring a default of true when the config page is not found. Simplified logic in getStoredRelationsEnabled by removing unnecessary type checks for resolved defaults.

* Changed section headers from "###" to "##"

Author: mdroidian

apps/roam/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Discourse Graph Plugin for roamresearch.com",
   "scripts": {
     "dev": "tsx scripts/dev.ts",

apps/roam/src/components/CreateRelationDialog.tsx

@@ -12,18 +12,17 @@ import { render as renderToast } from "roamjs-components/components/Toast";
 import MenuItemSelect from "roamjs-components/components/MenuItemSelect";
 import AutocompleteInput from "roamjs-components/components/AutocompleteInput";
 import getPageTitleByPageUid from "roamjs-components/queries/getPageTitleByPageUid";
-import { getSetting } from "~/utils/extensionSettings";
 import getDiscourseRelations, {
   type DiscourseRelation,
 } from "~/utils/getDiscourseRelations";
 import { createReifiedRelation } from "~/utils/createReifiedBlock";
+import { getStoredRelationsEnabled } from "~/utils/storedRelations";
 import findDiscourseNode from "~/utils/findDiscourseNode";
 import { getDiscourseNodeFormatInnerExpression } from "~/utils/getDiscourseNodeFormatExpression";
 import type { DiscourseNode } from "~/utils/getDiscourseNodes";
 import type { Result } from "~/utils/types";
 import internalError from "~/utils/internalError";
 import getDiscourseNodes from "~/utils/getDiscourseNodes";
-import { USE_REIFIED_RELATIONS } from "~/data/userSettings";
 import posthog from "posthog-js";
 
 export type CreateRelationDialogProps = {
@@ -384,8 +383,8 @@ export const renderCreateRelationDialog = (
 export const CreateRelationButton = (
   props: CreateRelationDialogProps,
 ): React.JSX.Element | null => {
-  const showAddRelation = getSetting<boolean>(USE_REIFIED_RELATIONS, false);
-  if (!showAddRelation) return null;
+  const storedRelationsEnabled = getStoredRelationsEnabled();
+  if (!storedRelationsEnabled) return null;
   let extProps: ExtendedCreateRelationDialogProps | null = null;
   try {
     extProps = extendProps(props);

apps/roam/src/components/SuggestionsBody.tsx

@@ -26,9 +26,8 @@ import normalizePageTitle from "roamjs-components/queries/normalizePageTitle";
 import { type RelationDetails } from "~/utils/hyde";
 import { getFormattedConfigTree } from "~/utils/discourseConfigRef";
 import { render as renderToast } from "roamjs-components/components/Toast";
-import { getSetting } from "~/utils/extensionSettings";
-import { USE_REIFIED_RELATIONS } from "~/data/userSettings";
 import { createReifiedRelation } from "~/utils/createReifiedBlock";
+import { getStoredRelationsEnabled } from "~/utils/storedRelations";
 import posthog from "posthog-js";
 
 export type DiscourseData = {
@@ -310,7 +309,7 @@ const SuggestionsBody = ({
   };
 
   const handleCreateBlock = async (node: SuggestedNode) => {
-    if (getSetting<boolean>(USE_REIFIED_RELATIONS, false)) {
+    if (getStoredRelationsEnabled()) {
       if (discourseNode === false) {
         renderToast({
           id: "suggestions-create-block-error",
@@ -374,7 +373,7 @@ const SuggestionsBody = ({
       tag,
       nodeType: node.type,
       nodeText: node.text,
-      useReifiedRelations: getSetting<boolean>(USE_REIFIED_RELATIONS, false),
+      useReifiedRelations: getStoredRelationsEnabled(),
     });
     setHydeFilteredNodes((prev) => prev.filter((n) => n.uid !== node.uid));
   };

apps/roam/src/components/canvas/DiscourseRelationShape/DiscourseRelationUtil.tsx

@@ -63,8 +63,8 @@ import {
   shapeAtTranslationStart,
   updateArrowTerminal,
 } from "./helpers";
-import { getSetting } from "~/utils/extensionSettings";
 import { createReifiedRelation } from "~/utils/createReifiedBlock";
+import { getStoredRelationsEnabled } from "~/utils/storedRelations";
 import { discourseContext, isPageUid } from "~/components/canvas/Tldraw";
 import getPageUidByPageTitle from "roamjs-components/queries/getPageUidByPageTitle";
 
@@ -86,7 +86,10 @@ const getCanvasPageUidFromDOM = (): string | null => {
   // With multiple canvases, find the one that contains the currently focused element
   // or has been recently interacted with (has :focus-within)
   for (const container of containers) {
-    if (container.matches(":focus-within") || container.contains(document.activeElement)) {
+    if (
+      container.matches(":focus-within") ||
+      container.contains(document.activeElement)
+    ) {
       return container.getAttribute("data-page-uid");
     }
   }
@@ -107,7 +110,6 @@ import getPageTitleByPageUid from "roamjs-components/queries/getPageTitleByPageU
 import { AddReferencedNodeType } from "./DiscourseRelationTool";
 import { dispatchToastEvent } from "~/components/canvas/ToastListener";
 import internalError from "~/utils/internalError";
-import { USE_REIFIED_RELATIONS } from "~/data/userSettings";
 
 const COLOR_ARRAY = Array.from(DefaultColorStyle.values)
   .filter((c) => !["red", "green", "grey"].includes(c))
@@ -638,7 +640,7 @@ export const createAllRelationShapeUtils = (
         if (arrow.type !== target.type) {
           editor.updateShapes([{ id: arrow.id, type: target.type }]);
         }
-        if (getSetting<boolean>(USE_REIFIED_RELATIONS, false)) {
+        if (getStoredRelationsEnabled()) {
           const sourceAsDNS = asDiscourseNodeShape(source, editor);
           const targetAsDNS = asDiscourseNodeShape(target, editor);
 

apps/roam/src/components/results-view/ResultsTable.tsx

@@ -22,9 +22,9 @@ import toCellValue from "~/utils/toCellValue";
 import { ContextContent } from "~/components/DiscourseContext";
 import DiscourseContextOverlay from "~/components/DiscourseContextOverlay";
 import { CONTEXT_OVERLAY_SUGGESTION } from "~/utils/predefinedSelections";
-import { USE_REIFIED_RELATIONS } from "~/data/userSettings";
-import { getSetting } from "~/utils/extensionSettings";
 import { strictQueryForReifiedBlocks } from "~/utils/createReifiedBlock";
+import { getStoredRelationsEnabled } from "~/utils/storedRelations";
+import internalError from "~/utils/internalError";
 import {
   RenderRoamBlock,
   RenderRoamPage,
@@ -201,7 +201,7 @@ const ResultRow = ({
   onDragEnd,
   onRefresh,
 }: ResultRowProps) => {
-  const useReifiedRel = getSetting<boolean>(USE_REIFIED_RELATIONS, false);
+  const storedRelationsEnabled = getStoredRelationsEnabled();
   const cell = (key: string) => {
     const value = toCellValue({
       value: r[`${key}-display`] || r[key] || "",
@@ -371,7 +371,7 @@ const ResultRow = ({
               ) : (
                 cell(key)
               )}
-              {useReifiedRel &&
+              {storedRelationsEnabled &&
                 typeof r["ctxTargetUid"] === "string" &&
                 typeof r["id"] === "string" &&
                 typeof r["complement"] === "number" &&

apps/roam/src/components/settings/DiscourseRelationConfigPanel.tsx

@@ -50,7 +50,7 @@ import { getConditionLabels } from "~/utils/conditionToDatalog";
 import { formatHexColor } from "./DiscourseNodeCanvasSettings";
 import posthog from "posthog-js";
 import { getSetting, setSetting } from "~/utils/extensionSettings";
-import { USE_REIFIED_RELATIONS } from "~/data/userSettings";
+import { getStoredRelationsEnabled } from "~/utils/storedRelations";
 import {
   setGlobalSetting,
   getGlobalSettings,
@@ -91,7 +91,7 @@ export const RelationEditPanel = ({
       ),
     [nodes],
   );
-  const useReifiedRelations = getSetting<boolean>(USE_REIFIED_RELATIONS, false);
+  const storedRelationsEnabled = getStoredRelationsEnabled();
   const containerRef = useRef<HTMLDivElement>(null);
   const idRef = useRef(0);
   const cyRef = useRef<cytoscape.Core>();
@@ -392,7 +392,7 @@ export const RelationEditPanel = ({
   );
 
   const loadCytoscape = useCallback(async () => {
-    if (useReifiedRelations) return;
+    if (storedRelationsEnabled) return;
     cyRef.current?.destroy?.();
     const cytoscape = await window.RoamLazy?.Cytoscape();
     if (!cytoscape) return;
@@ -472,7 +472,7 @@ export const RelationEditPanel = ({
     setSelectedRelation,
     tab,
     unsavedChanges,
-    useReifiedRelations,
+    storedRelationsEnabled,
   ]);
   useEffect(() => {
     loadCytoscape();
@@ -774,7 +774,7 @@ export const RelationEditPanel = ({
           />
         </Label>
       </ControlGroup>
-      {!useReifiedRelations && (
+      {!storedRelationsEnabled && (
         <>
           <Tabs
             selectedTabId={tab}
@@ -1016,10 +1016,7 @@ const DiscourseRelationConfigPanel: CustomField["options"]["component"] = ({
   const [deleteConfirmation, setDeleteConfirmation] = useState<string | null>(
     null,
   );
-  const shouldHideCanvasRelation = getSetting<boolean>(
-    USE_REIFIED_RELATIONS,
-    false,
-  );
+  const shouldHideCanvasRelation = getStoredRelationsEnabled();
   const visibleRelations = useMemo(() => {
     if (!shouldHideCanvasRelation) {
       return relations;

apps/roam/src/components/settings/HomePersonalSettings.tsx

@@ -22,7 +22,7 @@ import {
   DISCOURSE_CONTEXT_OVERLAY_IN_CANVAS_KEY,
   STREAMLINE_STYLING_KEY,
   DISALLOW_DIAGNOSTICS,
-  USE_REIFIED_RELATIONS,
+  USE_STORED_RELATIONS,
 } from "~/data/userSettings";
 import { getSetting, setSetting } from "~/utils/extensionSettings";
 import { enablePostHog, disablePostHog } from "~/utils/posthog";
@@ -35,6 +35,7 @@ import { countReifiedRelations } from "~/utils/createReifiedBlock";
 import posthog from "posthog-js";
 import internalError from "~/utils/internalError";
 import { setPersonalSetting } from "./utils/accessors";
+import { getStoredRelationsEnabled } from "~/utils/storedRelations";
 
 const enum RelationMigrationDialog {
   "none",
@@ -52,10 +53,10 @@ const HomePersonalSettings = ({ onloadArgs }: { onloadArgs: OnloadArgs }) => {
   const [numExistingRelations, setNumExistingRelations] = useState<number>(0);
   const [isOngoing, setIsOngoing] = useState<boolean>(false);
   const [storedRelations, setStoredRelationsState] = useState<boolean>(
-    getSetting<boolean>(USE_REIFIED_RELATIONS, false),
+    getStoredRelationsEnabled(),
   );
   const setStoredRelations = (value: boolean) => {
-    setSetting<boolean>(USE_REIFIED_RELATIONS, value)
+    setSetting<boolean>(USE_STORED_RELATIONS, value)
       .then(() => {
         setStoredRelationsState(value);
         setPersonalSetting(["Reified relation triples"], value);
@@ -67,11 +68,11 @@ const HomePersonalSettings = ({ onloadArgs }: { onloadArgs: OnloadArgs }) => {
   const startMigration = async (): Promise<void> => {
     const before = numExistingRelations;
     try {
-      posthog.capture("Reified Relations: Migration Started");
+      posthog.capture("Stored Relations: Migration Started");
       const numProcessed = await migrateRelations();
       if (numProcessed === false) {
         renderToast({
-          content: "Reified Relations: Migration Failed",
+          content: "Stored Relations: Migration Failed",
           intent: Intent.DANGER,
           id: "migration-error",
         });
@@ -92,7 +93,7 @@ const HomePersonalSettings = ({ onloadArgs }: { onloadArgs: OnloadArgs }) => {
           intent: Intent.SUCCESS,
           id: "migration-success",
         });
-      posthog.capture("Reified Relations: Migration Completed", {
+      posthog.capture("Stored Relations: Migration Completed", {
         processed: numProcessed,
         before,
         after,
@@ -102,7 +103,7 @@ const HomePersonalSettings = ({ onloadArgs }: { onloadArgs: OnloadArgs }) => {
     } catch (error) {
       internalError({
         error,
-        userMessage: "Reified Relations: Migration Failed",
+        userMessage: "Stored Relations: Migration Failed",
       });
       setStoredRelations(false);
     } finally {
@@ -168,7 +169,7 @@ const HomePersonalSettings = ({ onloadArgs }: { onloadArgs: OnloadArgs }) => {
 
       <PersonalFlagPanel
         title="Enable stored relations"
-        description="Transition to using stored relations instead of pattern-based relations"
+        description="Use stored relations instead of legacy pattern-based relations"
         settingKeys={["Reified relation triples"]}
         value={storedRelations}
         onBeforeChange={async (checked) => {
@@ -299,12 +300,12 @@ const HomePersonalSettings = ({ onloadArgs }: { onloadArgs: OnloadArgs }) => {
           ) : (
             <>
               <p>
-                Activating the faster relations system will migrate all
-                previously created relations and newly created relations will
-                use the new system. You can deactivate this setting to revert to
-                the old system, and your newly created relations will not be
+                Activating stored relations will migrate all previously created
+                legacy pattern relations, and newly created relations will use
+                stored relations. You can deactivate this setting to revert to
+                the legacy system, and your newly created relations will not be
                 deleted; however, they will not be accessible until you
-                reactivate the faster relation system.
+                reactivate stored relations.
               </p>
               {activeRelationMigration ===
               RelationMigrationDialog.reactivate ? (
@@ -366,11 +367,11 @@ const HomePersonalSettings = ({ onloadArgs }: { onloadArgs: OnloadArgs }) => {
       >
         <div className={Classes.DIALOG_BODY}>
           <p>
-            Deactivating the faster relations system will mean that any
-            relations created using it will no longer be accessible. The
-            discourse context overlay will still be usable with the previous
-            relations system. Any relations created with the faster system will
-            be accessible should you choose to reactivate.
+            Deactivating stored relations means any relations created using them
+            will no longer be accessible. The discourse context overlay will
+            still be usable with the legacy pattern-based system. Any relations
+            created with stored relations will be accessible should you choose
+            to reactivate.
           </p>
         </div>
         <div className={Classes.DIALOG_FOOTER}>

apps/roam/src/data/userSettings.ts

@@ -9,4 +9,4 @@ export const DISCOURSE_CONTEXT_OVERLAY_IN_CANVAS_KEY =
   "discourse-context-overlay-in-canvas";
 export const STREAMLINE_STYLING_KEY = "streamline-styling";
 export const DISALLOW_DIAGNOSTICS = "disallow-diagnostics";
-export const USE_REIFIED_RELATIONS = "use-reified-relations";
+export const USE_STORED_RELATIONS = "use-reified-relations"; // "use-reified-relations" is legacy terminology, but we keep it for backwards compatibility

apps/roam/src/utils/registerDiscourseDatalogTranslators.ts

@@ -19,9 +19,8 @@ import replaceDatalogVariables from "./replaceDatalogVariables";
 import parseQuery from "./parseQuery";
 import { fireQuerySync, getWhereClauses } from "./fireQuery";
 import { toVar } from "./compileDatalog";
-import { getSetting } from "./extensionSettings";
 import { getExistingRelationPageUid } from "./createReifiedBlock";
-import { USE_REIFIED_RELATIONS } from "~/data/userSettings";
+import { getStoredRelationsEnabled } from "./storedRelations";
 
 const hasTag = (node: DiscourseNode): node is DiscourseNode & { tag: string } =>
   !!node.tag;
@@ -410,10 +409,7 @@ const registerDiscourseDatalogTranslators = () => {
       registerDatalogTranslator({
         key: label,
         callback: ({ source, target, uid }) => {
-          const useReifiedRelations = getSetting<boolean>(
-            USE_REIFIED_RELATIONS,
-            false,
-          );
+          const storedRelationsEnabled = getStoredRelationsEnabled();
           const relationPageUid = getExistingRelationPageUid();
 
           const filteredRelations = getFilteredRelations({
@@ -495,7 +491,7 @@ const registerDiscourseDatalogTranslators = () => {
             }
           };
 
-          if (useReifiedRelations && relationPageUid !== undefined) {
+          if (storedRelationsEnabled && relationPageUid !== undefined) {
             const relClauseBasis: DatalogClause[] = [
               {
                 type: "data-pattern",

apps/roam/src/utils/storedRelations.ts

@@ -0,0 +1,39 @@
+// We made the decision to use "Store relations" terminology for the UI
+// But there is still some legacy code that uses "Reified relations" terminology.
+// ENG-1521: Update internal terminology to use "stored" instead of "reified"
+
+import { USE_STORED_RELATIONS } from "~/data/userSettings";
+import { getSetting, setSetting } from "./extensionSettings";
+import { DISCOURSE_CONFIG_PAGE_TITLE } from "./renderNodeConfigPage";
+
+const INSTALL_CUTOFF = Date.parse("2026-03-01T00:00:00.000Z");
+
+const setResolvedDefault = (value: boolean): void => {
+  void setSetting(USE_STORED_RELATIONS, value).catch(() => undefined);
+};
+
+// Stored relations are the default for new DG installs. We use the config
+// page create date as the install cutoff because it reflects when DG was first
+// initialized in the graph.
+const getInstallDefault = (): boolean => {
+  const page = window.roamAlphaAPI.pull(
+    "[:create/time]",
+    [":node/title", DISCOURSE_CONFIG_PAGE_TITLE],
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+  ) as { ":create/time"?: number } | null;
+  if (!page) return true; // handle case where config page doesn't exist yet, assume new install
+
+  const createdAt = page[":create/time"];
+  return typeof createdAt === "number" && createdAt >= INSTALL_CUTOFF;
+};
+
+// Once the config page exists, persist the resolved default under the new
+// setting key so future reads can use the explicit setting path directly.
+export const getStoredRelationsEnabled = (): boolean => {
+  const value = getSetting<boolean | undefined>(USE_STORED_RELATIONS);
+  if (typeof value === "boolean") return value;
+
+  const resolvedDefault = getInstallDefault();
+  setResolvedDefault(resolvedDefault);
+  return resolvedDefault;
+};