Since v4.6 queries are action code expressions in a conditional form that must resolving to true/false statements. This also means that from v4.6 the old special query codes are deprecated in favour of action operators of the same name, without the # prefix.
Agent queries results will only list each item once, even if the original and/or one or more aliases are all within the scope of the query. An exception is allowed, where it is needed to locate an original and all its aliases, by using a contains() query based on the item's name as this will match all containers of both that note and all of its alias(es).
Agents - including smart adornments, can match notes, (including containers), separator notes, aliases (from v4 onwards), other agents but not map adornments. Adornments are the one exception to an agent's ability to query any object in the document.
References in the listings below to "BooleanAttribute", DateAttribute", etc.," refer to any system or user attribute, that is of the data type specified. Thus "BooleanAttribute" implies any attribute of the data type "Boolean".
Note that an agent's query only controls which notes are matched and whose aliases are added as children of the agent. Anything done to the (aliases of) matching notes is controlled via the the code stored in the AgentAction attribute. Action code can also be seen via the agent's Create or Rename dialogs.
Consider this very simplistic example of a query (second version is deprecated legacy code syntax):
$DateAttribute == "date"
Here, Tinderbox must decide if the user is attempting to call (incorrectly) the date() function or simply wishes to match the string 'date'. The double [sic] quotes in the latter example tell Tinderbox this is a string literal. For long-term users, changing to always quoting strings like this as a matter of course should pre-empt hard to spot errors in more complex queries.
Although queries used to allow inclusion of export codes this is now strongly deprecated in favour of action code where possible. Examples of legacy versions:
$MyString(^title^) DO NOT USE THIS!
$MyString==^title^ DO NOT USE THIS!
..both the above will resolve the export code (as a regular expression match or an exact match respectively) before processing the query. Now these would be coded as:
$MyString($Name)
$MyString==$Name
Note that the caret (^) character has a special meaning for Tinderbox, you need to escape it, but in a different way, use ^^ and not \^.
Tinderbox regular expressions recognise a number of patterns containing the backslash character. Some common examples are:
\s matches any whitespace character
\S matches anything EXCEPT a whitespace character
\w matches a word character, such as a letter
\W matches any non-word character, such as punctuation
Otherwise Tinderbox uses normal regular expression escaping (i.e. no double-escaped backslashes). For example:
this\sthat
recognises
this&[tab char]&that
as well as
this that
Agent actions can refer to the attributes of the current agent using the agent designator, and smart adornments can similarly use the adornment designator. For example:
Query: $Status=="Important"
Action: $Color=$Color(agent)
This agent gathers all "Important" notes and sets their colour to match the colour of the agent. Note that this is different from
Action: $Color=$Color(this)
since "this" refers to the note being gathered, and is also different from
Action: $Color=$Color(parent)
since "parent" is the parent of the original note, not the parent of the newly-made alias.
If the query string does not parse the agent's query will be disabled. If the query entered into the query box on the Create/Rename agent dialog does not parse, the dialog will not dismiss until the query (or action code) parses.