Advanced Searches

FoxTrot Professional Search provides extremely powerful search capabilities, some of which require a certain amount of dexterity. Here are a few example cases:

FoxTrot Queries

You may use one or multiple basic criteria (e.g. [includes all of the words], [includes at least one of the words] etc) to express your query, but you can also use matches the FoxTrot query to express it in a single text string. The syntax of these queries is documented in the Help menu.

Browse All Documents

Instead of searching for some specific keywords, you may want to browse your entire indexed dataset (or just a subfolder), and use the Categorization pane to focus on specific files.

To do this, use the all items of type criterion, with any file or folder type.

This can be useful especially when using the thumbnails mode for the result list.

Search by File Name

You may use the file name criterion, but sometimes this is not precise or flexible enough. In this case, use then apply advanced filter instead (or as a complement). If you do not use any other search criterion, then FoxTrot will suggest to add an any file or folder criterion, as filters can only be used in addition to another criterion, but this will be slower.

Once then apply advanced filter is selected, you may use some basic operators (contains, starts with, ends with…) or even some very powerful regular expressions¹, on either the file name, its extension, or the full path (or even on the entire file contents).

Please note that file name filters, like other criteria, are applied to the the index and not directly to the filesystem; thus if some files have been added, deleted, moved or renamed since the index was updated, the results won't reflect those changes. Similarly, you can't search for files in an unindexed folder; but you can search an unmounted volume.

Here are a few examples:

• to search for any c++ source code file (there are several possible file name extensions), use: [all items of type] [any file or folder], [then apply advanced filter] [extension] [is exactly one of the strings] [ignore case, multiple strings] [cpp—c++—cxx] (use the em dash character, i.e. option-dash, to separate strings)
• to search for a file inside a folder with a given name, no matter where that folder is located, and no matter how deep the file is in the folder hierarchy, use: [file name] [includes consecutive words] [filename.pdf], [then apply advanced filter] [full path] [contains the string] [ignore case] [/folder name/]
• to search for all images (especially using the thumbnail view) that are contained inside any application package (provided that including: files inside packages is enabled in the indexed data pane of the manage indices window), use: [all items of type] [image], [then apply advanced filter] [full path] [contains the string] [ignore case] [.app/]
• To find all video files whose name begins with any formatted date (e.g. 1984-01-24 presentation.mp4), use: [all items of type] [video], [then apply advanced filter] [file name] [contains the regular expression] [case insensitive] [^(19|20)?\d\d-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01]) ]
• to search for any file stored in a folder with the same name as the file itself (excluding the extension) (e.g. /Users/me/Documents/Report/Report.pdf), use: [all items of type] [any file or folder], [then apply advanced filter] [full path] [contains the regular expression] [case insensitive] [/([^/]+)/\1(\.[^/.]+)?$]

Neighboring Words

The includes neighboring words criterion can be used to find multiple words that occur near each other. You can use either single words, quoted strings, or wildcards, for example:

• to find documents that contain the 3 expressions [john doe] [condominium] and [new york], with no more than 100 other words between them, use: [contents, any metadata or file name] [includes neighboring words] [around a few lines - 100 words] ["john doe" condominium "new york"]
• to find documents containing [happiness] and any word starting with [slave], with no more than 100 other words between them, use: [contents, any metadata or file name] [includes neighboring words] [around a few lines - 100 words] [happiness slave*]

Dates

There are two very different ways to search for files created, or modified, in a given date range: categorizing, and filtering.

Categorizing by Date

FoxTrot uses some predefined date ranges, such as yesterday, this month, two years ago etc. All documents found are categorized according to these ranges, and a histogram chart shows how they are distributed. The height of each bar indicates how many documents were found in that date range, and the saturation of the bar’s color indicates the average relevance of those documents. Note that some documents may belong to more than one range: 6 months ago may overlap with last year. You may select one or more predefined ranges in the chart. Use the contextual menu to toggle between modification and creation dates, and to choose the graph's vertical scale.

Filtering by Date

For a more precise date search, use then filter by date. You can then search for any arbitrary date range, either relative (e.g. less than 5 weeks ago) or absolute (e.g. after January 24, 2020).

Searching for Dates as Regular Expressions

In addition, you may also use the regular expression¹ engine to search for some date strings within document contents, or file names. For example:

• to search for the date [January 24, 1984] in any standard English format, in addition to the word [macintosh], use: [contents, any metadata or file name] [includes all of the words] [macintosh], [then apply advanced filter] [contents] [contains the regular expression] [case insensitive, multiple strings] [\b0?1([/.-])24\1(19)?84\b—\bjan(uary)? +(24(th)?|twenty[- ]four(th)?),? +(19)?84\b]

Partial Words, Case, Accents, Punctuation and Special Characters

By default, FoxTrot searches only for whole words (i.e. whole strings of consecutive alphabetic and numeric characters) that match the words in your query. It ignores case and accents, and treats punctuation characters as word separators.

