Supertags

Supertags turn your notes into objects like Projects, People, Tasks, Books, Recipes. Supertags will help you find, structure and build your information in flexible, iterative and lightning-fast ways.
Last updated: July 30, 2024

Overview

Supertag = Turns a node into an object.

Use supertags to identify objects in your notes: Examples include #task, #meeting, #trip, #subscription, #person and so on. A good way to check if a supertag is right, is thinking “is a” when adding the tag to a node. A node with the contents “Marisha” is a #person. Oslo is a #city. With an eye for “what things come up in my notes that need to be remembered, organized or actioned”, these are good candidates for a supertag.

Supertags are the beginning of creating collections of objects, like a database: Anything you would make a list, collection or database for, these are good supertag candidates. Each row in a database represents one node. Each column represents the Fields of those nodes.

Supertags give you tools to structure the information of the object: Every time you apply a supertag to an item, it populates with default Fields and Nodes of your choice, to help you organize all important and related information regarding this item. If it is a person, adding a Field for their Phone Number and their Preferred Name might be handy. If it is a todo, you may want a Field with the Due Date. See more under Supertag configuration panel.

Basics

  • When you tag something, unlike traditional tags that signal that the content is related to the tag, in Tana the content is the tag. For example, "buy milk" is a #task. Therefore, supertags apply to the whole node.
  • This means that you can define objects in your notes, and give them special attributes based on what they are. Tasks can have Due dates. People can have Nicknames. Projects can have Statuses. These attributes are saved as Fields in the Template.
  • Supertags can be used on any node, and gathered at any time using Search nodes. If you remember to supertag your important stuffs, our powerful search nodes will ensure that everything resurfaces again in an instant, no matter where they are in the graph.
  • Click on a tag and you’re taken to a Supertag page. By default it creates a search looking for all nodes with this supertag in the graph, shown as a table. That said, you can adapt the Supertag page however you want by adding tabs and additional views of relevant information.
  • In the Supertag page, click on the wrench button on the top right to get to the Supertag configuration panel. (Note: you can also get to it by holding Cmd/Ctrl+Shift+click on any supertag)

Documentation

Create a supertag

On any node, typing # will bring up the Supertag menu. Continue typing the name of the supertag to either make a new supertag (always the top answer), or find an existing one that matches what you’re typing.

On any node, use the Command Line Cmd/Ctrl+K and type Convert to supertag. This converts the node to a Supertag definition turning the node name into the supertag name. This command will also take the child fields and nodes and make them into template items.

When you create a supertag, by default it sends the original Supertag definition to Schema.

Add/remove a supertag

To add a supertag, anywhere in a node, type #[name of tag] and hit Enter to apply it to the current node.

To remove a supertag, hover over the tag and click the x that shows up.

Both actions can be done via the Command line (Cmd/Ctrl+K):

  • "Add tag"
  • "Remove tag"

Delete a supertag

Before you delete a supertag, consider whether it has been applied to any nodes. In the Supertag configuration panel, scroll down and see the stats on how many nodes it’s been applied to.

  • If you have used it on 0 nodes, it’s fine to just delete the supertag.If you have used it on 1 or more nodes, consider finding all those nodes and untagging them before deleting, or if it’s being replaced by another tag, merging the old tag with the new tag.
  • When you delete a supertag that is applied to other nodes, these nodes will show a trash can icon. This follows our principles about Deleting Nodes, Supertags, and Fields that have references elsewhere, which states that Tana will never delete data that is indirectly associated with another element that you delete.

How to delete a supertag:

  • Option 1: Go to Supertag configuration panel. At the bottom there’s an option to Delete the tag.
  • Option 2: Find the original Supertag definition and delete it.

Configure a supertag

There are two places you can configure supertags from:

Supertag page

When you click on a supertag, you’re taken to the Supertag page.

This page by default will be set in Tabs view, and show you a table of all supertagged nodes on the first tab.

You can do basic configuration of the supertag here like adding columns (which are fields) and saving them to the supertag template using the ✨Suggestion that pops up.

You can also add other tabs with different views that you want accessible on the supertag page, such as instructions on how to use the supertag, search nodes with different default views, or a reference to any node you might find useful to access while looking at the supertag page.

Supertag configuration panel

