Roam Research Docs · Developer documentation

Data Model

markdown version · view in Roam Research

• Your graph is a DataScript database.
  • DataScript is an in-memory triple store: every fact is an [entity attribute value] datom.
    • (Datoms technically also carry a transaction id — but with no history kept, it isn't useful through the API.)
  • It's modeled on Datomic — same datalog queries and pull syntax — but without built-in history.
  • Every page, block, and user is an entity with attributes, queryable via roamAlphaAPI.data.q and roamAlphaAPI.data.pull.
• Addressing entities
  • Lookup refs work anywhere an entity id is accepted
    • a [unique-attribute value] pair:
      • [:block/uid "abc123xyz"]
      • [:node/title "My Page"]
      • [:user/uid "BBG4fFwol..."]
      • [:window/id ""]
  • :db/id (number) — the internal entity id you see in query and pull results.
    • Stable within a live graph, but not across export/import — persist :block/uids, never entity ids.
  • Reverse refs: prefix the name with _ to traverse a ref attribute backwards
    • :block/_refs (blocks referencing this entity = backlinks)
    • :block/_children (the direct parent).
• Querying tips
  • **Always use roamAlphaAPI.data.pull directly when you know the entity** — a pull with a lookup ref is direct index access, many times faster than a query.

    • // don't q for a block's children — pull them
      window.roamAlphaAPI.data.pull(
        "[{:block/children [:block/uid :block/string]}]",
        [":block/uid", "aBc123xYz"])

  • Clause ordering is huge for performance: :where clauses run top to bottom.
    • Put the most selective clause first — one anchored by a constant, a lookup ref, or an :in input.
    • A clause whose variables aren't bound yet scans its entire index — a leading unselective clause can make the same query drastically slower.
    • Predicate clauses ([(...)]) run once per remaining row — put them after the narrowing clauses.
  • Pass values through :in parameters instead of interpolating them into the query string.
  • For backlinks and parents, reverse-ref pulls (:block/_refs, :block/_children) are cheaper than joins.
  • All descendants of a block in one clause — no recursion needed, because :block/parents holds every ancestor:

    • window.roamAlphaAPI.data.q(
        `[:find ?uid
          :in $ ?ancestor-uid
          :where
          [?a :block/uid ?ancestor-uid]
          [?d :block/parents ?a]
          [?d :block/uid ?uid]]`,
        "aBc123xYz")
      // => the uid of every block anywhere under it

  • Narrow your pull patterns — [*] combined with recursive {:block/children ...} pulls entire subtrees; select only the attributes you need.
  • Fetching many entities? roamAlphaAPI.data.pull_many beats pulling in a loop.
  • For genuinely expensive queries: roamAlphaAPI.data.backend.q runs off the main thread, and roamAlphaAPI.data.fast.q is ~33% faster for read access — and remember the 20-second timeout.
• Entities
  • Page
    • Description::
      • A page is an entity with a unique :node/title
      • Its content lives in :block/children. There is no :block/string.
    • Attributes::
      • :node/title (string, unique) — the page title
      • :block/uid (string, unique) — the page's uid (daily notes use MM-DD-YYYY)
      • :log/id (number) — present on daily note pages; treat it as a presence flag ("is this a daily note?")
        • The value resembles the date in ms, but timezone offsets can skew it — don't use it for sorting or date math. Derive the date from the page's MM-DD-YYYY uid or its title via roamAlphaAPI.util.pageTitleToDate.
      • :block/children (refs, many) — the page's top-level blocks
      • :children/view-type (string, optional) — "bullet" | "numbered" | "document"
      • :page/edit-time (number) — rollup: time of the most recent edit anywhere on the page (this powers "recently edited")
      • :page/edit-user (ref) — rollup: who made that most recent edit
      • :page/word-count (number) — rollup: word count of the page's content
      • :page/sidebar (number) — present when the page is in the left-sidebar shortcuts; the value is its position (see roamAlphaAPI.data.page.addShortcut)
      • :create/time (number) — creation time, ms since epoch
      • :create/user (ref) — the creating user
      • :edit/time (number) — last edit of the page entity itself
      • :edit/user (ref) — who made that edit
      • PDF pages — created when a PDF is uploaded (titled from the file) — additionally carry:
        • :pdf/url (string) — the uploaded file's url in Roam's storage (fetch it via roamAlphaAPI.file.get)
        • :pdf/fingerprints (strings, unique, deprecated) — the PDF's fingerprint(s), used to recognize the same file again
        • :pdf/content-hash (string, unique) — hash of the file's content, also used to match re-uploads
    • Example::

      • window.roamAlphaAPI.data.pull("[*]", '[:node/title "unreads"]')
        // =>
        {":db/id": 8656,
         ":node/title": "unreads",
         ":block/uid": "hvZX-ANLE",
         ":block/children": [{":db/id": 11436}, {":db/id": 11440}, {":db/id": 43580}],
         ":page/sidebar": 4,
         ":page/word-count": 12,
         ":page/edit-time": 1773242490630,
         ":page/edit-user": {":db/id": 1},
         ":create/user": {":db/id": 1},
         ":create/time": 1773242490630}

      • // a page's top-level blocks, with their text and order
        window.roamAlphaAPI.data.pull(
          "[{:block/children [:block/uid :block/string :block/order]}]",
          '[:node/title "My Page"]')
        // =>
        {":block/children": [{":block/uid": "aBc123xYz",
                              ":block/string": "first block",
                              ":block/order": 0},
                             ...]}

  • Block
    • Description::
      • A block is an entity with a :block/string
      • It lives under a parent block or page via the parent's :block/children.
    • Attributes::
      • :block/uid (string, unique) — the block's uid
      • :block/string (string) — the block's text, in Roam-flavored markdown
      • :block/order (number) — position among siblings, 0-indexed
      • :block/open (boolean) — collapse state
      • :block/children (refs, many) — direct child blocks
      • :block/parents (refs, many) — all ancestors, from the page down to the direct parent — not just the parent
      • :block/page (ref) — the page the block lives on
      • :block/refs (refs, many) — every page or block this block references
        • [[links]], #tags, attribute::, and ((block refs)) all create identical :block/refs datoms — the syntax only changes rendering. Check refs; don't parse strings.
        • Backlinks are the reverse: :block/_refs.
      • :block/heading (number, optional) — 1–3 when the block is styled as a heading; absent otherwise (the write API accepts 0 to clear it)
      • :block/text-align (string, optional) — "left" | "center" | "right" | "justify"
      • :children/view-type (string, optional) — "bullet" | "numbered" | "document" — note the children namespace
      • :block/view-type (string, optional) — same values as the API's block-view-type
      • :block/props (map, optional) — per-block component state: image/iframe sizing, slider positions, query and table settings, ...; treat as internal
      • :create/time (number) — creation time, ms since epoch
      • :create/user (ref) — the creating user
      • :edit/time (number) — last edit time
      • :edit/user (ref) — who made that edit
      • :edit/seen-by (refs, many) — the User entities who have seen this block since its last edit; powers unread indicators ("mark unread" retracts the user)
      • :create/seen-by (refs, many) — same, tracked from the block's creation
      • :ent/emojis (vector, optional) — emoji reactions on the block: [{emoji: {native: "👍"}, users: [{uid, time}, ...]}, ...]
      • :annotation/origin (ref) — on PDF highlight blocks: the PDF Page the highlight came from
    • Example::

      • window.roamAlphaAPI.data.pull("[*]", [":block/uid", "6LMkuKL-Y"])
        // =>
        {":db/id": 16810,
         ":block/uid": "6LMkuKL-Y",
         ":block/string": "[[Developer Notes]] 🧑‍💻",
         ":block/order": 1,
         ":block/open": true,
         ":block/heading": 3,
         ":block/children": [{":db/id": 16811}],
         ":block/parents": [{":db/id": 16287}, {":db/id": 16289},
                            {":db/id": 16609}, {":db/id": 16804}],
         ":block/page": {":db/id": 16287},
         ":block/refs": [{":db/id": 17691}],
         ":create/user": {":db/id": 1},
         ":create/time": 1692372881926,
         ":edit/user": {":db/id": 1},
         ":edit/time": 1692372881926}

      • // backlinks: every block referencing a page
        window.roamAlphaAPI.data.q(
          `[:find ?s
            :in $ ?title
            :where
            [?page :node/title ?title]
            [?b :block/refs ?page]
            [?b :block/string ?s]]`,
          "My Page")
        // => [["a block referencing [[My Page]]"], ...]

  • User
    • Description::
      • A member of the graph — referenced by :create/user and :edit/user on every block and page.
    • Attributes::
      • :user/uid (string, unique) — the user's uid; see roamAlphaAPI.user.uid
      • :user/display-name (string)
      • :user/display-page (ref) — the user's display page
      • :user/email (string, unique)
      • :user/photo-url (string)
      • :user/color (string) — the user's display color (multiplayer presence)
      • :user/settings (map) — the user's client settings; treat as internal
    • Example::

      • // everything about the current user
        roamAlphaAPI.data.pull("[*]", [":user/uid", roamAlphaAPI.user.uid()])
        // =>
        {":db/id": 1,
         ":user/uid": "BBG4fFwolaVlT5FZQdzAI7P40aB3",
         ":user/display-name": "Josh",
         ":user/display-page": {":db/id": 42}}

  • Diagram
    • Description::
      • A {{[[diagram]]}} block is itself the diagram entity — alongside its normal Block attributes, it carries the canvas's nodes and edges as component sub-entities.
    • Attributes::
      • :diagram/nodes (refs, many) — the diagram's nodes; each node is its own entity (with its own :block/uid):
        • :diagram.node/block (ref) — the Block displayed in the node
        • :diagram.node/parent-node (ref) — the group node containing this node, when nested
        • :diagram.node/data (map) — layout: type ("block" | "group"), position / positionAbsolute ({x, y}), width, height
      • :diagram/edges (refs, many) — the diagram's edges; each edge is its own entity:
        • :diagram.edge/source (ref) — the node the edge starts from
        • :diagram.edge/target (ref) — the node the edge points to
        • :diagram.edge/data (map, optional) — edge styling/metadata
    • Example::

      • window.roamAlphaAPI.data.pull(
          `[:block/uid :block/string
            {:diagram/nodes [:diagram.node/data
                             {:diagram.node/block [:block/uid]}
                             {:diagram.node/parent-node [:db/id]}]}
            {:diagram/edges [{:diagram.edge/source [:db/id]}
                             {:diagram.edge/target [:db/id]}]}]`,
          [":block/uid", "4mJpKhngc"])
        // =>
        {":block/uid": "4mJpKhngc",
         ":block/string": "{{[[diagram]]}}",
         ":diagram/nodes": [{":diagram.node/block": {":block/uid": "gJN3BDpEy"},
                             ":diagram.node/parent-node": {":db/id": 29759},
                             ":diagram.node/data": {":type": "block",
                                                    ":position": {":x": 41, ":y": 55},
                                                    ":width": 54, ":height": 49}},
                            ...],
         ":diagram/edges": [{":diagram.edge/source": {":db/id": 29757},
                             ":diagram.edge/target": {":db/id": 29760}}]}

  • **Attributes (attr::)**
    • Description::
      • The triples created by attribute:: syntax live in :entity/attrs and :attrs/lookup. The current model is explained on Attributes Data Model — but it will be removed and replaced by a new attributes system, so don't build on it.
  • Window
    • Description::
      • A window stores one user's view state for one "window" — a page outline, its linked or unlinked references, or a sidebar window. This is where filters live.
      • :window/id embeds the viewing user, the window kind, and the target — e.g. "<user-uid>-body-outline-<page-uid>", "<user-uid>-mentions-page-<page-uid>", "<user-uid>-unreffed-links-<page-uid>". That's why filters are per-user.
    • Attributes::
      • :window/id (string, unique) — user + window kind + target
      • :window/filters (map) — {includes: [...], removes: [...]} of page uids; roamAlphaAPI.ui.filters reads and writes these as page titles
      • :window/mentions-state (map) — the window's linked-references display settings: sort, grouping, show-paths
      • windows also have their own :block/uid
    • Example::

      • window.roamAlphaAPI.data.pull("[*]", [":window/id", "<user-uid>-mentions-page-Do97zfpcF"])
        // =>
        {":window/id": "<user-uid>-mentions-page-Do97zfpcF",
         ":block/uid": "TcokCXcKg",
         ":window/filters": {":includes": [], ":removes": []},
         ":window/mentions-state": {":sort": ["page-date", "desc"],
                                    ":show-paths": true,
                                    ":not-by-page?": false,
                                    ":nest-under-parent-results?": false}}

  • Internal
    • Description::
      • Entity families for internal machinery — subject to change without notice; don't build on them: :graph/*, :version/*, :token/*, :harc/*, :vc/*, :restrictions/*, :append-api/*, :last-used/time.