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 email@example.com to provide your feedback.
Introduction to Part Of relationships
"Part Of" relationships are quite common in our world:
(is a part of) Ericaceae family
(is a part of) Plantae kingdom
(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:
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:
02: Green Algae
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.
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".
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.)
USE IN SEARCH
Now, let's set up our business:
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:
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.