Data Model

Understanding how Evernote stores data

---

The following diagram shows the major data structures and key fields for the primary objects managed by the Evernote service for each user, and the basic relationships between those objects. These objects correspond to the items that a user sees in their account: notes, notebooks, tags, etc.

This page simply describes the objects themselves. To learn how to create and manipulate the objects from your application, see later chapters in this documentation.

The structures on the left side of the diagram (User, Accounting, UserAttributes) are accessed via the UserStore service, while the ones on the right are accessed via the NoteStore service.

Each of the core NoteStore objects is identified by a globally unique identifier (GUID) that is assigned by the service when the object is first created. This identifier does not change for the lifetime of the object and is used to refer to the object in later API calls.

Each of these objects also has an update sequence number (USN) that is changed whenever the object is modified on the service. Each updated object receives a new USN whenever a change is committed. The USN values are unique and monotonically increasing within an account, so that a client can inspect any two objects in order to determine which was more recently modified.

User

Every Evernote user is represented by one User object in the Evernote service.

Accounting

Each User has a set of associated Accounting information that allows clients to determine the level of service available for that user, such as the monthly "uploadLimit", which specifies the number of bytes of new content that the user can upload into their account each month.

Note

A Note represents a single unit of information within an Evernote account. A note is made up of a single body section (the content) and zero or more associated Resources (images, audio, PDF, etc.). The note's structure is similar to a MIME email message: the body is made up of hypertext, and the resources represent embedded "attachments" that the body can refer to.

Each note exists in only one Notebook at a time. It is not possible for a single note to exist in two different notebooks. If the note is copied, a new note is created. If the new note is edited, the original will not be changed.

A note's content is stored as a block of text in Evernote Markup Language (ENML) format. To learn about the details of this format, which is largely a subset of XHTML, see the chapter on ENML.

The note contains a block of ENML even when the note does not appear to contain hypertext. For example, a plaintext note is just a simple ENML document, and an image note is just a small ENML placeholder with a reference to an embedded binary resource containing the image bytes.

The placement of a resource (e.g. image or audio) within the hypertext is represented using an <en-media> tag. For example:

The hash attribute contains an MD5 checksum of the corresponding resource's bytes, which is used as an unambiguous identifier that points from the hypertext to one of the note's attached resources. This identifier is used instead of the resource's GUID so that the note and all its resources can be created and copied without needing to replace the identifier in the copied note.

Note that this HTML tag must be replaced with a display-specific alternative at some point before rendering the content. For example, when the <en-media> tag refers to an image, it is usually replaced with an <img> tag that refers to a locally downloaded copy of the corresponding image resource. This replacement can happen at rendering time or when the data is first loaded/modified by a client. The modified data is specific client and is not generated by or sent to the Evernote service.

Every note also has a set of NoteAttributes that carry additional information about the note such as creation time, size, origin, etc. These attributes are useful for searching and filtering of notes.

Notebook

Each user account contains at least one Notebook. Notebooks are used to organize collections of Notes. Each notebook has a name, which must be unique within the owner's account. Notebooks can be grouped into stacks, which contain one or more notebooks, but cannot directly contain notes. A given user's account may contain up to EDAM_USER_NOTEBOOKS_MAX notebooks.

Each account has a single notebook that is marked as the default notebook. This is the notebook that will receive any notes that are created without explicitly specifying a destination notebook. The default notebook can be changed by updating another notebook to set its default flag to true. When a new notebook is made the default, the Evernote service automatically sets the default flag to false on the previous default notebook. If the default notebook is ever deleted from the account, the Evernote service will update the oldest remaining notebook to be the default.

The Evernote service does not permit the last notebook to be deleted from a user's account, which guarantees that there is always a notebook that can be used to store new notes.

When a user marks a notebook as public, the Evernote service adds a Publishing structure that contains the information about accessing and displaying that notebook. This includes the unique URI that can be used (in conjunction with the username) to construct the full public notebook URL for use in web browsers.

Resource

A Resource is a binary data block that is associated with a single Note, similar to an attachment for an email message. Resources typically contain images, audio clips, PDFs, documents, etc.

Each resource may have a set of ResourceAttributes that describe its system-defined properties. For example, meta-data from images may be extracted from a JPEG EXIF block and stored as searchable attributes on the resource.

Unlike web pages, which refer to images and other attachments using URLs that may reference content on other servers, the full content of a resource is stored on the Evernote service along with the corresponding note. This permits full synchronization of a user's data across systems and ensures that a note will remain available even if the content from which it originated is lost or changed.

Any type of file can be attached to a Note as a Resource, regardless of whether a user has a Free or Premium account. When creating a Resource, a MIME type must be set to indicate the file’s content type. The following are some of the standard types that Evernote clients are able to display. Other Resource types may be shown as an attachment in an Evernote client and will need to be opened in an external viewer/editor. The default type "application/octet-stream" should be used if a more specific type is not known.

• image/gif
• image/jpeg
• image/png
• audio/wav
• audio/mpeg
• audio/amr
• application/vnd.evernote.ink
• application/pdf

A resource may also have a block of recognition data that can be used to find text within binary resources such as images. The recognition block for each resource is stored in the custom "recoData" XML format, which specifies the various recognized regions of text in an image along with the alternate words that may be found in that region. To learn more about this, see the chapter on image recognition.

Tag

Each user account contains a set of zero or more Tags, which are an organizational tool to help users find relevant notes. Tags are applied only to Notes; Notebooks, Resources and other objects cannot be tagged.

Tags are full objects in the Evernote data model. A note with the tag "food" does not store the string "food", but instead includes a reference to the tag object with the name "food". The tag's name is unique within the user's account. If a note has been assigned the tag "food", then this is the same tag as "food" on any other note in the account. Each tag can be assigned to any number of notes, and each note may have any number of tags.

While many users may be comfortable finding and using their tags from a flat, alphabetized list, advanced users may want organization in order to help find a particular tag. The data model includes a simple organization scheme where a tag can be moved to be a "child" of another tag within the tag list. The location of a tag underneath its "parent" does not imply any semantic relationship between these tags. This is intended as a simple layout option for the list of all tags. A tag with no assigned parent is considered to be a "top level" tag for purposes of display and navigation.

Each tag can only have one parent, so it cannot be moved under two different tags in the organizational scheme. The Evernote service will not permit the creation of a new "expenses" tag underneath the "business" tag if an "expenses" tag already exists in that account.

Tags are shared across notebooks. If notes in two different Notebooks have a tag named "cooking", then those notes have the same Tag.

Tags are only assigned to a note as part of an explicit user action. They are not automatically created based on note attributes, and they are not created as part of automated search filters. Searching based on note attributes (such as creation time and size) is supported, but this is independent from the "Tag" mechanism, which is reserved for user-assigned labels.

SavedSearch

Each account contains zero or more SavedSearches, which can be used to find a set of Notes meeting various criteria. These criteria can include a combination of keywords, tags and attributes. These criteria can be saved within the account for re-use at a later date, and each saved search has a unique name within that account for ease of identification.

A saved search includes a "query" string, which contains a search expression that is represented using the Evernote search grammar documented in the search grammar chapter. The saved search is just a stored query; it is not directly associated with any of the notes which would happen to match if this query were executed. This is different from a tag, which has an explicit relationship with its notes in the data model. A saved search can be thought of as a "smart tag" whose corresponding notes are only determined when the query is executed.

When the query is executed, Evernote will select all of the notes that meet the search's criteria, as if those criteria had been manually re-entered into an Evernote client's search GUI or sent to the findNotes function.