Searching note data and metadata
The most powerful Cloud API functions are NoteStore.findNotes and NoteStore.findNotesMetadata, which allow you to search for notes within a user's account. You can search the full text of notes, or search by specific metdata such as notebook, note title, tag, date or location.
Why two search functions?
NoteStore.findNotes and NoteStore.findNotesMetadata allow you to perform the exact same searches. They differ in the control that they give you over the results that you get back. For efficiency, you should normally use findNotesMetadata to control the exact data model fields that your application needs. The examples on this page demonstrate the use of findNotesMetadata.
Let's start by finding the most recently modified notes in the user's account:
For efficiency, findNotes paginates the search results, retrieving a subset of the full result set with each call to findNotes. In this case, we're getting 10 notes at a time. The NoteList that we get back also tells us the total number of notes that matched the search.
To retrieve all of the notes that match the search, we'll have to make multiple calls to findNotes:
For efficiency, the Note and NoteMetadata objects returned by findNotes and findNotesMetada never include the note's content or resource data. Separate API calls must be made to fetch these values if they are needed:
It's easy to add criteria to a search. All of the search parameters are specified in the NoteFilter object. NoteFilter has specific fields that allow you restrict your search by notebook and by tags. You can also control whether the search includes notes that are in the trash (they're omitted by default). To restrict the search to those notes in a specific notebook, simply set the NoteFilter's notebookGuid field:
To search according to other criteria, use the the NoteFilter's words field. This field accepts the full Evernote search grammer, which lets you query almost any aspect of a note. Let's perform a full text search of notes containing the word "elephant":
The query above will match any note that contains the word elephant in the note title, the note content or one of the note's tags. It will also match notes that contain an image that contains the word "elephant". The image recognition chapter contains more information about searching within images.
The search grammar allows you to search according to multiple criteria. You can specific whether the search must match all of the criterial (AND) or any of the criteria (OR). It is not possible to nest ANDs and ORs in a single query. Here's a search for notes were created in the last day and have "elephant" in the title: