1
0
silverbullet/website/Objects.md
2023-10-03 17:59:33 +02:00

4.5 KiB
Raw Blame History

#core

SilverBullet automatically builds and maintains an index of objects extracted from all markdown pages in your space. It subsequently allows you to Live Queries this database in (potentially) useful ways.

Some examples of things you can query for:

  • Give me a list of all books that I have marked as want to read
  • Give me a list of all tasks not yet completed that have today as a due date
  • Give me a list of items tagged with #quote
  • Give me a list of not-completed tasks that reference the current page

By design, the truth remains in the markdown: all data indexed into objects will have a representation in markdown text as well. The index can be flushed at any time and be rebuilt from markdown files.

Object representation

Every object has a set of Attributes.

At the very least:

  • ref: a unique identifier (unique to the page, at least), often represented as a pointer to the place (page, position) in your space where the object is defined. For instance, a page object will use the page name as its ref attribute, and a task will use page@pos (where pos is the location the task appears in page).
  • tags: an array of type(s) of an object, see @tags.

In addition, any number of additional tag-specific and custom Attributes can be defined (see below).

Tags

$tags Every object has one or more tags, defining the types of an object. Some tags are built-in (as described below), but you can easily define new tags by simply using the #hashtag notation in strategic locations (more on these locations later).

Here are the currently built-in tags:

page

Every page in your space is available via the page tag. You can attach additional tags to a page, by either specifying them in the tags attribute Frontmatter, or by putting additional Tags in the first paragraph of your page, as is done with the #core tag at the beginning of this page.

In addition to ref and tags, the page tag defines a bunch of additional attributes as can be seen in this example query:

page where name = "{{@page.name}}"

task

Every task in your space is tagged with the task tag by default. You tag it with additional tags by using Tags in the task name, e.g.

  • My task #upnext

And can then be queried via either task or upnext.

The following query shows all attributes available for tasks:

upnext

Although you may want to render it using a template such as template/task instead:

upnext render [[template/task]]

item

List items are not currently indexed unless explicitly tagged (for performance reasons). Like other things, an an item can be tagged using Tags.

Here is an example of a #quote item using a custom Attributes:

  • “If you dont know where youre going you may not get there.” [by: Yogi Berra] #quote

And then queried via the #quote tag:

quote select by, name

data

You can also embed arbitrary YAML data blocks in pages via fenced code blocks and use a tag as a coding language, e.g.

name: Pete
age: 55

Which then becomes queriable via the person tag:

person 

All page links are tagged with link. You cannot attach additional tags to links. The main two attributes of a link are:

  • toPage the page the link is linking to
  • page the page the link appears on

In addition, the snippet attribute attempts to capture a little bit of context on where the link appears.

Note: this is the data source used for the {[Mentions: Toggle]} feature as well page {[Page: Rename]}.

Here is an query that shows all links that appear in this particular page:

link where page = "{{@page.name}}" and inDirective = false 

anchor

$myanchor

Anchors use the $myanchor notation to allow deeplinking into a page and are also indexed and queryable. It is not possible to attach additional tags to an anchor.

Here is an example query:

anchor where page = "{{@page.name}}"

tag

The ultimate meta tag is tag itself, which indexes for all tags used, in which page they appear and what their “parent tag” is (the context of the tag: either page, item or task).

Here are the tags used/defined in this page:

tag where page = "{{@page.name}}" 

attribute

This is another meta tag, which is used to index all Attributes used in your space. This is used by e.g. attribute completion in various contexts. You likely dont need to use this tag directly, but its there.

attribute where page = "{{@page.name}}" limit 1