Chronicle read models with empty child collections
During root initialization, Chronicle omits child collection fields rather than writing []. A previously populated collection can remain stored as [] after its last child is removed. When the .NET client reads a model with a missing field, a supported non-nullable collection becomes empty; a nullable collection preserves the distinction between missing (null) and stored empty ([]). Choose the declaration that matches what your application needs to know.
This applies to collections declared with [ChildrenFrom<T>] or a declarative .Children(...) projection. A newly created order, for example, can have no line items yet even though the order itself is ready to read.
Root initialization leaves child collections untouched
Section titled “Root initialization leaves child collections untouched”Chronicle never writes a children collection on behalf of the root event. A children path is owned exclusively by the child add and remove operations for the whole lifetime of the read model, and the root projection’s initial state is applied with every children path removed.
The root write must preserve children already stored, including during partition reprocessing. If a LineItemAdded has already added a child, allowing OrderPlaced to write Lines = [] would erase it. Projection replay and catch-up each use a single step that reads events in sequence order; only reactors and reducers run that work independently per partition.
Omitting the field lets the root write leave children untouched. This exclusion applies only to children collections; Chronicle applies the rest of the initial state as written.
What you read back
Section titled “What you read back”When the .NET client materializes a read model, it fills a missing collection property according to its declaration:
| Declared as | No value stored | A value stored |
|---|---|---|
IEnumerable<LineItem> Lines |
An empty collection | Exactly that value, including [] |
IEnumerable<LineItem>? Lines |
null |
Exactly that value, including [] |
With a supported non-nullable declaration, you can enumerate Lines without a null guard even before the first child arrives. A nullable declaration preserves the difference between an absent field and a stored empty list.
Strings and dictionaries are not normalized. Neither are collection types the reader cannot construct, such as an unsupported custom collection. Use a supported collection type when you rely on this behavior.
Say which answer you want
Section titled “Say which answer you want”Declare Lines as non-nullable if missing should mean empty, or nullable if absence matters to your application. No additional option or registration is needed:
using Cratis.Chronicle.Events;using Cratis.Chronicle.Keys;using Cratis.Chronicle.Projections.ModelBound;
[EventType]public record EmptyChildrenOrderPlaced(string Customer);
[EventType]public record EmptyChildrenLineItemAdded(Guid ItemId, string ProductName, int Quantity);
public record EmptyChildrenLineItem([Key] Guid Id, string ProductName, int Quantity);
// Non-nullable: an order with no line items reads back as an empty collection,// so enumerating Lines never needs a guard.[FromEvent<EmptyChildrenOrderPlaced>]public record EmptyChildrenOrder( [Key] Guid OrderId,
string Customer,
[ChildrenFrom<EmptyChildrenLineItemAdded>(key: nameof(EmptyChildrenLineItemAdded.ItemId))] IEnumerable<EmptyChildrenLineItem> Lines);
// Nullable: "no line items yet" stays distinguishable from "an empty list".[FromEvent<EmptyChildrenOrderPlaced>]public record EmptyChildrenDraftOrder( [Key] Guid DraftOrderId,
string Customer,
[ChildrenFrom<EmptyChildrenLineItemAdded>(key: nameof(EmptyChildrenLineItemAdded.ItemId))] IEnumerable<EmptyChildrenLineItem>? Lines);import io.cratis.chronicle.events.EventTypeimport io.cratis.chronicle.projections.ChildrenFromimport io.cratis.chronicle.projections.FromEventimport io.cratis.chronicle.readModels.ReadModel
@EventTypedata class EmptyChildrenOrderPlaced(val customer: String = "")
@EventTypedata class EmptyChildrenLineItemAdded(val itemId: String = "", val productName: String = "", val quantity: Int = 0)
data class EmptyChildrenLineItem(val id: String = "", val productName: String = "", val quantity: Int = 0)
// Non-nullable: an order with no line items reads back as an empty collection, so enumerating// lines never needs a guard.@ReadModel@FromEvent(EmptyChildrenOrderPlaced::class)data class EmptyChildrenOrder( val id: String = "", val customer: String = "", @ChildrenFrom(EmptyChildrenLineItemAdded::class, key = "itemId") val lines: List<EmptyChildrenLineItem> = emptyList())
// Nullable: "no line items yet" stays distinguishable from "an empty list".@ReadModel@FromEvent(EmptyChildrenOrderPlaced::class)data class EmptyChildrenDraftOrder( val id: String = "", val customer: String = "", @ChildrenFrom(EmptyChildrenLineItemAdded::class, key = "itemId") val lines: List<EmptyChildrenLineItem>? = null)import io.cratis.chronicle.events.EventType;import io.cratis.chronicle.projections.ChildrenFrom;import io.cratis.chronicle.projections.FromEvent;import io.cratis.chronicle.readModels.ReadModel;
import java.util.List;
@EventTyperecord EmptyChildrenOrderPlaced(String customer) {}
@EventTyperecord EmptyChildrenLineItemAdded(String itemId, String productName, int quantity) {}
record EmptyChildrenLineItem(String id, String productName, int quantity) {}
// Non-nullable: an order with no line items reads back as an empty collection, so enumerating// lines never needs a guard.@ReadModel@FromEvent(eventType = EmptyChildrenOrderPlaced.class)class EmptyChildrenOrder { private String id = ""; private String customer = ""; @ChildrenFrom(eventType = EmptyChildrenLineItemAdded.class, key = "itemId") private List<EmptyChildrenLineItem> lines = List.of();
public String getId() { return id; } public void setId(String id) { this.id = id; }
public String getCustomer() { return customer; } public void setCustomer(String customer) { this.customer = customer; }
public List<EmptyChildrenLineItem> getLines() { return lines; } public void setLines(List<EmptyChildrenLineItem> lines) { this.lines = lines; }}
// Nullable: "no line items yet" stays distinguishable from "an empty list".@ReadModel@FromEvent(eventType = EmptyChildrenOrderPlaced.class)class EmptyChildrenDraftOrder { private String id = ""; private String customer = ""; @ChildrenFrom(eventType = EmptyChildrenLineItemAdded.class, key = "itemId") private List<EmptyChildrenLineItem> lines;
public String getId() { return id; } public void setId(String id) { this.id = id; }
public String getCustomer() { return customer; } public void setCustomer(String customer) { this.customer = customer; }
public List<EmptyChildrenLineItem> getLines() { return lines; } public void setLines(List<EmptyChildrenLineItem> lines) { this.lines = lines; }}Elixir does not support this workflow yet.TypeScript does not support this workflow yet.The rule is applied when the instance is materialized, not when it is stored, so changing a declaration takes effect for instances that were written long before you changed it. Nothing needs replaying.
A record-body normalizer such as IEnumerable<LineItem> Lines { get; init; } = Lines ?? []; does not cover every read path. Direct MongoDB reads can bypass the constructor, as explained under Where these semantics apply below and in Designing read models.
Initial values do not reach a child collection
Section titled “Initial values do not reach a child collection”Setting Lines = [] through initial values does not change this storage behavior. Chronicle removes every children path before applying the root’s initial state, so that value never reaches the sink.
Use the declaration instead. Initial values remain the right tool for business defaults, sentinel values, and properties that are not children collections.
Where these semantics apply
Section titled “Where these semantics apply”These rules belong to Chronicle’s reader, not to the stored document. They apply wherever Chronicle materializes the read model for you — reading a single instance, reading a collection, materialized instances and paging, snapshots, watching a read model, and read model reactors — and to anything layered on those APIs. The read model testing scenarios materialize through the same code, so a spec and a running system answer this question identically.
A direct MongoDB query with IMongoCollection<T> uses the MongoDB driver’s deserializer instead of Chronicle’s reader. Get started uses this path for reporting and ad-hoc reads. Without a matching convention, a missing collection field can become null even when you declared it non-nullable.
Cratis Arc’s MongoDB convention pack fills a supported non-nullable collection on a [ReadModel] type with an empty collection for both an absent field and a stored null. Without Arc, configure equivalent driver behavior or read through Chronicle.
Related topics
Section titled “Related topics”- Children Collections - Declaring child collections on a read model
- Consistency Models - When a read model has to be correct
- Sinks - Where read model instances are stored