# 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:

```
/books/42
```

EventSourcingDB **enforces this structure when writing events**: each segment may only contain **letters, digits, underscores, and hyphens** (`0-9`, `A-Za-z`, `_`, `-`). Subjects that contain spaces, dots, or other special characters are **rejected**. A trailing slash is allowed and is normalized away, so `/books/42/` and `/books/42` refer to the same subject.

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 and underscores** 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/42` could refer to the stream of events for a specific book.
- `/users/17/orders/9001` might represent the order history for a specific user's transaction.
- `/machines/a7d3/maintenance` could 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](/learn/tutorials/first-steps-with-eventsourcingdb/reading-events)** or **[observing events](/learn/tutorials/first-steps-with-eventsourcingdb/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.