Roam is built on a Datomic database. In simple terms, a Datom is an individual fact. It is an attribute with a value. Datoms consist of four elements:

Entity ID

Attribute

Value

Transaction ID

Roam stores facts about paragraphs and pages using :block/ attributes. There are few minor differences between pages and paragraphs that I will explain in a minute, however, the basic concept you must understand, is that a page is just a special type of block. Mostly, Roam treats a page exactly the same way as a paragraph. Both are blocks.

Hidden ID: 

The entity-id is the real block-id, even though it is not visible through the Roam user interface. This is the ID that is used to tie information together in the database. The Entity ID identifies facts about a block, capturing parent-child relationships, and references to blocks.

Public ID:

Is the block reference of a paragraph, e.g.: ((GGv3cyL6Y)), or

the [[Page Title]] for pages. Note that pages also have a nine-character long UID - very much like the block reference, you could use these, for example, for constructing URLs that point to specific pages in your graph.

Every block will have the following attributes:

:block/uidThe public ID, i.e. nine-character long block reference.:create/emailThe email address of the person who has created the block.:create/timeTime in milliseconds since epoch (January 1, 1970 midnight UTC/GMT).:edit/emailThe email address of the person who has edited the block.:edit/timeThe time the block was last edited.

The Roam database is like a forest. Each page is a tree. The root of the tree is the page, the branches are the higher-level paragraphs; the leaves are the paragraphs at the deepest level of nesting on the page.

For every paragraph, Roam always creates two pointers. Children reference the entity-id of their parents using :block/parents and parents reference the entity-id of their children using :block/children.

Parents keep a list of their children in the :block/children attribute. This list will ONLY include the entity-id of their immediate descendants, not the grandchildren. A page will only list the top-level paragraphs on the page as its children, but not the nested paragraphs. Similarly, a paragraph will only list blocks nested right under it, not the blocks nested under the nested blocks. The lowest level blocks in the nesting (the leaves) will have no :block/children attribute.

Children also keep a list of their parents in the :block/parents attribute. Contrary to :block/children, the list of parents includes the entity-id of ALL ancestors i.e. grandparents, great grandparents, etc. A nested paragraph will have references to the parent paragraph(s) and the page as well. The top-level paragraphs on a page have the entity-id of the page in the :block/parents attribute, while paragraphs nested under another paragraph will have the entity-id of the higher level paragraph and the entity-id of the page.

:node/titleAll pages will have a title, and no paragraphs will have one.

If you want to find all pages in your database, you need to query :node/title because this property will only hold value for pages. By executing the following query you will get a table with two columns: the entity-id of each page under ?p and the title of each page under ?title.

If you would also want to see the nine-character UID for each page, for example, to construct a link to the page, you would need to find the :block/uid attribute associated with the ?p entity-id. Here's how the query would look like. Note how ?p appears in both patterns in the where clause. This tells the query engine to find the title and the uid for the same entity.

Every paragraph will have the following attributes:

:block/pageEvery paragraph on a page regardless of their level of nesting will also reference the entity-id of their page.:block/orderThis is the sequence of the block within the page or within their level of nesting under a paragraph. You will need to sort this value to retrieve the paragraphs in the proper sequence, as they appear in the document.:block/stringThe contents of the block.:block/parentsThe ancestors of the paragraph. For top-level paragraphs this is only the page. For nested paragraphs, this attribute lists all their ancestors leading up to (and including) the page.

Roam will only set these attributes (only exist in the database for the paragraph) if you change the value from the default for the specific block. e.g. you set the text alignment of the block from left aligned to centered.

:children/view-type

Specifies how to display the block’s children. Recognized values are ‘bullet’, ‘document’, ‘numbered’.

:block/headingIn case you set the heading level of the block to H1, H2, or H3. Allowed values of this are 1,2,3.:block/props

This is where Roam stores the sizing of an image or iframe, the position of the slider, the setting of the Pomodoro timer, etc.

:block/text-alignAlignment of the paragraph. Values are 'left', 'center', 'right', 'justify'.

If you are wondering how to find out what attributes exist in your database, I have good news! Using a simple query, you can list all the attributes in your database.

Below is the list. Truth be told, the query above will not sort the values, and will not create the last column. I have included the slightly more advanced version of the query, which will do the sorting, in the downloadable roam.json file. I found the namespace function in the clojure.core documentation.

NamespaceAttribute:Namespace/Attributeattrslookup:attrs/lookupblockchildren:block/childrenblockheading:block/headingblockopen:block/openblockorder:block/orderblockpage:block/pageblockparents:block/parentsblockprops:block/propsblockrefs:block/refsblockstring:block/stringblocktext-align:block/text-alignblockuid:block/uidchildrenview-type:children/view-typecreateemail:create/emailcreatetime:create/timeeditemail:edit/emaileditseen-by:edit/seen-byedittime:edit/timeentityattrs:entity/attrslogid:log/idnodetitle:node/titlepagesidebar:page/sidebarusercolor:user/coloruserdisplay-name:user/display-nameuseremail:user/emailuserphoto-url:user/photo-urlusersettings:user/settingsuseruid:user/uidvcblocks:vc/blocksversionid:version/idversionnonce:version/nonceversionupgraded-nonce:version/upgraded-noncewindowfilters:window/filterswindowid:window/id

