The Query Language

You’ve been using search to find nodes by text, and tagged to find nodes by supertag. But what if you want to find all tasks that are marked “Done” and were created this month? Or all contacts in a specific company? That’s where the query command comes in — it’s like SQL for your Tana data.

By the end of this lesson, you’ll be able to construct filtered queries using field conditions and operators.

Query vs Search

First, understand when to use which command:

# Search: finds "meeting" anywhere in text
supertag search "meeting"

# By tag: all meetings
supertag search --tag meeting

# Query: meetings with specific conditions
supertag query "find meeting where Status = Completed"

Query is for when you need to filter by field values, dates, or combine conditions.

Basic Query Syntax

The query command follows this pattern:

supertag query "find <supertag> [where <conditions>]" [options]

Simple queries:

# All todos
supertag query "find todo"

# All todos where Status is "Done"
supertag query "find todo where Status = Done"

# All contacts at a specific company
supertag query "find contact where Company = Acme"

Try running a query that finds tasks with a specific status in your own Tana data.

Operators

Available operators for conditions:

# Todos NOT completed
supertag query "find todo where Status != Done"

# Notes containing "AI" in the name
supertag query "find note where name ~ AI"

# People with multi-word names (use single quotes)
supertag query "find person where name ~ 'John Smith'"

# Todos without a due date
supertag query "find todo where 'Due Date' is empty"

The ~ (contains) operator is your friend for partial matches. Use single quotes around values with spaces. Use is empty to find nodes where a field hasn’t been set.

Combining Conditions

Use AND and OR to combine conditions:

# Active todos due this week
supertag query "find todo where Status = Active AND 'Due Date' < 7d"

# Contacts at Acme OR Google
supertag query "find contact where Company = Acme OR Company = Google"

# Complex: Active high-priority tasks
supertag query "find task where Status = Active AND Priority = High"

Build your queries step by step, adding conditions one at a time to see how each narrows the results.

Practice

Exercise: Query Your Todos

1. Find all your todos: supertag query "find todo"
2. Filter to a specific status: supertag query "find todo where Status = Done"
3. Try combining conditions with your own field names

Checkpoint

✅ You can construct a query that returns exactly the subset of nodes you want.

Key Takeaways

1. query filters by field values; search finds text
2. Use where with conditions like Field = Value
3. Combine conditions with AND / OR

What’s Next

We’ll add time-based filters to analyze when things were created or modified.