Evernote Core Workflow B: Search & Retrieval

Overview

Comprehensive search and retrieval workflow for Evernote, including search grammar, filters, pagination, related notes discovery, and result enrichment with notebook/tag names.

Prerequisites

• Completed evernote-install-auth setup
• Understanding of Evernote search grammar
• Valid access token configured

Instructions

Step 1: Search Service Foundation

Build a SearchService wrapping findNotesMetadata(). Use NoteFilter for query terms, sort order, and notebook scope. Use NotesMetadataResultSpec to control which metadata fields are returned (title, dates, tags, notebook GUID).

const filter = new Evernote.NoteStore.NoteFilter({
  words: 'tag:urgent notebook:"Work"',
  ascending: false,
  order: Evernote.Types.NoteSortOrder.UPDATED
});

const spec = new Evernote.NoteStore.NotesMetadataResultSpec({
  includeTitle: true, includeUpdated: true,
  includeTagGuids: true, includeNotebookGuid: true
});

const result = await noteStore.findNotesMetadata(filter, 0, 50, spec);

Step 2: Advanced Search Grammar Builder

Implement a fluent QueryBuilder class that chains operators: notebook("Work"), tag("urgent"), intitle("meeting"), createdAfter(date), hasUncompletedTodos(), hasAttachments(). Call .build() to produce the query string. Use any: prefix for OR logic.

const query = new QueryBuilder()
  .notebook('Work')
  .tag('urgent')
  .lastNDays(7)
  .hasUncompletedTodos()
  .build();
// Result: 'notebook:"Work" tag:"urgent" created:day-7 todo:false'

Step 3: Paginated Search Results

Use an async generator to iterate through large result sets page by page. Track offset and compare against totalNotes to determine when to stop. Default page size of 50-100 balances API calls versus response size.

Step 4: Related Notes Discovery

Call noteStore.findRelated() with a RelatedQuery (by note GUID or plain text) and RelatedResultSpec to discover related notes, notebooks, and tags.

Step 5: Search Result Enrichment

Cache notebook and tag lookups, then map GUIDs to human-readable names. Return enriched results with notebookName, tags[], created, and updated fields.

For the full SearchService, QueryBuilder, pagination, and enrichment implementations, see Implementation Guide.

Search Grammar Quick Reference

Operator	Example	Description
notebook:	notebook:"Work"	Restrict to notebook
tag:	tag:urgent	Has tag
-tag:	-tag:archived	Exclude tag
intitle:	intitle:meeting	Word in title
created:	created:day-7	Created within last 7 days
updated:	updated:week	Updated this week
todo:	todo:false	Has uncompleted todos
resource:	resource:image/*	Has attachment type
any:	any: term1 term2	Match ANY term (default is AND)

Output

• SearchService with text search, notebook search, and tag search
• Fluent QueryBuilder for composing search grammar queries
• Async generator for paginated results
• Related notes discovery via findRelated()
• Enriched results with notebook and tag names

Error Handling

Error	Cause	Solution
RATE_LIMIT_REACHED	Too many search calls	Add delay between paginated requests
BAD_DATA_FORMAT	Invalid search grammar syntax	Validate query with QueryBuilder
QUOTA_REACHED	Search quota exceeded	Reduce search frequency, cache results

Resources

• Search Grammar
• Search Overview
• Related Notes
• API Reference

Next Steps

For error handling patterns, see evernote-common-errors.

Examples

Find action items: Search for notes with uncompleted todos from the past week using QueryBuilder().thisWeek().hasUncompletedTodos().build(). Enrich results with notebook names.

Meeting search: Find all notes titled "meeting" in the "Work" notebook from the last 30 days, paginate through results, and export titles with tags.