Home | Appendix

|  |  | Search Prefixes

DEVONthink supports a wide variety of searchable attributes. These include common attributes, like names or tags, but also include document or DEVONthink-specific items, like word counts or custom metadata you've defined. Similar to searching with Spotlight or some other applications, the use of search prefixes is not only supported, but encouraged. These take the form of a prefix and a prefix operator, e.g., `name:`, followed by the search term. Search prefixes These prefixes are automatically applied when you choose criteria in the advanced search editor but they can also be manually entered in the search field. In the following list, we show the human-readable names you'd see in the criteria editor. In parentheses are the corresponding raw query values you'd type in a toolbar search or use in scripting. Content: Text contents in a file. (`text`) Metadata: The metadata for a file. (`metadata`) Name: The name of an item. For documents, this is distinct from the filename and does not include the file extension. (`name`) URL: The associated URL. (`url`) Finder Comment: Spotlight Comments. (`comment`) Author: The name of the sender of an email. (`author`) From: The email address of the sender of an email. (`docAuthorEmailAddresses`) Recipient: The name of a recipient of an email. (`docRecipients`) To: The email address of a recipient of an email. (`docRecipientEmailAddresses`) Title: The title of a file. The title may be distinct from its name, e.g., a song title for an MP3 file. (`docTitle`) Comment: The RTF-specific comments for a file. (`docComment`) Headline: A headline applied to some files. Rare. (`docHeadline`) Subject: The subject line from an email. (`docSubject`) Description: The description found on some files, typically images. (`docDescription`) Keywords: The PDF or RTF specific keywords for a file. (`docKeywords`) Organization: The company specified in imported links or vCards from the Contacts application. (`docOrganization`) Copyright: Copyright information in the metadata of a file. (`docCopyright`) Album: The album information from media metadata, e.g., MP3 files. (`docAlbum`) Composer: The composer information from media metadata, e.g., MP3 files. (`docComposer`) Creator: The process or application used to create a file. (`docCreator`) Producer: The producer of a file, usually applied to media files. (`docProducer`) Aliases: Aliases applied to an item. (`aliases`) Tags: Tags applied to an item. (`tags`) Label: The color label of an item, from 0 (no label) though 7 or by name, e.g., Important. (`label`) Rating: The star rating of an item, from 0 (unrated) through 5. (`rating`) Width: The width of a document in points, i.e., the width multiplied by 72. (`width`) height: The height of a document in points, i.e., the height multiplied by 72. (`height`) length: The number of pages in a file or length of a media file in seconds. (`length`) size: The size of an item in bytes, KB, MB, or GB, e.g., `size >= 50 MB`. (`size`) wordcount: The number of words in the contents of a file. (`wordcount`) charactercount: The number of characters in the contents of a file. (`charactercount`) hits: The number of times a file has been viewed or opened. (`hits`) filename: The name of the file in the file system, including the file extension. (`filename`) extension: The extension of a file, e.g., txt. This also supports an Any Extension option to filter filenames having or lacking an extension. (`extension`) kind: Supports `any`, `group`, `smartgroup`, `tag`, `ordinarytag`, `grouptag`, `text`, `rtf`, `formattednote`, `markdown`, `html`, `webarchive`, `xmlfile`, `propertylist`, `image`, `pdf` for all PDF documents, `pdf+text` matching PDF documents with a text layer, `quicktime`, `video`, `audio`, `bookmark`, `feed`, `news`, `script`, `sheet`, `email`, and `other`. (`kind`) Item prefixes: These special prefixes are for state-based queries, like if items are replicants or contains aliases. They all follow the form of `item:<specified state>`, e.g., `item:locked`. You can specify the state of items, i.e., is or is not. The available options are as follows: Replicated: Matches items that are replicants. (`replicated`) Duplicated: Matches items that are duplicates. (`duplicated`) Indexed: Matches items that are indexed, not imported. (`indexed`) Pending: Matches items whose contents aren't downloaded and available. (`pending`) Tagged: Matches items with tags applied. (`tagged`) The other option is specifying whether items do or don't contain a certain property. For example, you can search for items containing aliases and the `item:<specified state>` syntax is also used. This includes the negated form. Here are the searchable properties: Aliases: Matches items with aliases. (`aliased`) Annotation: Matches items with an associated annotation file. (`annotated`) Comment: Matches items with a Finder comment. (`commented`) Data: Matches items with child items, e.g., a group with items contains data. An empty group can be found via `item!:data`, meaning the item does not contain data. (`data`) Metadata: Matches items with metadata. (`metadata`) Reminder: Matches items with a due date set. (`reminded`) Script: Matches items with a script applied in the Info inspector. (`scripted`) Thumbnail: Matches items with a thumbnail applied. (`thumbnail`) URL: Matches items with a URL set in the Info inspector. (`url`) Marked: Item states shown in the Flag column in the item list, e.g., locked, can be searched for. When choosing criteria in the Advanced options of the toolbar search, choose the Marked criterion. If using a raw query string, the search prefix is `item:<specified state>` and it's negated form, `item!:<specified state>`. Here are the marking options available: Flag: The flag state of an item. Supports `flagged` or `unflagged`. Unread: The unread state of an item. Supports `read` or `unread`. Locking: The locking state of an item. Supports `locked` or `unlocked`. Dates: Dates are a very commonly used property in searches, for example, if you're looking for a document you created two days ago. Here are the date-based properties you can search for. See the Date Operators in the next section for the syntax you can use with these. added: The date the item was added to the database. (`added` or `additionDate`) Date Created: The date the item was created. (`created` or `creationDate`) modified: The date the item was last modified. (`modified` or `modificationDate`) opened: The date the item was last opened. (`opened` or `openingDate`) due: The due date set in a Reminder for an item. (`due` or `dueDate`) Miscellaneous Properties: There are also more esoteric attributes you can search for, like the number of attachments in emails, or the detected language of a document. Original Name: The original name of a renamed document, before it was renamed. (`md_originalname`) Attachments: The number of attachments in an email or the number of resources added to an RTFD file. (`md_attachments`) Annotations: The number of annotations set in a PDF file. (`md_annotationcount`) Encryption: The encrypted state of a PDF. This is a Boolean value denoted numerically, e.g., `md_encrypted==1` when a file is encrypted. (`md_encrypted`) Incoming Item Links: The number of item links to a document from other documents in DEVONthink. (`md_incomingItemLinkCount`) Outgoing Item Links: The number of item links to other documents present in a document. (`md_outgoingItemLinkCounts`) Language: An abbreviation of the detected language in the contents of a file. For a list of values, select a language in the criteria and note the abbreviation to use. (`md_language`) Country: An abbreviation of the country in the geolocation data for a file. For a list of values, select a country in the criteria and note the abbreviation to use. (`md_country`) Postal Code: The postal code detected in the geolocation data for a file. (`md_zipcode`) Administrative Area: The state, province, or region detected in the geolocation data for a file. (`md_area`) Locality: The city detected in the geolocation data for a file. (`md_locality`) PRO Custom Metadata: Any custom metadata attributes defined in the Data settings are also available as search prefixes. The search prefix you will type is a concatenated form of the attribute's name, prefixed with `md`. For example, an attribute of `Total Cost` would have a search prefix of `mdtotalcost`. There are also two special prefixes you can use: scope: This limits where you are searching. It supports `selection` (the current group or database), referring to a database by name (in quotes), and `inboxes`. If no scope is specified, the search applies to all open databases. When used, `scope:` should be the last parameter in the query. any: When used, this allows you to specify whether to return results matching any of the criteria. This can only be used when specifying more than one search prefix, e.g., tags and filename.
Example: `added>=2019-03-10 scope:selection` `tags:sync; methods scope:"Tech Stuff"` `any: name:test OR imprint {any: tags:blue; red}`
Sub-criteria searches: Yes, you may have noticed in the last example a tags search in curly braces. This creates sub-criteria for the search. This obviously extends the search options to allow creating even more complex forms. Prefix Operators Many times prefixes end with a colon, e.g., `tags:` but some use other forms, depending on the available options in the criterion. For example, words can "begin with" some characters, but a size is greater or less than a value. If you select a criterion you would see what options apply. Use the keys below to map the option to its operator. Matches, Is, Is Not: `:` is equal to the term matches. With strings-based queries, it allows for wildcards to be used. It is also used for state-based queries, like Kind. The negated form, `:!` is also supported. `==` is equal to the term is. This must be an exact match of the search term. These can be used in strings and number-based queries. The negated form, `!=` is also supported.
Example: Kind is Group → `kind:group` Item is indexed → `item:indexed` Item is not Replicated → `item:!replicated` Extension is XML Document → `extension==XML` Language is not English → `language!=en`
String Matching: These are operators that are used with string-based queries, like names or text content. These queries also support: `:<` is equal to begins with. `:>` is equal to ends with. `:~` is equal to contains. (The tilde is the second key down on the top left of an English keyboard.)
Example: Subject begins with party → `docSubject:<party` Locality ends with field → `md_locality:>field` Name contains tech → `name:~tech`
Number Matching: In addition to the `==` and `!=` operators, numbers can also use these operators: `<` is equal to is less than and `<=` is is less than or equal to. `>` is equal to is greater than and `>=` is is greater than or equal to.
Example: Word Count is less than 1000 → `wordcount<1000` Size is greater than 10MB → `size>10 MB` Hits is greater than or equal to 1 → `hits>=1`
Range Matches: For certain numerical attributes, you can use a range matching syntax, `attribute:lowerLimit-upperLimit`. For example, `wordcount:500-1000` matches files with between 500 and 1000 words. This is identical to the longer form syntax of `wordcount>=500 wordcount<=1000`. Range matches can be used with: width, height, duration, length, hits, wordcount, charactercount, and size prefixes. Date Operators: These are operators used with date-based queries, like the creation date of files. `<` is equal to before and `<=` is before or on. `>` is equal to later and `>=` is later or on. `:#` is equal to within last and `:!#` is not within last. These searches default to days, but you can also use weeks, months, or years, e.g., `modified:!#1weeks`. Note you always use the plural form of the time component. For dates-based queries, `:` is equal to is and `:!` equals is not. For greater compatibility, some other combinations of operators are allowed. `due:<=2020-01-03` is equivalent to `due<=2020-01-03`. Named Relative Dates: You can use these terms for relative dates: Today, Yesterday, This Week, Last Week, This Month, Last Month, This Quarter, Last Quarter, This Year, and Last Year. Use these with is, before (or on), and after (or on) operators.
Example: Date Created is after January 31, 2019 → `created:>=2019-01-31` Date opened is not within last 5 days → `openingDate:!#5days` Date Due is not Today → `due:!Today`
Date searching allows for some flexibility in formats. Time is not a required parameter, but can be specified. These searches are all equivalent:
Example: `added>10 march, 2019` `added>March 10, 19` `added>2019-03-10 08:30:00 -0500`