In a data-access layer, what does it mean to flatten a multi-field value object into its owner's columns?

## One object, no table of its own A **flattened value** — also called a component or an inline value — is a class with several fields (`street`/`city`/`postcode`, `amount`/`currency`, `from`/`to`) that the mapping treats as part of the **owner's row**. Each field becomes a column on the owner's table. A customer with an address is still one row in one table; loading the customer loads the address with it. No join, no second entry in the identity map, no extra statement. This is the layer's answer to a mismatch. The domain wants a small type with behaviour and equality by content; the schema wants columns it can constrain and index. Flattening keeps both: the code sees one object, the database sees ordinary columns. ## What the value concedes Because it has no key, a flattened value gives up everything identity buys: - **Nothing can reference it.** A foreign key needs a target key, and the value has none; other rows point at the owner instead. - **It cannot be loaded, updated or deleted on its own.** Every write is an update of the owner's row, and “clearing” it means writing nulls into the owner's columns. - **It has no lifecycle of its own** — no separate insert, no cascade decision, no version column; the owner's version covers it. - **It cannot be shared.** Two owners holding the same instance in memory do not share storage: each writes its own columns, and one of them mutating the shared instance quietly changes what the other will write. Treating the type as immutable and assigning a replacement removes that whole class of bug. - **Its equality is by content**, which is what makes it a value at all: two addresses with identical fields are the same address. ## Where the column names come from The names come from the **mapping**, not from the class — the detail interviews probe. Since the type's own mapping supplies the defaults, two owners that flatten the same type generate the same column names. Harmless in two different tables; fatal in one table that holds both a billing and a shipping address. Layers solve this the same way generically: a per-use prefix, or explicit per-use overrides, so the same type lands as `bill_city` in one place and `ship_city` in the other. Nesting one flattened value inside another repeats the problem a level deeper. ## Flattened value, mapped row, or side table | Shape | Own key | Queryable alone | Written by | Fits | |---|---|---|---|---| | Flattened value | no | no | the owner's update | a small value read and written with its owner | | Mapped row of its own | yes | yes | its own statements | anything referenced, shared or counted independently | | Side table of plain values | no | only via the owner's key | often a wholesale rewrite | a set or list of scalars with no identity | The third row is the collection case: tags, phone numbers, scores — values with no identity — go in a side table holding the owner's key plus the value, plus an index column when order matters. Because those rows carry no key, many layers do not diff them; they delete the owner's rows and re-insert the current contents on any change. For five values that is invisible. For five thousand it is the write amplification behind a save that got mysteriously slow. ## The edges worth knowing - **All columns null.** If nothing was ever set, layers differ on whether you get a value whose fields are all null or a null reference for the whole value. A round trip that changes the shape of the answer is a genuine source of bugs, and worth pinning down deliberately rather than discovering. - **Nullability should move as a unit.** Declaring some sub-columns not-null and others nullable makes “half an address” representable, and then every reader must decide what half means. - **Constraints and indexes still work.** These are ordinary columns: a unique constraint across the pair, a check constraint, an index on one sub-column are all available. That is the practical advantage over collapsing the value into one opaque column, where the engine can no longer see the parts. - **Reporting sees the parts.** Anyone reading the table directly sees named columns and needs no knowledge of the application's types — again unlike an opaque encoding. - **Migration is the real cost.** Turning a flattened value into a table of its own later is a data migration plus a mapping change, not a mapping change alone. Flatten when you are reasonably confident the value will never need identity; promote it when it does.