Search Grammar

All things Evernote search

---

Evernote translates all note searching and filtering into a simple, text-based string representation. This internal search format is used for SavedSearch queries, and it may also be used directly by power users. This same search syntax is implemented on the Evernote service and all clients, which means that the same search should produce the same results on all systems.

Evernote's search grammar is a simple list of terms which are evaluated within a notebook (or "all notebooks") to find a match. By default, the search results are the intersection of the notes that match each individual search term. This behavior changes if the "any:" modifier is found in the search. In this case, the search is executed as a union of the matches of the individual terms, and notes will be returned that match any of the criteria terms. The results are obviously identical if there is only one search term.

String matches are case insensitive, and multiple spaces will compare as if they were a single space.

The search grammar includes a set of advanced search expressions in the form of "modifier:argument". A note will match this expression if the appropriate condition is met. The matching terms vary by the type of the modifier, so that a date may be compared differently than a string.

Any matching term may also be negated by adding a "-" character to the beginning. This means that the term will only match a note if the conditional is NOT true. Each term in the search may be one of the following:

Search Terms

This section documents the way that the search grammar will interpret search terms within the search expression.

Scope modifiers

notebook:[nb name] - will match notes in a notebook with the provided name. Name matching is case-insensitive. Since notebooks have exclusive relationships with notes, at most one notebook can be provided for the search. If no notebook is given, the search will go over all of the user's active notes. The notebook is not included in the "union" created by the "any:" operator. E.g.:

• notebook:"Bob's first notebook"
  • Matches all notes in this notebook
• notebook:"Hot Stuff" any: mexican italian
  • Matches all notes in the "Hot Stuff" notebook that have the word "mexican" or the word "italian" in them.

any: - If this expression is found at the beginning of the search (after the "notebook", if present), then the search will return a note that matches any of the other search terms. If this is not found, then the default behavior will be used: a note must match all of the search terms. This expression cannot be negated.

Matching literal terms

