Relations & snapshots
Relation basics
A relation is a link between records in two entity tables. It lets you reuse information instead of typing the same customer or product details into every order. For example, each order can link to the customer who placed it, and each order item can link to the product being sold.
One or many records
Use a single relation when one record points to one related record, such as one order's customer. Use an array relation when one record needs a list, such as an order with many order items. These links can model common relationship patterns: one-to-many (one customer with many orders), many-to-one (many orders each point to one customer), one-to-one (each side points to one corresponding record), and many-to-many (use a linking entity, such as order items, to connect records from both sides).
| Prop | Type | Description |
|---|---|---|
| Array relation | A list of linked records | Use when one record contains multiple related records, such as the line items within an order. |
Live and snapshot relations
A live relation keeps a link to the other record and reads its latest values. If a supplier changes its phone number, a page showing a live supplier relation will show the updated number. A snapshot copies the related values into the record at the time it is saved. That copy stays as it was, even if the original record changes later.
| Prop | Type | Description |
|---|---|---|
| Live relation | Always up to date | Use for information that should reflect the latest version, such as a product's current category or a customer's current contact details. |
| Snapshot relation | Saved copy | Use for history that must not change later, such as the customer's name and address on an old invoice or the product name and price charged on an order. |
orders {
customer: customers // current customer details
customer_at_purchase: customers snapshot // saved copy
items: order_items[] // a list of order items
}Use live links for reusable information such as categories, current product details, and contact information that should stay current. Use snapshots for invoices, orders, and other records that must show what was true when the transaction happened. For a sale, snapshot the product name and price if later catalog edits must not change the old invoice.
Changing relation behavior clears that field's saved values