To open the config panel:

  • Click the wrench on the top right of the Supertag page
  • Cmd/Ctrl+Shift+click on a supertag

Colors

There are 12 colors available for supertags plus colorless (grey) to pick from.

Template

The supertag template is where you add fields, search nodes and regular nodes that will show on every node with this supertag.

There are several ways you can add template objects in the Supertag template section:

—Extend

Pick a supertag from the list that you want the current supertag to inherit template objects from. This allows you to set different default values, and also add template objects for greater specificity.

Example: A basic #task tag has the >Due date and >Project fields.

  • You can create a #design-task that is extended by the #task tag, then set the default >Project value to "Office Renovation".
  • You can also add a new field, >Reno team, so you can add individuals and teams that these tasks be assigned to.

—Add fields

Fields become attributes to the supertag object. Examples:

  • a #task can have fields like Status, Deadline, Priority, Team, Assignee
  • a #client can have fields like Company name, Email, Point of contact
  • a #project can have fields like Timeline, Lead, Team, OKRs, KPIs, Stage, Priority

Add fields: Type > at the beginning of a new node to add a new field. See Configuring a field on how to edit fields.

Add fields ad-hoc: Add a field under any tagged node (that isn't already part of the template), then right-click the field name > Add to template

Set default values for fields: Fill out the field value in the supertag template. Example: New #task always has >Status: Inbox

Set auto-initialize functions in fields: These will insert a field value, created at the moment when a supertag is applied to a node. Auto-initializations will trigger under the following conditions:

  • when the tag is applied to a node. In other words, if it already is applied, it needs to be removed and applied again for the auto-init to work
  • if the field doesn't exist already

Also, see: Auto-initialize

—Add search nodes

A search node can customize its results based on the supertag instance. Example:

  • a #project that looks up related #tasks
  • a #person that looks up related #meetings
  • an #author that looks up related #books

Make a search node:

  • Command line (Cmd/Ctrl+K) -> Find nodes
  • Type ? and click on ✨Create search node

See Query Builder for more on customizing your search.

—Add nodes

Add nodes just by typing them in. You can also add references to nodes.

Template node states

Template nodes have two states:

  • Dependent - They are connected to the template object still (i.e. they don't have their own nodeID)
  • Independent - They are disconnected from the template object (i.e. they have their own nodeID) because they've been edited in some way.

Dependent template nodes

Template nodes that are still dependent will change in sync with changes you make to the supertag config.

Template objects are similar to a projection, in that they are visible but not material. This means that template nodes cannot be searched, since they don't have their own unique nodeIDs separate from the template.

Independent template node

If template objects are edited, they instantiate as a separate node, receive a unique nodeID and will no longer be updated with template changes.

A template object from a supertag is considered edited if the following has happened:

  • It was edited in any way, even if you write and delete its contents fully
  • Field initiation was triggered
  • Its view options were changed
  • Getting a link or copying it, because it then needs a unique nodeID

Only a hard delete (Cmd/Ctrl+Shift+Backspace will clear the independent node, resetting the template node,

To “reset” a template node

  • do a hard-delete (Cmd/Ctrl+Shift+Backspace) to clear out the edits and populate it with the current template. If you already had content there that you want to save, move it out of the way first before doing the hard delete.

Optional fields

Optional fields allow you to specify which fields you use sometimes in a supertag.

This means you can add only the most important fields to your supertag template, while you move the rest to optional, ready to go when you need them.

To add optional fields:

  • Supertag config: Add a field in the Optional fields section right beneath the Supertag template
  • Add an ad-hoc field - twice: Add a field under any tagged node. If you add it again a second time under another node with the same tag, it automatically gets added as an optional field.
  • AI-enabled suggestions: If you use AI in Tana, fields will be automagically suggested for any new supertag you create.
  • Demote from template: Right-click on a field that is part of a supertag template, and choose Make optional

Once optional fields have been added, whenever you use that supertag again, the optional fields will be suggested in the following ways:

  • Button next to the tag
  • Suggested fields widget (appears only for a little while, then disappears after 24h)
  • Slash command inside tagged node

Show as checkbox

Turn this on to show a checkbox on all tagged nodes.

Done state mapping

Optionally map the checkbox state to one or more field values. This creates a two-way connection between a field value and the checkbox state. If you check/uncheck the box, the field value changes to the value you specify for either state.

Insert fields using >, and select the values for each state.

Build title / title expression

Build the title of a node from the values of its fields. Title expression are set in a supertag called "Build title from fields", and will apply to all its instances.

Title expressions composes field values from the node into a title using this the format: ${field name}

The title expression uses the actual name of the attribute.

You can also write between the fields, it could look like this; ${Objective} with the team at ${Date}

The existing name of the node can be accessed through ${name}. Note that if the title expression begins with ${name}, you will be able to edit the first part of the title directly on the node. In any other case, the node title will be locked for editing (even if ${name} appears later in the expression)

You can also specify a max length using ${field name|30…} which will show only the first 30 characters of a value.

Choose whether you want the placeholder to appear if the field is empty by appending a ? - either ${field name|?} or ${field name|30…?}.

In fields that have a list of nodes as values, we include all field values, not just the first one.

System attributes available in the title expression:

  • ${cdate} and ${ctime} - Created date and time in UTC, i.e. not local time
  • ${mdate} and ${mtime} - Modified date and time in UTC, i.e. not local time
  • ${sys:description} - Description field
  • ${sys:createdAt} - Time of creation
  • ${sys:lastEditedAt} - Time of last edit
  • ${sys:lastEditedBy} - User who last edited the node
  • ${sys:editedBy} - All users who ever created/modified the node
  • ${sys:owner} - Parent node
  • ${sys:dateFromCalendarNode} - The calendar node this node belongs to (Calendar date system field)
  • ${sys:doneTime} - Date and time this node was marked done

Nodes here are the same nodes that exist on the Supertag Page (see above)

Related content makes it possible to change the layout of a node or tagged item to show a references or search nodes next to the node. This can be used to show for example tasks or meetings on the Today page, or action items next to a meeting. Related content can be edited in the tag config for tagged items, or Ctrl/Cmd+K > Configure node for individual nodes. It's possible to choose two different positions for related content; on the right side or below the node.

Set child supertag

If you want to have a default supertag applied to all child nodes of any instance of this supertag, you can set the supertag you want here. This supertag will be applied to all new children.

On added/removed

You can trigger custom commands to run when this tag is added or removed.

To configure: Go to the supertag config > AI and Commands > Trigger commands on events. Add the command nodes here.

Use case examples:

  • When added, send a notification to a member of the workspace whenever a tag is added
  • When added, move the node to a specific place
  • When removed, change status of a field to Archived

Limitation: If a supertag is added/removed via API, it will not trigger as actions by API are currently not recorded as a user action. This is a limitation with how our API is implemented.

Supertag definition

What is a Supertag definition?

When you create a new supertag, a node is created that stores the configuration of this supertag. This is the Supertag definition and includes its name, template, and commands that show up as buttons, among other things. You access the settings of the supertag via the Supertag configuration panel.

How to find the Supertag definition?

There are two situations where you’ll encounter needing to use supertag nodes:

  • Creating a Search node
    • To find it here, just type “#” in the search expression editor and Tana will look for every supertag in accessible workspaces
  • Creating a Tana Template
    • To find it anywhere else, type “@#” and the name of the supertag. Supertag definitions show up in their color and hashtag at the front.

Merging supertags

See Merging duplicate nodes



Related release notes

  • fixedFixed bug where within search results, nodes in Option from supertag fields did not show the suggestion to tag new nodes. ()
  • fixedWhen you right-click on a banner and say "Use on all nodes tagged #x", we used to move the image to the tag banner, meaning that if you removed it from the tag, it was gone from the original node as well. We now leave it in place on the original node, even if you set it on a tag. ()
  • fixedFix bad-looking layout with banner on supertag pages ()
  • fixedCorrected inconsistent legacy implementation where node with done state mapping but no checkbox would show strikethrough. We now disregard done state mapping when there is no checkbox on the node. ()
  • improvedMoved "Create a supertag based on table" button to the view options menu ()
  • improvedIf you create a search under a tagged node, you can now right-click it and in the node editor bar, promote it to related content or to the supertag template. This gives you an easy way to customize the view of the node exactly the way you want, and means we can finally deprecate the use of this FAQ: https://tana.inc/faq/how-can-i-configure-the-view-of-a-search-node-that-exists-in-a-supertag-template Shoutout to Navigator Darren for providing the stopgap measure! ()

Related FAQs

Examples

  • How can I use system fields in Title expressions/Build title from field
    Sep 26, 2024

    Calculated system fields are prefixed with sys: to avoid being mixed up with user-created fields with the same name.

    Example: ${sys:Owner}

    Calculated system fields and their respective title expressions can be found here.

  • How can I find all tags that extend a tag?
    Sep 26, 2024

    One way is to create this search node:

    • >system field Tags : #tag (use supertag that was extended)
    • IS TAG

    Example:

  • How to use Tana Paste with supertags that have non-alphanumeric characters?
    Sep 26, 2024

    Tana Paste can usually parse supertags that are one word, such as #task. If a supertag has spaces, numbers or irregular characters, try wrapping the name in double brackets like this:

    #[[1'3$4'6]]

    If you want to grab the supertag definition, include the hashtag within the brackets, like this:

    [[#1'3$4'6]]

  • How can I add supertags on things that I send from Tana Capture?
    Sep 26, 2024

    While it isn't possible to tag things when you're sending things from Tana Capture, you can have Tana do some post-processing magic to convert written-out tags to real tags once they arrive the Inbox—no AI needed!

    1. This method uses a simple Tana Paste command that you can run on the Inbox node, which targets all new children that have "#" in them.
    2. Once you've created the command, you must add it to the On child added section of the Inbox node. You can find it by running the command Debug node on the title of the Inbox.

    Here's Theo describing the command:

    "All it does is paste the nodes that have # in them and that are not tagged, using Tana Paste.

    Say we add this through Tana Capture:

    buy milk #todo

    The command will paste that exact text back in with Tana Paste, where ${name} is buy milk #todo and ${sys:content} are any child notes that are present. Using Tana Paste, #todo will be added as a tag.

    Note: this creates a new node, so the created date will change, meaning you’ll lose the time that the node was captured through Tana Capture."

  • How can I find nodes based on a field value of an ancestor?
    Sep 26, 2024

    There is no way to build a search that is able to read the fields of an ancestor node. But, using title expressions, you can grab the field value of an ancestor node and have it part of the title of the node you're running the search on, making that information searchable.

    TLDR: Use the ${sys:owner} title expression to pick up content from ancestor nodes and their fields.

    This solution is great for Readwise users and came about when Maggie from the community wanted to search her Readwise highlights by the tags of the article/book it was taken from.

    To do this, use ${sys:owner.Field}, and repeat sys:owner as many levels up as you need to go to target the right ancestor. In the case of Readwise highlights, you usually need to go up two levels. Check out the demo video:

    Now with the information you need from the ancestor node baked into the title of the highlight itself, it can be used to search and filter those nodes.

    While this solution came up in the context of the Readwise integration, it is a reusable pattern that can be applied elsewhere.

Question

  • What is the difference between supertags in Tana and hashtags used in social media?
    Sep 26, 2024

    Here's a comparison between hashtags and supertags:

    • Primary function
      • Hashtags: identify keywords and trends that are relevant to a piece of content
      • Supertags: identify items and entries in one's data or knowledge-base
    • Placement
      • Hashtags: Can appear anywhere in the content
      • Supertags: Applies to the whole content (node), always appears at end
    • Search
      • Hashtags: Finds all content tagged with that hashtag across the platform
      • Supertags: Similar to hashtags
    • Value
      • Hashtags: Connects users to the broader conversation across the platform
      • Supertags: Connects users with their own content, improving knowledge management and retrieval
    • Shorthand
      • Hashtags: "This content is related to X"
      • Supertags: "This content is an X"
    • Examples
      • Hashtags:
        • Example: This content relates to [#topic1, #topic2]
        • #TaylorSwift
        • #ErasTour
        • #BlankSpace
      • Supertags:
        • Example: This item is a #[type of item/entity]
        • Taylor Swift #artist
        • Eras Tour #event
        • Blank Space #song

    Using supertags this way is a good starting point for getting to know them. Once you become more familiar, it's not a problem if you want to break the rules and use supertags like hashtags - as long as you know what the tradeoffs are and why you are doing this.

  • How do I create a relational database in Tana like in Notion or Airtable?
    Sep 26, 2024

    Because Tana is a graph, building relational databases is easy.

    Think of supertags as databases, and fields as columns in a database

    Let's use an example:

    • You have two supertags: #person and #project. You want to relate the two by assigning a team lead to each project that draws from person.
    • To relate each project to one team lead, we can make an Instance field called Team lead in the project. This allows us to select the #person supertag so this field will now create a dropdown of options from every instance of the person supertag.
    • Now, every time you assign a team lead to every project, on the other side you can look at a person and see what projects they are noted as Team lead for in the Reference section.

    There are many other ways to relate one database to another in Tana that go beyond what relational databases can do. That's because all information in Tana is stored as a graph, and on top of this we have flexible ways to build schemas with supertags and fields. It's everything a relational database has, with much more freedom and flexibility in the long run.

  • Why is my field not auto-initializing?
    Sep 26, 2024

    How auto-initialization works

    There could be several reasons why a field isn't auto-initializing.

    Currently, field auto-initialization is triggered only on the event where

    • a supertag is applied to a node, and
    • the field is in a placeholder state (i.e. doesn't exist/have its own nodeID).

    Fields will therefore not auto-initialize under the following events:

    • 1. When added anywhere as a solo field
    • 2. On nodes where the supertag is already applied and the field is added after the fact
    • 3. If the field is nested under a node in the supertag template. Fields have to be direct children to the supertag to auto-initialize

    The next question is likely: can I trigger auto-initialization somehow?

    As a result of how initialization is triggered today, there is an unintentional quirk that can be used to re-initialize fields.

    For fields that fall under category 2 (from the list above), it is possible to trigger initialization by applying any supertag to the node. The fields have to be in a placeholder state, or it won't work. Video demo:

  • My supertagged nodes are not updating with the latest changes I'm making! What's going on?
    Sep 26, 2024

    Supertag template nodes are directly connected to the template until the moment you edit or make a change to them in the instance.

    Editing them in any way separates them from the template, and any change you make to the template will not reflect on edited template nodes. This is part of Tana's way to never destroy information you have touched and edited.

    To refresh template nodes with the updated ones from the supertag template, consider first whether you have content you want to save, and move them out of the template element first. Then, perform a hard delete (Cmd/Ctrl+Shift+Backspace) to clear the stale node, and the template will immediately repopulate it.

  • How do I share a supertag from my private workspace to a shared one?
    Sep 26, 2024
    Currently, the easiest and most foolproof way to do this is to not share it but instead build the supertag, with its fields and anything else necessary for the supertag to work, from the ground up in the new space.

    That said, if you still want to move a supertag over that exists only in your private workspace, the main work is to ensure that there's nothing in the supertag that references something in your private workspace, otherwise it will appear as broken to others once it's moved.

    It's like packaging up a zip file. You can't just zip up a bunch of shortcuts, you need the real files in there or the recipient will only see broken shortcuts.

    You'll also have to remember to move over other things like field options, commands, and ensure that no saved view options contain elements from your workspace. Basically, you must ensure that nothing you're moving over from your workspace contains references from your workspace.

    To bring all nodes (except system nodes) into the supertags, fields and commands you want to move, use the command "Bring referenced node here". Alternatively, you can move each necessary node separately too if you for example want the field definition to exist outside the supertag. But the key is that everything that is connected to what you're sending over gets sent over too, otherwise there will be missing pieces.

  • What does this warning mean: "Fields nested under other nodes or fields will not work as expected"?
    Sep 26, 2024

    This warning pops up in the supertag template when there are fields that are indented (another word for nested).

    There are several "expected" behaviours of fields in supertags that only work when they are first-level nodes in the template, such as (and not limited by) the following:

    • Searching for nodes based on their field values (all #tasks with Status::Complete)
    • Viewing the node as a table, with fields as columns
    • Using fields to build title using title expressions

    If you do not care for any of the above uses, you can safely ignore the warning.

  • What does the system field "Number of nodes with this tag" do?
    Sep 26, 2024

    This system field is relevant only for supertag objects, and reveals the number of times a tag has been used.

    How to use it:

    • Make a search node with IS TAG - which will find all supertags in your graph
    • Display: Number of nodes with this tag

    It shows you how many nodes the tags have been applied to.

  • Can you have a different supertag applied to your day nodes based on a specific interval?
    Sep 26, 2024

    Background

    Recently the community discovered a peculiar thing was possible with regards to Calendar/Journal nodes. It was code that was put in a while back when we were thinking about how to revamp the calendar nodes, a project we had to shelf for other priorities. It was code that is the wee beginnings of how to do recurring calendar node templates.

    In the Journal node section of your settings, you'll see this:

    There's an expression you can use to define intervals of when you want certain supertags applied to certain calendar nodes. It is loosely based on the cron format (opens Wikipedia)

    In the field values for defining which supertag to use, you can nest the tags under a cron expression to have it apply only during a certain interval The expression takes on this custom format: DAY-OF-MONTH MONTH DAY-OF-WEEK YEAR

    Legend: Cron format

    DAY-OF-MONTH

    • 1-31

    MONTH

    • 1-12, or JAN-DEC

    DAY-OF-WEEK

    • MON-SUN, or 1-7

    YEAR

    • 2024

    Common syntax in cron

    • * (asterisk) represents "every" possible value for that field.
    • ? (question mark) is used to specify "no specific value" and is often used where the day of the month or day of the week should be ignored.
    • , (comma) is used to separate discreet values

    How to use in Tana

    Specify the cron expression as a field value, and nest the supertag you want used at that interval.

    Here are some pattern examples from u/syncretizm on Reddit

    Specific day of the week:

    • ? * FRI * = Every Friday

    Only weekdays:

    • ? * MON-FRI * = Every weekday

    Specific date in a month every year:

    • 31 12 * * = Last day of the year

    Last day of any month:

    • L * ? * = Last day of the month

    Every day in a specified month:

    • * 3 * * = Every day in March

    Here are even more patterns, courtesy of GPT

    A specific day of every month:

    • 15 * * * = The 15th day of every month.

    Specific days of the week throughout the year:

    • * * MON,WED,FRI * = Every Monday, Wednesday, and Friday of every week.

    First day of each quarter:

    • 1 1,4,7,10 * * = January 1, April 1, July 1, and October 1.

    Last weekday of a specific month:

    • LW * SEP * = Last weekday of September.

    Specific day of the week in a specific month:

    • * 11 FRI * = Every Friday in November.

    A day near the end of the month, every month:

    • L-3 * * * = The third-to-last day of every month.

    An annual event on a specific day and month:

    • 14 2 * * = Every February 14th.

    First Monday of every month:

    • 1-7 * MON * = The first Monday that occurs between the 1st and 7th of every month.

    Specific day of the week, only in certain months:

    • * JAN,MAR,JUL FRI * = Every Friday in January, March, and July.

    A specific day if it is a weekday:

    • 5 * MON-FRI * = The 5th of the month if it is a weekday.

    Skipping years for an annual event:

    • 10 10 * * 2023/2 = October 10th, starting in 2023 and every two years thereafter.
    Note that it will only apply to all new day nodes once the rule is established. It will not apply to existing nodes.
  • How can I bulk add/remove supertags?
    Sep 26, 2024

    Select the nodes, then type # or use the command Add tag to add supertags to all selected nodes.

    Use the command Remove tag to bulk-remove supertags.

  • Can I show an alternative representation of a field value when building a title?
    Sep 26, 2024

    Yes you can, with this kind of annotation:

    ${My field.Alternative}

    Where My field is the field you want appearing in the title, and .Alternative is the name of the field within the field value you want to target instead. This is great whenever you, for example, want to swap out written-out states for emojis.

    Example

    You have an Options field with some pre-determined options. For each option, add a field like Icon and put a different value for each.

    When writing out the title expression in the supertag configuration, use the 1. field name in the 2. title expression format, plus add the field (in this case, "Icon") you are targeting inside the field value which will 3. make the value of the new target field appear instead.

    You can go deeper with the targeting by adding more periods. So, you could have something like Field.Field2.Field3 for example.

    For more information on title expressions, check out this section in the Supertag doc.

  • I'm unable to delete nodes/fields in the supertag config, what's going on?
    Feb 02, 2024

    The tag might be extended, which means that it's inheriting fields from another tag. Check right above the supertag template to see if it has been extended: