• 

Tips: How to read Tana queries

Robert S. posted this question in the Tana Slack Community:

Is there a resource on understanding the syntax of and order of operations for tana commands and live search? Wondering how everyone learned it if it's not in the help center.

Great question! In this article, we hope to answer this question with some helpful tips on how to "read" Tana searches. Many of these principles will also apply to things like Command nodes. Once you can follow their logic and how they're built, they become open books that can both teach and inspire you to construct your own creations in Tana.

If you're more interested in learning what individual functions and operations do, our Navigators created a template full of live search examples that allow you to interact with each search expression to see how they work. Access it here (link opens Tana).

Read it like a sentence

Let's say you're looking for a property that meets all the criteria: a house, on 5 acres of land, and around $750k in price. If you were writing this into Google search, it would be something like this:

house AND 5 acres AND $750k

The "AND" is what's called a boolean operator. Other common boolean operators include "OR" and "NOT", both of which also exist in Tana, we just use them slightly differently than you would in a conventional Google search scenario as we will see below.

Read it like a list

When building a search expression in Tana's query builder, you would write the above query using the AND field operator to wrap all the criteria:

Notice in the screenshot above that the field is a purple colour, signifying that it is a special Tana field. These fields are available through looking them up in an empty field, and also via the buttons at the bottom of the window (1)

If you want to read it more like a sentence, imagine little ANDs between each of the nodes, as you can see in the query linter at the bottom (2).

(By the way, a "linter" in this context means that it removes the visual "fluff" from the query builder interface, showing the logic of the search expression in plain code instead)

However, as the yellow box suggests (3), the query builder already has an AND wrapped around the outside of it, so for the criteria on the first indentation level it is not necessary to wrap it in an AND operator of your own. Fixing this will make it look like this:

When a criteria is just text in a plain node, it tries to match any text in any node that exists in Tana. It is more realistic to imagine that this property information would live in Tana in a more structured way. So, here's an example of a #real estate listing supertag with the following fields:

Back to our query builder, to be more precise about what we're looking for, we'd adjust it to this:

This kind of search where you are looking for a subset of results from a particular supertag is very common in Tana. But what if you have more than one thing you want to look for in the same query? Can you search for your dream house OR your dream apartment OR your dream bungalow, all at the same time?

Why yes, yes you can.

Read it like a list within a list (nesting)

Now is time for us to introduce the concept of nesting queries.

You can ask Tana different queries that will appear in the same stream of results. To do this, you need to nest them within an OR operator:

Imagine little ORs appearing between your separate dream home queries, because we're now asking Tana to return either a house option OR an apartment option OR a bungalow option.

Notice that once we moved the criteria away from the first indentation level, the built-in AND operator doesn't apply to them anymore so we now have to wrap each set of criteria in their own separate AND operators.

Reading this query out as a sentence, as the linter is showing, would sound something like this:

Find all #real estate listings that are either house options on 5 acres of land and around $750k, OR apartment options on the subway with 3 bedrooms and for around $850k, OR bungalow options on the lake and for around $650k but NOT near a highway, and each listing must not be closed.

This query is starting to sound a bit too much like a run-on sentence, with the risk of any human reading this losing track of the search logic mid-way. For nested queries, it can therefore be easier to break up the reading experience per major indentation level, starting from the left-most level and working our way to the right as we get deeper into the query. The below screenshot shows how the same example looks like in Tana's Live Query, with a suggested reading order that breaks it up into separate sentences:

Following the suggested reading order, reading the query would sound more like this:

• 1-3: Find any results that are #real estate listings, AND any one of these three options, AND are not closed.
• 4-9: Either it will match Option 1 criteria, OR Option 2 criteria, OR Option 3 criteria.
• 10-11: Option 3 must NOT be near a highway.

Instead of one long sentence, we've now broken it up into three sentences, one for each indentation level of the query. These are much simpler and easier to understand than the long, run-on sentence.

Here's another query you can try to read. The answer will be below the screenshot, so don't scroll down too fast if you want to try doing it yourself first!

📝 Quick note: As you'll see in the example below, Tana has certain keywords that are simply written out to perform a certain operation. Some of them include:

• TODO, which finds all nodes that have a checkbox on them,
• NOT DONE, which finds all unchecked nodes, and
• DONE, which finds all checked nodes.

To see a list of all special keywords, go to the Live Search Help page and scroll down to the table called "Plain text node using one of these keywords".

Here's how this query could be read:

• Find any results that are #todos, AND based on one of two options.
• The first criteria is to find all #todos that are not done
• The second criteria is to find all #todos that are done, AND edited the past day (24 hours).

What does this mean? Whoever made this query wanted to show all "not done" todos, while also including recently "done" todos (but not all completed todos ever). In order to accommodate the different time scopes between open and completed tasks, the query had to be made as two separate sub-queries.

Summary

• All queries are simply matching a long list of criteria that can combine matching all (AND), any (OR) or none (NOT) of them.
• Tana uses fields to represent these common search operators (AND/OR/NOT).
• In the query builder, check out the query linter which is at the bottom of the box. This shows you what the search expression looks like written out as one long "sentence", without the fluff.
• Multiple queries can exist in one search expression as nested sub-queries by using the OR operator.
• Break down complex queries by interpreting sentences for each indentation level, making them easier to read for humans.

I hope this walkthrough on how to read Tana queries was helpful! If you have feedback to give on this article, I welcome you to send them my way via email (fei at tana.inc) or DM me on the Tana Community Slack.