TQL — the Trakr Query Language

Shape of a query

A query is a sequence of field operator value clauses joined by AND or OR, optionally grouped with parentheses, optionally negated with NOT, and optionally sorted.

field operator value [AND | OR] … [ORDER BY field [ASC | DESC]]

Queries you would actually write

# my open work, most urgent first
project = OPS AND statusCategory != DONE AND assignee = currentUser()
  ORDER BY priority DESC, updated DESC

# anything that went through review and closed last quarter
status WAS "In Review" AND resolution = DONE AND resolved > -1q

# tickets that were handed off — who did Luc give away?
assignee CHANGED FROM "luc.dupont" AND updated BETWEEN -14d AND now()

# unassigned and due before the week is out
project = SUP AND assignee IS EMPTY AND due < endOfWeek()

# full-text across summary and description
text ~ "certificate expired" AND created > -7d

# service-linked work with real time on it
service = "Payments" AND label IN (regression, hotfix) AND timeSpent > 2h

# everything that blew a first-response target
firstResponseBreached = true AND slaDue < now() ORDER BY slaDue ASC

# the backlog in the order the team actually ranked it
project = OPS AND statusCategory = TODO ORDER BY rank ASC

What the parser refuses, and how it tells you

Validation returns an error with a position in the query string, so the editor can put the caret where the problem is. The cases it names:

1. Unknown field — refused with a suggestion of the closest real field name.
2. Unbalanced parentheses — refused with the position of the offending bracket.
3. Unclosed quote — refused rather than swallowing the rest of the query as a string.
4. Operator invalid for the field type — a text operator on a date, an ordering operator on a set.
5. Historical operator on an unsupported field — named explicitly, so you know it is the field and not the syntax.
6. Missing value — a clause with an operator and no operand is an error, never an implicit "anything".

Autocomplete works against the same metadata the validator uses — field names and their values — so most of these never reach the point of being submitted.

The badge toggles

The TQL badge on the search bar switches to AI. You ask a question in your own words; Trakr returns generated TQL — never results. The query appears under the bar, editable as ordinary TQL, and it is run through the same parser and validated before it is handed back. If the model produces something the parser refuses, you never see it.

This is the whole design argument. A natural-language search that returns rows asks you to trust an answer you cannot inspect. Returning the query means you can read it, correct it, save it, and re-run it tomorrow with identical semantics.

you type ›  high priority bugs Luc picked up this month that are still open

trakr returns ›
type = Bug AND priority >= High AND assignee = "luc.dupont"
  AND statusCategory != DONE AND created >= startOfMonth()

The people resolver

Models are bad at usernames and good at names. A TqlPeopleResolver injects your organisation's own directory into the prompt in the form luc.dupont (Luc Vermeulen), then rewrites a loose assignee ~ "Luc" into an exact assignee = "luc.dupont".

• Ambiguous names Left alone, never guessed
• Customer accounts Excluded from the directory
• currentUser() and lists Never rewritten
• Directory cap 200 accounts

Past 200 accounts the roster is omitted rather than truncated — a half-directory would make the model confidently rewrite the wrong person, and a resolver that is sometimes wrong is worse than one that is sometimes absent.

AI features run against whichever provider your organisation configured, including self-hosted and OpenAI-compatible endpoints. See AI in Trakr.