The find(scope) operator can be used to produces a list of matching paths, i.e. the $Path of matched objects. The operator's scope argument is supplied in the form of a query. Notes matching the query form the output list. The latter being List-type data it is thus not de-duped like an agent's results. The background to the find() operator was as a custom designator, allowing an ad hoc query where a fixed designator (e.g. 'children') might normally be used.
It is important to note this method does not use agents directly, as find() is intended to run in actio code. Where an agent's query populates the agent container with aliases, a find(scope) returns a path for any note matching the scope argument's query. Thus matches cannot be seen in a Map or Outline view as with an agent - a point to bear in mind if seeing matches in the UI is important to the user.
A key difference of using find() vs. $AgentQuery to query is that find() returns originals and all aliases that match whereas an agent returns only one match per original object favouring an original over aliases. Thus if note "Project X" has two aliases, an agent will match one item (the original) whereas find() will return a list of three items (the original and each alias).
The $IsAlias boolean system attribute lets find() return only aliases or only originals. Thus for note 'Test', this will return a list of the paths to each alias of Test but exclude the original:
find($Name=="Test" & $IsAlias==true)
In contrast, this returns only the original:
find($Name=="Test" & $IsAlias==false)
Note that the boolean tests for $IsAlais can also be written in short for. True: $IsAlais. False: !$IsAlais.
Want to find all the aliases of all notes whose name contains the string "Test"?
find($Name.contains("Test") & $IsAlias)
The above will match names like "Test", "My Test" as well a "Tester" but not "Intestate". By using .icontains() for case insensitive matching, "intestate" would be found.
find($Name.icontains("Test") & $IsAlias)
Want to exclude aliases that have 'Exam' in their path?
find(!$Path.contains("Exam") & $IsAlias & $Name.contains("Test"))
Want the original find to exclude aliases that are agents' contents?
find($Name.contains("Test") & $IsAlias & !$AgentQuery(parent))
Want to display the resulting list as line-by-line entries in $Text?
$Text = find($Name.contains("Test") & $IsAlias).format("\n")
Notice how the $IsAlias term in the scope query is used to filter out either original or alias.
See also—notes linking to here: