Relationships

An order should point to a customer that was actually generated. ref() selects retained data from another generator; previous() reads earlier data from the same instance.

The result

The order copies both customer fields from one earlier customer event:

{"customerId":"CUST-00","name":"Asha"}
{"orderId":"ORD-00","customerId":"CUST-00","customerName":"Asha"}

Link an order to a customer

defaults:
  seed: 42
generators:
  - name: customers
    config:
      maxEvents: 1
    value:
      customerId: =seq(format=CUST-%02d)
      name: Asha
  - name: orders
    config:
      maxEvents: 1
    vars:
      customer: =ref(customers)
    value:
      orderId: =seq(format=ORD-%02d)
      customerId: $customer.customerId
      customerName: $customer.name

ref(path)

Selects an event from another generator’s retained history. The target must be a literal generator path.

generators:
  - name: customers
    value:
      customerId: =uuid()
      name: =faker(person.fullName)

  - name: orders
    vars:
      customer: =ref(customers)
    value:
      orderId: =uuid()
      customerId: $customer.customerId
      customerName: $customer.name

{"customerId":"82be13c8-9c65-4a8b-8427-84e29a51658a","name":"Paul Considine"}
{"orderId":"7a1093b6-025d-45ec-b30d-6e629d581c68","customerId":"82be13c8-9c65-4a8b-8427-84e29a51658a","customerName":"Paul Considine"}

Use a whole-record ref when multiple fields must stay correlated. Two separate calls such as ref(customers.customerId) and ref(customers.name) may select different retained events.

A ref() creates an automatic dependency: Synthtraffic makes source history available before evaluating the dependent generator. A same-generator ref() is invalid; use previous() instead.

By default, Synthtraffic retains up to 100000 events for each required source generator. Reaching the configured history limit stops the run rather than silently discarding old source events.

Schedules are only needed for stronger ordering, such as completing all customers before any orders. See the Relationships lesson for the full scenario pattern.

previous(path)

Returns the previous generated value at a literal field path for the current instance.

value:
  priorStatus: =previous(status)

The first event of an instance has no prior event, so this call fails:

previous(status) has no prior event for instance default

Guard the first event with case so previous() runs only when a prior event exists. Only the selected branch is evaluated:

vars:
  updateNumber: =seq(start=1)
value:
  updateNumber: $updateNumber
  previousUpdate:
    =case:
      - if: =eq($updateNumber, 1)
        then: none
      - else: =previous(updateNumber)

Do not pass a missing previous value into a numeric function. See Logic for case rules.

Previous values are isolated by instance: two customer or sensor instances do not share each other’s earlier fields. The path is written as previous(status), not previous($status), because it names the earlier output field rather than reading the current scope.

Use Collections to select or omit fields from a whole-record ref.

Next: work with scenario time.