If you are interested in writing queries for Roam, you should really work through the nine chapters of Learn Datalog Today. It is fun and action packed with exercises. 

I will now quote a few paragraphs from the tutorial almost verbatim, changing the examples to fit Roam.  For the rest, please visit the tutorial.

I also recommend the following youtube video by Stuart Halloway, which summarizes the key features of the Datalog query language in eleven minutes.

A query is a vector starting with the keyword :find followed by one or more pattern variables (symbols starting with ?, e.g. ?title). After the find clause comes the :where clause which restricts the query to datoms that match the given data patterns. Use the _ symbol as a wildcard for the parts of the data pattern you wish to ignore.

For example if you want to find the text based on the block reference of a paragraph you would write:

Considering the example at the beginning of this post, this query would return "Check [[Projects]]"

The important thing to note here is that the pattern variable ?b is used in both data patterns. When a pattern variable is used in multiple places, the query engine requires it to be bound to the same value in each place. Therefore, this query will only find the string for the block that has the uid r61dfi2ZH.

Datoms about an entity may be in attributes that are in different namespaces. For example, if I would want to find the title of the page, that holds the ((r61dfi2ZH)) paragraph, I would write the following query. Note that I first read the ?block/page attribute for the entity-id of the page which I store in ?p. I then use this to locate the ?note/title and ?block/uid for the page.

Considering the example above, this would return "January 19th, 2021" and "01-19-2021".

The predicate clause filters the result set to only include results for which the predicate returns true. In datalog you can use any Clojure function or Java method as a predicate function. In my experience, in the Roam javascript implementation, Java functions are not available, and only a handful of Clojule functions work.

Clojure functions must be fully namespace-qualified, except for the clojure.core namespace. Sadly, outside the core namespace I have only found few that worked in Roam. These include clojure.string/includes?, clojure.string/starts-with?, and clojure.string/ends-with?. Some of the helpful functions from the core namespace include namespace which returns the namespace of an attribute, and count which returns the length of a string. Some ubiquitous predicates that can also be used without namespace qualification are <, >, <=, >=, =, not=, != and so on.

Here are two examples using predicates. The first one returns the number of characters in a paragraph based on the block_reference.

The second lists blocks that were modified after a given date.

Sadly, I could not make transformation functions work in javascript. These are only an option if you install a Datalog database on your desktop, and load the Roam.EDN for further manipulation.

The only workaround available is to post-process the results after the query. The following example will filter page titles to find a text fragment ("temp") case insensitively, and then to sort the results alphabetically. This query will return pages including words like "Template", "template", "Temporary", "attempt", etc.

Aggregates work, as expected. There are many aggregates available including sum, max, min, avg, count. You can read more about aggregates here.

You can abstract away reusable parts of your queries into rules, give them meaningful names and forget about the implementation details, just like you can with functions in your favorite programming language.

A typical example of rules in Roam are the ancestor rules. These exploit the :block/children to traverse the tree of nested blocks. A simple ancestor rule would look like this. This finds the ?child based on a ?parent entity-id.

The first vector is called the head of the rule where the first symbol is the name of the rule. The rest of the rule is called the body.

It is possible to use(...)or[...]to enclose it, but it is conventional to use(...)to aid the eye when distinguishing between the rule's head and its body, and also between rule invocations and normal data patterns, as we'll see below.

You can think of a rule as a kind of function, but remember that this is logic programming, so we can use the same rule to find parents based on the entity-id of the child, and the child based on the entity-id of the parent.

Put another way, you can use both ?parent and ?child in (ancestor ?child ?parent) for input and for output. If you provide values for neither, you will get all the possible combinations in the database. If you provide values for one or both, it will constrain the result returned by the query as you would expect.

Now becomes:

The % symbol in the :in clause represents the rules.

This may not seem as an enormous achievement at first. Rules, however, can be nested. By extending the above rule you can make it so, that it returns not only the children, but the entire sub-tree under ?parent. Rules can contain other rules, and can call recursively themselves.

Of course, in this example, we would be better off using the :block/parent attribute, which would allow for a much simpler query.

This post is already too long and too technical. For this reason, I am completely omitting a discussion about (pull ) requests - though in the examples in the roam.json I will include a few. (pull ?e [*]) is a powerful approach to get data from your database. Here are two references that are worth reading if you want to learn more.

Datomic Pull in the Datomic On-Prem Documentation

Introduction to the Roam Alpha API on Put Your Left Foot.