More specifically, a word (or a “textual entity”, to use a term with no linguistic meaning) is defined as a sequence of consecutive characters that fall into the following Unicode categories: Letter (Lu, Ll, Lt, Lm, Lo) or Number (Nd, Nl, No). For example, the strings [H2O] or [ft²] are both single words, whereas [eco-friendly] consists of two separate words separated by some punctuation. In addition, any Symbol character (Sm, Sc, Sk, So), as well as any Chinese, Japanese or Korean Ideographic character, and any character with a Unicode codepoint higher than U+10000 (e.g. emojis, many ancient or historical scripts, and some regional scripts that are still in use), is also considered by FoxTrot as a whole word (even when contiguous to other high codepoint, Ideographic, Symbol, Number or Letter characters).

You may search for words starting, ending, or containing a substring by using the * wildcard as a prefix or suffix: [fox*], [*trot] and [*ox*] will all find the word [FoxTrot].

In some cases, you may want to consider capitalization or accents (e.g. you don't want to find [us] when searching for [US], or to find [resume] when searching for [résumé]). You may also want to search for a sequence of words that contains some punctuation or other non-alphanumeric characters (e.g. you don't want to find [Rh-] when you search for [Rh+]; or you don't want to find [Sagittarius A] when you search for [Sagittarius A*] - and you actually want to find the * character, and not interpret it as a wildcard; or you don't want to find the IP address [12.34.56.78] when you search for the phone number [12-34-56-78]).

In these cases, use includes the exact string. However, there are some important limitations that you should be aware of:

• the search string must contain at least one word (i.e. at least one alphabetic or numeric character)
• if the search strings starts with, or ends with, an alphabetic or numeric character, that character will be found only if it is the first, or the last, character of a word in the document. I.e., you can't use includes exact string to search for partial words (even if you use the * character, which is searched literally)

An alternative to includes the exact string is to use then apply advanced filter with contains the string. It does not have these limitations, but is much slower. For example:

• to find a smiley, use: [all items of type] [any file or folder], [then apply advanced filter] [contents] [contains the string] [ ] [;-)]. Please note that for performance reasons, you should reduce the number of files to which the filter is applied whenever possible, by using some restrictive criteria instead of [all items of type]

Another alternative is to use regular expressions; see below.

Regular Expressions

FoxTrot performs near-instantaneous searches because it searches for whole words (or parts of words, when using * wildcards) in its index. In some situations, you can't express your query in terms of whole words or parts of words, but you may express it using regular expressions¹. Because FoxTrot stores a compressed version of the plain text content of your documents, it can also perform this type of unindexed search very efficiently; it typically takes only a few seconds to process gigabytes of documents. Whenever possible, use some restrictive criteria before applying a regular expression filter, but if necessary, use the [all items of type] [any file or folder] criterion:

• to find one of the strings [Sagittarius A] or [Sgr A] that is not immediately followed by an asterisk character, use: [contents] [includes at least one of the words] ["Sagittarius A" "Sgr A"], [then apply advanced filter] [contents] [contains the regular expression] [case insensitive] [(Sagittarius|Sgr) A(?!\*)]
• to find any word consisting of 2 to 5 characters (including accented or non-Roman letters) immediately followed by an asterisk character, use: [all items of type] [any file or folder], [then apply advanced filter] [contents] [contains the regular expression] [\w, \d, \s and \b also apply to Unicode characters] [\b\w{2,5}\*]
• to find any group of 2 Han (Chinese) characters that are not immediately preceded or immediately followed by another Han character: [all items of type] [any file or folder], [then apply advanced filter] [contents] [contains the regular expression] [ ] [(?<!\p{Han})\p{Han}{2}(?!\p{Han})]
• to find all PDF documents whose indexed content length is 100 characters or less, use: [all items of type] [PDF], [then apply advanced filter] [contents] [contains the regular expression] [. also applies to newlines] [^.{0,100}$]

Extended Attributes

Custom metadata attributes can be added to any file using extended attributes, either by third-party applications, or from the terminal. These extended attributes are indexed by FoxTrot, and can be found as part of the other metadata field. For example, to add a publication.year attribute to a file, type the following command in Terminal.app (replace year and path with the actual publication year and path of your file):

xattr -w com.apple.metadata:publication.year "year" path

To search for a specific custom attribute, add a [then filter by Spotlight attribute] criterion, select [other Spotlight attribute…] from the popup menu, click the [Add…] button, enter the extended attribute key (without the "com.apple.metadata:" prefix), as well as a human-readable name and description, and click [Add]. Make sure the [in menu] checkbox for this attribute is checked, and click [OK]. Then select this attribute in the [then filter by Spotlight attribute] criterion popup menu.

When you use [then filter by Spotlight attribute], the value of that attribute should appear in the excerpt column.