PartOf & COMPONENTS_REC

I'm a new help page!

This is our first pass writing documentation for this feature. If something isn't explained well, or you're still confused after reading this, we'd love to hear from you on where we can do better! Please reach out to @Fei in the Tana Slack Community or email her at fei@tana.inc to provide your feedback.

Introduction to Part Of relationships

"Part Of" relationships are quite common in our world:

  • Blueberry

    • (is a part of) Ericaceae family

      • (is a part of) Plantae kingdom

  • A member

    • (is a part of) Group X

      • (is a part of) Network Red

  • Empire State Building

    • (is part of) Fifth Avenue

      • (is part of) New York City

It is also common to use any of the parts as values for other things. In fact, we prefer to go as detailed as possible:

  • Business A

    • is located in Empire State building, floor 34

    • is a member of Group X

However, lets say we write a query for:

  • All businesses located in New York City, and are members of Network Red.

We want the search to return results such as Business A, but we didn't write New York City, or Network Red. We know the result we want, but how can we make this work?

This is where the semantic relationship "Part Of" comes in. Nodes can have "Part Of" relationships defined through its fields.

The way it works is that a node has a field that can make explicit that it forms "Part Of" the node inserted as the value of the field.

In an outline structure, it abstractly looks like this:

  • 01: I'm the "sum parts of" all the child nodes nested under me

    • 02: I'm "part of" node 01

    • 03: I'm also "part of" node 01, and the "sum part of" nodes 04 and 05

      • 04: I'm "part of" node 03, 01, but not 02

      • 05: I'm also "part of" node 03, 01, but not 02

In practice the same structure looks like this:

  • 01: Plantae

    • 02: Green Algae

    • 03: Spermatophyte

      • 04: Conifers

      • 05: Flowering plants

This means that all nodes downstream of node 01 are part of it. But node 05 forms part of only its direct ancestors 03 and 01.

SETUP

Sketch a plan of the semantic relationships, think of them like this:

  • The Empire State Building... is part of the Street called Fifth Avenue, which... is part of the City called New York City

  • Mortgage, Bills and Expenses are all part of my Budget

Make an Options field for each relationship, go to the bottom of the field config and find the "Advanced" toggle, and turn on "Field has Semantic function" > "Part of".

The field type Options has a new configuration: Semantic function

To define the semantic relationship in Tana, it will end up looking something like the below: (Note that field names have "(is part of)" added for ease of reading the relationships, and are not necessary for the setup.)

The setup of semantic relationships via fields

USE IN SEARCH

Now, let's set up our business:

A node that has fields which uses information with semantic meaning

Important: Keep the definition and use of semantic information separate. When using information that has semantic function, we recommend using different fields than the ones you have set up in your semantic map. If you use the same field (like "Street" in the Empire State Building example above), the information you enter for the business risks getting included as part of the semantic relationship. Here we use >Location and >Membership, two fields that are not used to define semantic relationship, to pull information from the semantic relationship.

To use the semantic relationship "Part Of" in search, use the new search expression COMPONENTS_REC, or components recursive.

  • Components are all the Parts of a whole

  • Recursive means that it will search every node downstream of the referenced node that say they're "Part Of" any node that is part of the referenced node.

Think of COMPONENTS_REC as meaning "any part of" a node that has semantically relevant nodes connected to it via "Part Of".

The search query will look like this:

Live Query on "All businesses located in New York City, and are members of Network Red", using COMPONENTS_REC

The description text in the bottom of the search query window gives us clues as to what the query is doing. The query looks for all nodes that match:

  • being tagged #business AND

  • Location equals anyPartOf node "New York City" AND

  • Membership equals anyPartOf node "Network Red".

Note: COMPONENTS_REC doesn't work as a string/plain text match, it has to be a reference to the actual node that has the relationships you're searching through.