If no advanced search modifier is found in a search term, it will be matched against the note as a text content search. Words or quoted phrases must exactly match a word or phrase in the note contents, note title, tag name, or recognition index. Words in the content of the note are split by whitespace or punctuation. Words may end in a wildcard to match the start of a word. Searches are not case sensitive. (A wildcard is only permitted at the end of the term, not at the beginning or middle for scalability reasons on the service.) Multiple whitespace and/or punctuation characters in the quoted phrase or the note will be compared as if they were a single space. The backslash escape character ('\') may be used to escape a quotation mark within a quoted phrase. E.g.:

• potato
  • matches: "Sweet Potato Pie"
  • does not match: "Mash four potatoes together"
• Ever*
  • matches: "Evernote Corporation"
  • does not match: "forevernote"
• "San Francisco"
  • matches: "The hills of San Francisco"
  • does not match: "San Andreas fault near Francisco winery"
• -potato
  • matches: "Mash four potatoes together"
  • does not match: "Sweet Potato Pie"
• ham
  • matches: "green eggs&ham."
• "eggs ham"
  • matches: "green eggs&ham."

Punctuation is used to split the input query and document into words, but it is ignored for text matching. The behavior of a quoted search should behave as if the following operations were performed on both the search query and the target note:

1. All XML markup is removed from the document, leaving only the visible text as a string
2. The string is converted to a list of words which are separated by one or more whitespace and/or punctuation characters.
3. The case of each word in the list is normalized
4. The list of words in the query must match with the same sequence of words in the converted Note

For example, if a user searches for the phrase "Spatula! City! For Bargains..." against this ENML document:

The algorithm should convert the search phrase into a normalized list of words:

[ "spatula", "city", "for", "bargains" ]

And the document into:
[ "come", "down", "to", "spatula", "city", "for", "bargains", "on", "spatulas" ]

The search should match, since words from the target phrase are found in the list of words extracted from the document. (The same result could be implemented without literally converting each note into a list of words, but this gives the intended behavior that we see from major search engines like Google and MS.)

Matching Core Note Properties

tag:[tag name] - will match notes that have a tag with the literal name (word or quoted phrase). This requires an full case-insensitive match on the tag name. The tag name may end with a wildcard to match the beginning of a tag. The pattern will match from the beginning of the full tag name, and punctuation will be included. I.e. the tag and the search string are not tokenized by whitespace and/or punctuation. This can be used multiple times to specify all tags that must match the notes. E.g.:

• tag:cooking
  • Matches any note with the "cooking" tag
• tag:cook*
  • Matches any note with a tag that starts with "cook"
• -tag:cook*
  • Matches any note that does not have a tag that starts with "cook"
• tag:*
  • Matches any note that has at least one tag
• -tag:*
  • Matches any note that has no tags

intitle:[literal] - will match notes with a title that contains the literal word or quoted phrase. Can be used more than once. E.g.:

• intitle:chicken
• intitle:"tale of two"
• -intitle:beef
• Matches notes that do not have the word "beef" in their title.

created:[datetime] - will match any note that has a 'created' timestamp that is equal to, or more recent than, the provided datetime. (See Section C.2 for details on the legal format of the datetime argument.) E.g.:

• created:20070704
  • Matches notes that were created on or after July 4th, 2007, based on the client's timezone.
• created:20070704T090000
  • Matches notes that were created on or after 9:00am on July 4th, 2007, based on the client's timezone.
• created:20070704T150000Z
  • Matches notes that were created on or after 3:00pm GMT on July 4th, 2007.
• -created:20070704
  • Matches notes that were created before July 4th, 2007, based on the client's timezone.
• created:day-1
  • Matches notes that were created yesterday or today
• -created:day
  • Matches notes that were created before today
• created:day-1 -created:day
  • Matches notes that were created yesterday (only)
• created:day-30
  • Matches notes that were created within the last 30 days (or today)
• created:week
  • Matches notes that were created in this calendar week (Sunday-Saturday)
• -created:month
  • Matches notes that were created before this month
• created:year-1
  • Matches notes that were created last year or this year

updated:[datetime] - will match any note that has a 'updated' timestamp that is equal to, or more recent than, the provided datetime. (See Section C.2 for details on the legal format of the datetime argument.)

resource:[MIME type string] - will match notes that have a resource with a MIME type that matches the argument. E.g.:

• resource:image/gif
  • Matches notes with at least one image/gif resource
• resource:audio/*
  • Matches notes with at least one audio resource
• -resource:image/*
  • Matches notes with no images
• resource:application/vnd.evernote.ink
  • Matches notes with one or more ink resources

Attribute Matching

The search expression may also contain a matching term for any attribute that is defined in the data model. These are defined in the NoteAttributes and ResourceAttributes structures in Types.thrift. This will match against the Note attribute, if NoteAttributes contains an attribute with that name, or else it will try to match against the Resource attribute if if one exists with that name. The match is performed based on the type of the attribute.

String attributes will be compared using the standard string matching as above (case insensitive, normalized spacing, optional wildcard at the end of the argument).
Datetime attributes will be matched in the same manner as "created" and "updated", above.

Boolean attributes will be matched based on the argument of "true" or "false". A boolean attribute will match the wildcard ("*") argument if it has any value set for that attribute.

Double expressions will match notes where the attribute that is greater than or equal to the argument (see "latitude" for examples). Double comparisons are numeric, not lexical, so an argument of "99.9" is less than an argument of "100". A double attribute will match the wildcard ("*") argument if it has any value set for that attribute.

subjectDate:[datetime] - matches notes with a subjectDate attribute that is equal to or later than the argument datetime.

latitude:[double] - matches notes with a latitude that is greater than or equal to the argument. E.g.:

• latitude:37 -latitude:38
  • Matches notes with a latitude that is greater than or equal to 37, but do not have a latitude greater than or equal to 38. (I.e. 37 <= latitude < 38)

longitude:[double] - matches notes with a longitude that is greater than or equal to the argument.

altitude:[double] - matches notes with an altitude that is greater than or equal to the argument.

author:[string] - will match notes that have an "author" attribute set with a name that matches the argument string. E.g.:

• author:"robert parker"
• author:robert*
• -author:*
  • Matches notes that have no "author" attribute set

source:[string] - matches notes that came from an application or data source that matches the argument string. Not all notes will have a "source" attribute. Standard source attributes queries include:

• source:web.clip
  • Matches notes that were clipped from a web page using an Evernote Web Clipper
• source:mail.clip
  • Matches notes that were clipped from a local mail client
• source:mail.smtp
  • Matches notes that were delivered to the service via the email gateway.
• source:mobile.ios
  • Matches notes that were created on an iOS client of some form.
• source:mobile.android
  • Matches notes that were created on an Android client of some form.
• source:mobile.*
  • Matches notes that were created on a mobile client of some form.

sourceApplication:[string] - matches notes that have a source application string that matches the argument. This string is not guaranteed to be structured. Standard sourceApplication attribute queries include:

• sourceApplication:food.*
  • Matches notes that were created by Evernote Food
• sourceApplication:hello.*
  • Matches notes that were created by Evernote Hello
• sourceApplication:skitch.*
  • Matches notes that were created by Evernote Skitch

contentClass:[string] - matches notes that have a contentClass string that matches the argument. E.g.:

• contentClass:evernote.food.meal
  • Matches notes created using Evernote Food
• contentClass:evernote.hello.*
  • Matches notes created by Evernote Hello

placeName:[string] - matches notes that have a placeName string that matches the argument. E.g.:

• placeName:home
  • Matches notes with the placeName attribute set to “home”

applicationData:[string] - matches notes that have an entry in the applicationData map with a key that matches the argument. This can allow an application to find all of the notes that it has added application-specific metadata. E.g.:

• applicationData:myapp
  • Matches notes with a “myapp” entry in the applicationData map
• applicationData:*
  • Matches notes that have at least one entry in the applicationData map

reminderOrder:[integer] - matches notes that have been marked as a reminder. The actual integer attribute value is used to order reminders relative to one another and is generally not useful in search. E.g.:

• reminderOrder:*
  • Matches all notes that have been marked as a reminder

reminderTime:[datetime] - matches notes with a reminderTime attribute that is equal to or later than the argument datetime. reminderTime is the time at which the user has requested a reminder about the note. E.g.:

• reminderTime:day
  • Matches all notes with a reminder set for today or later
• reminderTime:day -reminderTime:day+7
  • Matches all notes with a reminder set for the next 7 days

reminderDoneTime:[datetime] - matches notes with a reminderDoneTime attribute that is equal to or later than the argument datetime. reminderDoneTime is the time at which the user dismissed the reminder. E.g.:

• reminderDoneTime:day
  • Matches all notes with a reminder done time of today
• reminderDoneTime:day-7
  • Matches all notes with a reminder done time in the past week

Advanced Content Matching

The following search terms are expressed as attributes, but these do not correspond to literal attributes in the NoteAttributes data model. Instead, these perform advanced matching against the content of the notes. These do not match standard words in the notes, but rather match special elements embedded within the ENML document.

todo:[true|false|*] - if the argument is "true", this will match notes that have ToDo checkboxes that are currently checked. If the argument is "false", this will match notes that have ToDo checkboxes that are not currently checked. If the argument is "*", this will match notes that have a ToDo checkbox of any type.

• -todo:false todo:true
  • Matches notes that have completed ToDo items, but no uncompleted items.

encryption: - matches notes that have an encrypted region within them.

Date/Time Arguments

Various expressions (such as "created:...") take an argument that is interpreted as a date or a date and time. This date is translated into a universal time value for comparison against the timestamps on the notes. The search grammar includes datetime expressions using either an absolute specification (including year, month, day...) or an expression that is relative to the current day/week/month/year. The former is required to support searches in a specific date range, but the latter is particularly useful for saved searches which may return notes that are (e.g.) no more than 7 days old.

Absolute Date/Time Arguments

Absolute datetimes are specified using a compact profile of ISO 8601 ( http://en.wikipedia.org/wiki/ISO_8601 ). An absolute datetime must fit one of the following three forms:
yyyyMMdd - Used to specify a date with no time component. Equivalent to "yyyyMMddT000000" for the same values. The date is converted to a universal time based on the client's desired timezone before comparing against the internal universal timestamps on the notes. E.g. "20071031" evaluates to 12:00am on 31 October 2007 in the client's timezone.
yyyyMMdd'T'HHmmss - Used to specify a date with a time component. The date and time are converted to a universal time based on the client's desired timezone before comparing against the universal timestamps on the notes. E.g. "20071031T093000" evaluates to 9:30am on 31 October 2007 in the client's timezone.
yyyyMMdd'T'HHmmss'Z' - Used to specify a date and time in absolute UTC (aka "GMT" or "Zulu") time. This time can be compared against notes as a universal time, which will produce the same results regardless of the client's current timezone preferences. E.g. "20071031T153000Z" evaluates 3:30pm UTC on 31 October 2007.

Relative Date Arguments

Relative date arguments are evaluated based on the client's notion of the beginning of the current "day", "week", "month", or "year". They may include an integer delta to indicate a previous day/week/month/year instead of the current one. If no delta is provided, the argument evaluates the the beginning of the current day/week/month/year. The following examples show how each expression would be evaluated by a client with a local date and time of: Wednesday, 31 October 2007, 13:30:56

• day - would evaluate to: Wednesday, 31 October 2007, 00:00:00
• day-1 - would evaluate to: Tuesday, 30 October 2007, 00:00:00
• day-14 - would evaluate to: Wednesday, 17 October 2007, 00:00:00
• week - would evaluate to: Sunday, 28 October 2007, 00:00:00
• week-2 - would evaluate to: Sunday, 14 October 2007, 00:00:00
• month - would evaluate to: Monday, 1 October 2007, 00:00:00
• month-1 - would evaluate to: Monday, 1 September 2007, 00:00:00
• year - would evaluate to: Monday, 1 January 2007, 00:00:00
• year-1 - would evaluate to: Sunday, 1 January 2006, 00:00:00

Examples

Find notes containing the word "chicken", tagged with "cooking", and created this year:

chicken tag:cooking created:year

Find notes tagged with "cooking" but not "mexican" that include the word "beef" but not the word "carrots"

tag:cooking -tag:mexican beef -carrots

Find notes in my "Travel" notebook with San Francisco in the title:

notebook:Travel intitle:"San Francisco"

Find notes that either include the text "San Francisco" or are tagged with the "SFO" tag:

any: "San Francisco" tag:SFO

Find image notes from the Sunnyvale region:

resource:image/* latitude:37 -latitude:38 longitude:-123 -longitude:-122

Find untagged audio notes that I edited in the last week or two:

-tag:* resource:audio/* updated:week-1

Formal Search Grammar

The following grammar is expressed using EBNF notation. This grammar assumes that recursive-descent parsing will be "greedy" to handle any ambiguity. The output of parsing this grammar is a set of terms and operators; separators are ignored. The parsing results of search expressions which do not match this grammar are undefined.