# The description of Event and Stream definitions

`pg_eventstore` provides classes to prepare the events to be inserted into the eventstore. The most important are:

- `PgEventstore::Event` class which represents an event object
- `PgEventstore::Stream` class which represents a stream object

## Event object and its defaults

`PgEventstore::Event` has the following attributes:

- `id` - String(UUIDv4, optional, not `nil`). If no provided - the value will be autogenerated.
- `type` - String(optional, not `nil`). Default is an event's class name. Types which start from `$` indicate system events. It is not recommended to prefix your events types with `$` sign.
- `global_position` - Integer(optional, read only). Event's global position in the eventstore, aka the "all" stream position (inspired by the popular EventstoreDB). Manually assigning this attribute has no effect. It is internally set when reading events from the database.
- `stream` - PgEventstore::Stream(optional, read only). A Stream an event belongs to, see description below. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.
- `stream_revision` - Integer(optional, read only). A revision of an event inside its stream.
- `data` - Hash(optional). Event's payload data. For example, if you have a `DescriptionChanged` event class, then you may want to have a description value in the event payload data. Example: `DescriptionChanged.new(data: { 'description' => 'Description of something', 'post_id' => SecureRandom.uuid })`
- `metadata` - Hash(optional). Event metadata. Event meta information which is not part of an events data payload. Example: `{ published_by: publishing_user.id }`
- `link_id` - String(UUIDv4, optional, read only). If an event is a link event (link events are pointers to other events), this attribute contains the `id` of the original event. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.
- `created_at` - Time(optional, read only). Database's timestamp when an event was appended to a stream. You may want to put your own timestamp into a `metadata` attribute - it may be useful when migrating between different databases. Manually assigning this attribute has no effect. It is internally set when appending an event to the given stream or when reading events from the database.

Example:

```ruby
PgEventstore::Event.new(data: { 'foo' => 'bar' }, type: 'FooChanged')
```

## Stream object

To be able to manipulate a stream, you have to compute a stream's object first. It can be achieved by using the `PgEventstore::Stream` class. Here is a description of its attributes:

- `context` - String(required). A Bounded Context, read more [here](https://martinfowler.com/bliki/BoundedContext.html). Values which start from `$` sign are reserved by `pg_eventstore`. Such contexts can't be used to append events.
- `stream_name` - String(required). A stream name.
- `stream_id` - String(required). A stream id.

Example:

```ruby
PgEventstore::Stream.new(context: 'Sales', stream_name: 'Customer', stream_id: '1')
PgEventstore::Stream.new(context: 'Sales', stream_name: 'Customer', stream_id: 'f37b82f2-4152-424d-ab6b-0cc6f0a53aae')
```

There is a special stream, called the "all" stream. You can get this object by calling the`PgEventstore::Stream.all_stream` method. Read more about the "all" stream in the `Reading from the "all" stream` section of [Reading events](reading_events.md) chapter.

## Important note

Because the database is designed for Eventsourcing, some limitations should be met - a combination of `Event#type`, `Stream#context` and `Stream#stream_name` must have low cardinality(low unique values number). This means you should pre-defined values there. Otherwise it may lead to the performance degradation. See [How it works](how_it_works.md) chapter for the details.