Queries

Common Roam Datalog queries abstracted into human-readable typed helpers.

getAllBlockUids

Returns the uids representing all the blocks in the graph.
import { getAllBlockUids } from 'roam-client';
const blockUids = getAllBlockUids();
console.log(blockUids); // ['block-uid', 'other-uid', ...etc]

getAllBlockUidsAndTexts

Returns all the blocks in the graph as objects with their uid and text content.
import { getAllBlockUidsAndTexts } from 'roam-client';
const blocks = getAllBlockUidsAndTexts();
console.log(blocks); // [{uid: 'block-uid', text: 'Content'}, ...etc]

getAllPageNames

Returns the titles of all the pages in the graph.
import { getAllPageNames } from 'roam-client';
const pageTitles = getAllPageNames();
console.log(pageTitles); // ['Welcome', 'June 9th, 2021', ...etc]

getBlockUidAndTextIncludingText

Returns all the blocks as objects with their uid and text content that contain the input string
import { getBlockUidAndTextIncludingText } from 'roam-client';
const blocks = getBlockUidAndTextIncludingText('hello');
console.log(blocks);
/*
[
{uid: 'block-uid', text: 'hello, world'},
{uid: 'other-uid', text: 'Othello'},
]
*/

getBlockUidByTextOnPage

Returns the block uid that has the input text on the page with the input title.
import { getBlockUidByTextOnPage } from 'roam-client';
const blockUid = getBlockUidByTextOnPage({
text: 'Welcome to the graph',
title: 'Welcome'
});
console.log(blockUid); // 'block-uid'

getBlockUidsAndTextsReferencingPage

Returns the blocks as objects with their uid and text content that has a reference to the page with the input title.
import { getBlockUidsAndTextsReferencingPage } from 'roam-client';
const blocks = getBlockUidsAndTextsReferencingPage('Welcome');
console.log(blockUid);
/*
[
{uid: 'block-uid', text: 'Start with [[Welcome]] page'},
{uid: 'other-uid', text: '#Welcome to the graph!'},
]
*/

getBlockUidsByPageTitlegetBlockUidsByPageTitle

Returns all of the block uids that are on the page with the input title.
import { getBlockUidsByPageTitle } from 'roam-client';
const blockUids = getBlockUidsByPageTitle('Welcome');
console.log(blockUids); // ['block-uid', 'other-uid']

getBlockUidsReferencingBlock

Returns all of the block uids that have a reference to the input block uid.
import { getBlockUidsReferencingBlock } from 'roam-client';
const blockUids = getBlockUidsReferencingBlock('ref-block');
console.log(blockUids); // ['block-uid', 'other-uid', ...etc]

getBlockUidsReferencingPage

Returns all of the block uids that have a reference to the page with the input title.
import { getBlockUidsReferencingPage } from 'roam-client';
const blockUids = getBlockUidsReferencingPage('Welcome');
console.log(blockUids); // ['block-uid', 'other-uid', ...etc]

getChildrenLengthByPageUid

Returns the number of top-level blocks on the page represented by the input uid.
import { getChildrenLengthByPageUid } from 'roam-client';
const len = getChildrenLengthByPageUid('06-09-2021');
console.log(len); // 3

getCreateTimeByBlockUid

Returns the timestamp of when the block represented by the input uid was created.
import { getCreateTimeByBlockUid } from 'roam-client';
const time = getCreateTimeByBlockUid('block-uid');
console.log(time); // 1623215529945

getDisplayNameByEmail

Returns the display name configured for the user with the input email.
import { getDisplayNameByEmail } from 'roam-client';
const name = getDisplayNameByEmail('[email protected]');
console.log(name); // 'Vargas'

getDisplayNameByUid

Returns the display name configured for the user with the input uid.
import { getDisplayNameByUid } from 'roam-client';
const name = getDisplayNameByUid('abcd1234abcd1234abcd1234abcd');
console.log(name); // 'Vargas'

getEditedUserEmailByBlockUid

Returns the email address of the last user to edit the input block uid.
import { getEditedUserEmailByBlockUid } from 'roam-client';
const email = getEditedUserEmailByBlockUid('block-uid');
console.log(email); // '[email protected]'

getEditTimeByBlockUid

Returns the timestamp of when the block represented by the input uid was last edited.
import { getEditTimeByBlockUid } from 'roam-client';
const time = getEditTimeByBlockUid('block-uid');
console.log(time); // 1623215529945

getFirstChildTextByBlockUid

Returns the text content of the block that is the first child of the parent block represented by the input uid.
import { getFirstChildTextByBlockUid } from 'roam-client';
const text = getFirstChildTextByBlockUid('parentuid');
console.log(text); // 'The first child'

getFirstChildUidByBlockUid

Returns the block uid of the first child of the parent block represented by the input uid.
import { getFirstChildUidByBlockUid } from 'roam-client';
const childUid = getFirstChildUidByBlockUid('parentuid');
console.log(childUid); // 'block-uid'

getLinkedPageTitlesUnderUid

Returns all of the page titles referenced by blocks on the page represented by the input uid.
import { getLinkedPageTitlesUnderUid } from 'roam-client';
const pageTitles = getLinkedPageTitlesUnderUid('06-09-2021');
console.log(pageTitles); // ['TODO', 'June 2021']

getNthChildUidByBlockUid

Returns the block uid that is indexed by the input order within the children of the block represented by the input uid.
import { getNthChildUidByBlockUid } from 'roam-client';
const childUid = getNthChildUidByBlockUid({
blockUid: 'parentuid',
order: 3
});
console.log(childUid); // 'block-uid'

getOrderByBlockUid

