Subjects¶
This guide explains the role of subjects in EventSourcingDB, how they are structured, and how to use them effectively. Subjects are more than just metadata – they are a core part of how events are organized, filtered, and retrieved.
You'll learn how subjects identify event streams, how to structure them meaningfully, and how to make the most of their hierarchical nature.
What Is a Subject?¶
Every event in EventSourcingDB belongs to exactly one event stream, and the stream is identified by its subject. The subject is a required field and must be provided in the event's subject property, as defined by the CloudEvents specification.
Unlike CloudEvents, where the subject is conceptually free-form, EventSourcingDB assigns it a specific semantic meaning: it acts as the unique identifier for an event stream. All events with the same subject belong to the same stream, and no stream can exist without one.
Path-Based Structure¶
Subjects in EventSourcingDB are treated as hierarchical paths. Each subject must start with a forward slash (/) and may contain additional segments, separated by slashes. For example:
This structure allows subjects to express nested relationships and enables powerful filtering and grouping. Subjects are case-sensitive and should be written in lowercase, with hyphens as separators if needed. This convention improves readability and ensures consistent behavior across tools and platforms.
Avoid camelCase, underscores, or dots within subjects. Use slashes for hierarchy and hyphens for clarity.
Semantic Use of Subjects¶
Subjects are intended to reflect a meaningful identifier – either from a domain perspective, a technical ID, or both. For example:
/books/42could refer to the stream of events for a specific book./users/17/orders/9001might represent the order history for a specific user's transaction./machines/a7d3/maintenancecould track maintenance events for a particular device.
You are free to choose the structure, but we recommend aligning it with your domain model to ensure clarity and long-term maintainability.
Filtering by Subject¶
When reading events or observing events, you can filter by subject. There are two filtering modes:
- Exact match: Returns only the events for the specified subject.
- Recursive match: Returns events for the subject and all sub-subjects.
This allows you to group related streams and retrieve their data collectively. For example, querying /books/42 recursively would also return events from /books/42/pages/1, /books/42/pages/2, and so on.
EventQL also supports filtering by subject, including both exact and pattern-based matching.
Reading All Events¶
By convention, all subjects in EventSourcingDB begin with a forward slash. The root subject / represents the top-level namespace in the hierarchy.
You can read or observe all events in the system by querying from / with recursion enabled. This can be useful for system-wide reporting, analytics, or catch-all subscriptions in downstream systems.
Designing Hierarchies with Care¶
The hierarchical subject structure enables a flexible way to model related data. You can isolate substreams while still making them accessible as part of a parent stream. However, this flexibility should be used thoughtfully.
Avoid overly deep or fragmented subject hierarchies that make streams hard to reason about. Only introduce sub-subjects when they meaningfully extend the parent and add structure without obscuring intent.
Subject Naming Guidelines¶
The subject field is the backbone of stream identity in EventSourcingDB. A well-designed subject structure improves readability, makes filtering more effective, and helps downstream consumers interpret event data in context.
Keep subjects consistent, meaningful, and aligned with your domain – and use the hierarchy to your advantage without overcomplicating it.