subject-too-deep

• Routes: write-events, read-events, observe-events, read-subjects, restore-backup, and import-events
• Description: subject is too deep: it may have at most 32 segments
• Details: value, the subject as the request, the backup, or the import gave it. When writing events, also event or precondition, the place of the event or the precondition in its list, counting from 0. When reading or observing events, also option, which is fromLatestEvent where the subject is the one of that option. When restoring a backup or importing events, also eventId, the ID of the event.

Why It Happens#

A subject may have at most 32 segments and at most 1,024 characters, see Limits. The database keeps a subject together with every subject above it, so the memory and the disk space that an event takes grow with the length and the depth of its subject at once, and the bounds keep that in proportion. A typical cause is a subject that mirrors a deep hierarchy segment by segment, such as the folders of a file system.

The bounds hold for every subject that a request hands in: the subject of an event, the subject to read, observe, or list, the subject of fromLatestEvent, and the subject of a precondition. They hold for the subject of every event of a backup or of an import as well. When restoring a backup, the restore fails at the event, and the database removes what it has restored so far, see When a Restore Fails. When importing events, the import fails at the event, and the database removes what it has imported so far, and keeps the schemas that were registered before it.

How to Fix It#

Flatten the subject: give it the segments that identify the element, such as /documents/42, and keep the rest of the hierarchy in the data of its events. Events that an earlier version stored with such a subject stay readable, through a subject above it, through /, or with EventQL, but a backup that holds one cannot be restored, and an export that holds one cannot be imported until its subject is changed.

Example#

To read the events of a subject of 33 segments, EventSourcingDB answers with this error, as a line of the stream, and then ends the stream with its end item:

{
  "type": "error",
  "data": {
    "code": "https://docs.eventsourcingdb.io/errors/subject-too-deep",
    "description": "subject is too deep: it may have at most 32 segments",
    "details": {
      "value": "/s1/s2/s3/s4/s5/s6/s7/s8/s9/s10/s11/s12/s13/s14/s15/s16/s17/s18/s19/s20/s21/s22/s23/s24/s25/s26/s27/s28/s29/s30/s31/s32/s33"
    }
  }
}