Returns the index of an input block uid within its parent's children array.
import { getOrderByBlockUid } from 'roam-client';
const order = getOrderByBlockUid('block-uid');
console.log(order); // 1

getPageTitleByBlockUid

Returns the title of a page that a given block is on represented by the input uid.
import { getPageTitleByBlockUid } from 'roam-client';
const pageTitle = getPageTitleByBlockUid('block-uid');
console.log(pageTitle); // 'Welcome'

getPageTitleByPageUid

Returns the title of the page represented by the input uid.
import { getPageTitleByPageUid } from 'roam-client';
const pageTitle = getPageTitleByPageUid('06-09-2021');
console.log(pageTitle); // 'June 9th, 2021'

getPageTitleReferencesByPageTitle

Returns all of the page titles with a linked reference to the input page title.
import { getPageTitleReferencesByPageTitle } from 'roam-client';
const pageTitles = getPageTitleReferencesByPageTitle('Book');
console.log(pageTitles); // ['Harry Potter', 'Atomic Habits']

getPageTitlesAndBlockUidsReferencingPage

Returns all of the blocks as objects with their uids and page titles that reference the page with the input title.
import { getPageTitlesAndBlockUidsReferencingPage } from 'roam-client';
const pageTitles = getPageTitlesAndBlockUidsReferencingPage('Book');
console.log(pageTitles);
/*
[
{title: 'Harry Potter', uid: 'block-uid'},
{title: 'Atomic Habits', uid: 'other-uid'},
]
*/

getPageTitlesAndUidsDirectlyReferencingPage

Returns all of the pages as objects with their uids and titles that reference the page with the input title directly in their own titles.
import { getPageTitlesAndUidsDirectlyReferencingPage } from 'roam-client';
const pages = getPageTitlesAndUidsDirectlyReferencingPage('Book');
console.log(pages);
/*
[
{title: 'A good [[Book]]', uid: 'apage-uid'},
{title: 'Library of [[Book]]s', uid: 'other-uid'},
]
*/

getPageTitlesReferencingBlockUid

Returns all of the page titles that contain a block that references the block represented by the input block uid.
import { getPageTitlesReferencingBlockUid } from 'roam-client';
const pageTitles = getPageTitlesReferencingBlockUid('block-uid');
console.log(pageTitles); // ['Harry Potter', 'Atomic Habits']

getPageTitlesStartingWithPrefix

Returns all of the page titles that start with the input prefix.
import { getPageTitlesStartingWithPrefix } from 'roam-client';
const pageTitles = getPageTitlesStartingWithPrefix('Article');
console.log(pageTitles); // ['Articles', 'Article/Year End Review', ...etc.]

getPageUidByPageTitle

Returns the uid of the page with the input title.
import { getPageUidByPageTitle } from 'roam-client';
const pageTitle = getPageUidByPageTitle('June 9th, 2021');
console.log(pageTitle); // '06-09-2021'

getPageViewType

Returns the view type of the page with the input title.
import { getPageViewType } from 'roam-client';
const viewType = getPageViewType('Welcome');
console.log(viewType); // 'bullet'

getParentTextByBlockUid

Returns the text content of the block that is the direct parent of the block represented by the input uid. Root level blocks return an empty string.
import { getParentTextByBlockUid } from 'roam-client';
const text = getParentTextByBlockUid('block-uid');
console.log(text); // 'Text of a block with children'

getParentTextByBlockUidAndTag

Returns the text content of the block that is the first parent of the block represented by the input uid and is also referencing the input tag.
import { getParentTextByBlockUidAndTag } from 'roam-client';
const text = getParentTextByBlockUidAndTag({
blockUid: 'block-uid',
tag: 'TODO'
});
console.log(text); // 'A Parent block with a [[TODO]]'

getParentUidByBlockUid

Returns the uid of the block or page that is the parent of the input block uid.
import { getParentUidByBlockUid } from 'roam-client';
const parentUid = getParentUidByBlockUid('block-uid');
console.log(parentUid); // "parentuid"

getParentUidsOfBlockUid

Returns the uid of the block or page that is the parent of the input block uid.
import { getParentUidsOfBlockUid } from 'roam-client';
const parentUid = getParentUidsOfBlockUid('block-uid');
console.log(parentUid); // ["parentuid", "pages-uid"]

getSettingsByEmail

Returns the settings configured for the user with the input email. See UserSettings to see what fields are returned in the return object.
import { getSettingsByEmail } from 'roam-client';
const settings = getSettingsByEmail('[email protected]');
console.log(settings); // {}: UserSettings

getShallowTreeByParentUid

Returns all the child blocks as objects with the text content and uids of the parent block represented by the input uid.
import { getShallowTreeByParentUid } from 'roam-client';
const blocks = getShallowTreeByParentUid('parentuid');
console.log(blocks);
/*
[
{text: 'First child', uid: 'first-uid'},
{text: 'Second child', uid: 'seconduid'},
...etc,
]
*/

getTextByBlockUid

Returns the text of the block represented by the input uid.
import { getTextByBlockUid } from 'roam-client';
const text = getTextByBlockUid('block-uid');
console.log(text); // 'Roam Block Content'

getTreeByBlockUid

Fetches the entire tree of blocks with the root at the input block uid. See TreeNode for the shape of the return object.
import { getTreeByBlockUid } from 'roam-client';
const node = getTreeByBlockUid('block-uid');
console.log(node); // {}: TreeNode

getTreeByPageName

Fetches the entire tree of blocks available on the input page and returns the data in an array. See TreeNode for the shape of the return object.
import { getTreeByPageName } from 'roam-client';
const nodes = getTreeByPageName('Atomic Habits');
console.log(node); // [{}]: TreeNode[]