SynthEvents: A Year of Events in One Download
Most introductions to Event Sourcing start with a handful of events written by hand – on this blog, a book that is acquired, borrowed, and returned. That is how you learn what an event looks like. It is not how you learn what an event store feels like once a year has gone by, with hundreds of streams woven into each other and stories in them that nobody wrote down on purpose.
Getting such a year usually means running a system for one, or writing a simulation of your own. SynthEvents, our free service for synthetic events, hands it to you in a single download: a library, a list of to-dos, and a pottery studio, each simulated over the year 2025, as plain CloudEvents or as a backup that you restore into EventSourcingDB as it is. In this post, we look at what a year shows that a handful cannot, how such a year comes about, why it is the same for everyone, and how it gets into your database with three commands.
What a Handful of Events Can't Show#
A handful of events written by hand is the right tool for one job: learning the shape of an event. You see a type, a subject, and some data, and you see how a few of them add up to the state of a book. Our own tutorial starts like that, and so do many posts on this blog. Nothing about that is wrong, and nothing in this post replaces it.
What a handful cannot show is what happens over time. In a real library, a copy is lent out and comes back three weeks later, with hundreds of other loans in between. A late fee turns up only once somebody has kept a book too long, and in the pottery studio, a refund turns up only once somebody has canceled a booking. The interesting parts of a history are the ones that need time to happen. A handful written by hand can name them, but it never lets them happen.
The same goes for questions. How many loans run late? How many courses fill up? Which errands get postponed again and again? You cannot ask these questions of three events, and you cannot try out a projection, a query, or a dashboard that is meant to answer them.
The relational world solved this decades ago with shared example databases such as Northwind, Sakila, and AdventureWorks. When we wrote about what the community needs in April, we put it bluntly: "There's no equivalent of Northwind for Event Sourcing." Three domains are not a canon yet, but they are a start, and anyone can use them.
Three Domains, a Year Each#
SynthEvents offers three domains, each in a scenario called everyday, which sets the make-up of a run: who takes part, how often they act, and the policy they meet, such as the loan period, the late fee, and the time zone the rules reckon days in. All three cover the year 2025:
- A library, from the copies it starts with to a year of loans. Readers borrow, renew, and return copies, sometimes late, and pay their fees, while a librarian adds new copies and withdraws old ones.
- To-dos of people who start using the list one after the other, note down their errands, and work through them. They put some off, adjust others, mark what is urgent, and throw a few away.
- A pottery studio, called
coursesin the names of its files and event types. Customers reserve seats, book, pay, and now and then cancel, while the studio plans its courses weeks ahead, sees most of them fill up, and calls off those that too few people book.
Every domain comes in three sizes, with about 500, about 5,000, and about 20,000 events, which you download from SynthEvents' product page. The sizes differ in how many people take part, not in how long: each covers the whole year. Every event is a CloudEvent with a type such as io.synthevents.library.book-borrowed, and its IDs and times are written the way EventSourcingDB writes its own, with IDs that count from zero and times to the nanosecond. Shortened to its type, subject, time, and data, a loan from the small data set of the library looks like this:
{
"type": "io.synthevents.library.book-borrowed",
"subject": "/books/6fdeca74-aa2f-4fd0-ad0f-1f62f2c99b32",
"time": "2025-01-06T15:06:08.55670659Z",
"data": {
"borrowedAt": "2025-01-06T15:06:08.556Z",
"borrowedBy": "/readers/eb6b7f2c-1e87-4c66-bd86-0a0bfd1b57d1",
"borrowedUntil": "2025-01-27"
}
}
The subject is the copy that was lent: every copy has a subject of its own below /books/. Next to the time of the event, the data carries the time of the loan itself, as a library would record it. The reader has no name, only a path with a UUID, and the books are made up, down to their authors. There is no personal data in any data set, because there is no real library behind it, no real user of a to-do list, and no real studio.
Behavior From Rules, Not a Random Sample#
SynthEvents does not make up events one by one. It simulates everyone in a domain: the readers and the librarian, the users of the to-do list, the customers and the studio itself. Each of them follows a story on a simulated clock. They wait, do something, learn whether it worked, and decide what to do next.
Whatever somebody does is a command, and the rules of the domain decide whether it is accepted and which events it results in. The scenario and chance decide who comes when and what they try; the rules decide what follows from it.
A command that the rules refuse leaves no event, but it still steers what happens next. A reader who finds every copy of a book lent out tries again on a later visit. A customer who finds a course full tries the next one. That is why the events of a data set always follow the rules of their domain, and why conflicts arise the way they do in a real system: from people acting on what they believe, which is not always what is true.
There is a limit to this, and it matters. The figures of the scenarios are set by hand and coarsely, so that the data is plausible: how often readers come, how far ahead customers book, how many errands get postponed. For the to-dos and the courses, we looked at real to-dos and at the bookings of a real studio to get the shape right, but none of their figures made it into a data set. A data set is not a measurement of any real library or studio, and it tells you nothing about them. If you need synthetic data that matches the statistics of your own system, for example to train a model, that is a different job, and one we described in Training AI Without the Data You Don't Have.
The Same Data for Everyone#
Every data set follows from its request, seed included, and the version of SynthEvents. Everyone in a simulation, the studio included, draws their own random numbers, derived from the seed, and nothing depends on the wall clock. The ready-made data sets use the seed standard, so they are the same for everyone, byte for byte, as long as SynthEvents keeps its version. A newer version may change them, so if you depend on exactly these events, keep the file.
A data set also says how it was made. The source of every event names SynthEvents, its version, and every parameter it was generated with except the format – the domain, the scenario, the range, the number of events, and the seed. So even after a restore, any event carries the recipe of its data set.
Data that is the same for everyone changes what a workshop feels like. Picture twenty people in a room, each with a database of their own. If they had to make that year themselves, even with one script that writes the same events into every database, no two databases would agree on when anything happened, since the server stamps every event with the moment it arrives. A restore keeps the times of the file. With a ready-made data set, everyone looks at the same year, down to the same event with the same ID and the same time, such as the same reader who paid a late fee twice. A discussion can start from a fact, not from comparing notes.
Sometimes the ready-made data sets do not fit, though. A workshop might need a longer period than a year, a talk a smaller data set, or a team a domain that looks like its own business rather than like a library. If you need one of these, ask us for a tailor-made data set: with a seed of your own, you generate it once and hand out the file, so everyone in your workshop gets the same one, and its source says how to generate it again. For another range or size, we send you a token for the API of SynthEvents and the command that generates the data set. If you need a domain of your own, we build it for you as a service.
From Download to Database#
Getting a year into EventSourcingDB takes three commands. First, download a data set, here the pottery studio with about 5,000 events, as a backup for EventSourcingDB:
curl \
-o courses.ndjson \
https://www.eventfoundation.io/products/synthevents/data-sets/courses-everyday-medium.eventsourcingdb.ndjson
The data sets come as backups in the format of EventSourcingDB 1.3, so you need version 1.3 or later; if you pulled the image before 1.3 came out, run docker pull thenativeweb/eventsourcingdb first. Then start EventSourcingDB with Docker, with a temporary data directory, so that the database is empty on every start:
docker run -it -p 3000:3000 \
thenativeweb/eventsourcingdb run \
--api-token=secret \
--data-directory-temporary \
--http-enabled \
--https-enabled=false
Finally, in a second terminal, restore the data set:
curl \
-X POST \
-H "authorization: Bearer secret" \
-H "content-type: application/x-ndjson" \
--data-binary "@courses.ndjson" \
http://localhost:3000/api/v2/management/restore-backup
EventSourcingDB answers with a stream that ends with an end item once the data set is restored. A restore needs an empty database, which the temporary data directory provides. The data set brings the schemas of all event types of its domain along, so from now on, EventSourcingDB checks every event you write of one of these types against its schema. And every data set stays within the 25,000 events that an evaluation license allows, so it restores into the instance above, which runs on that license, since EventSourcingDB uses it when it has none of its own.
Now the database holds a year of a studio, and you can ask it questions. This EventQL query counts the canceled bookings by their reason:
FROM e IN events
WHERE e.type == "io.synthevents.courses.booking-canceled"
GROUP BY e.data.reason
PROJECT INTO { reason: UNIQUE(e.data.reason), count: COUNT() }
Send it with QUERY, the HTTP method that the v2 API uses for reads:
curl \
-X QUERY \
-H "authorization: Bearer secret" \
-H "content-type: application/json" \
-d '{
"query": "FROM e IN events WHERE e.type == \"io.synthevents.courses.booking-canceled\" GROUP BY e.data.reason PROJECT INTO { reason: UNIQUE(e.data.reason), count: COUNT() }"
}' \
http://localhost:3000/api/v2/data/run-eventql-query
{"type":"row","data":{"value":[{"count":93,"reason":"requested"}]}}
{"type":"row","data":{"value":[{"count":39,"reason":"course-canceled"}]}}
{"type":"row","data":{"value":[{"count":13,"reason":"unpaid"}]}}
{"type":"end","data":{}}
Three reasons, three stories: customers who changed their minds, courses the studio called off, and bookings that were never paid. None of them was written by hand, and all of them follow from what the customers and the studio do, within the rules of the domain. If you work with a tool other than EventSourcingDB, download the same data set as plain CloudEvents from the product page instead, and read it line by line.
The restore kept the IDs, times, and hashes of the events as the file has them. In Not an Event Yet, we argued that only the server can set these fields, because an event whose ID, time, and hash you chose yourself proves nothing about when the store learned of it, in what order, or whether it has changed since. In that post's words, "testimony you write yourself is worth what it cost you." In the restored part of your database, these fields are set by SynthEvents, not testified by your database. The restore checks the hashes, so it refuses a file with an event changed on the way – unless whoever changed it computed the chain anew, which anyone can, since the hash needs no key.
For a studio that never existed, there is nothing to testify about: what matters is that every database holds the same events, and keeping their IDs, times, and hashes is what makes them the same. Every event you write afterwards, the server stamps as usual.
A Year Instead of a Handful#
The three events of a library still do what they always did: they teach you what an event is. What they never could is show you what a store becomes once events pile up over months, with loans that run late, courses that do not fill, and errands that keep getting postponed. That is also why the last step of our tutorial fills the database with a year of the library from SynthEvents. The same years of all three domains are one download away, and each is the same year for everyone who downloads it.
If you would like to try it, the SynthEvents quickstart walks through these steps with the library, starts EventSourcingDB with its management UI so that you can browse the year, and shows how to generate a data set of your own once you have a token. The data is yours under CC0 1.0: use it, change it, and pass it on, without asking.
