Schedules

A relationship only needs a source event to exist before it can be selected. Sometimes you need a stronger guarantee: finish every customer before starting any order. A schedule gives you that control.

Run one group after another

The first scenario should produce every customer before any order:

customers  CUST-00
customers  CUST-01
orders     ORD-00
orders     ORD-01

All customers before any orders

defaults:
  seed: 42

generators:
  - name: customers
    config:
      maxEvents: 2
    value:
      customerId: =seq(format=CUST-%02d)
      name: =faker(person.fullName)

  - name: orders
    config:
      maxEvents: 2
    vars:
      customer: =ref(customers)
    value:
      orderId: =seq(format=ORD-%02d)
      customerId: $customer.customerId
      customerName: $customer.name

schedule:
  stages:
    - run: [customers]
    - run: [orders]

Press Try it. The result follows the stage order above.

The new lines are under schedule.stages:

• Each run list names the generators in that stage.
• Stages run from top to bottom, so customers reaches its limit before orders starts.
• Put more than one name in run, such as [customers, products], when those generators may run together within one stage.
• Connections flush between stages. This lets a destination finish writing one group before the next group begins.

Every generator you want to run must appear in a stage.

Without the schedule, ref() would ensure that at least one customer exists before an order needs one, but the streams could then continue together. Use a schedule only when complete groups or batches must be ordered.

Repeat stages in batches

Add maxEvents to a stage to limit how many events each listed generator produces on one visit. Add cycle: true to return to the first stage until every generator reaches its own config.maxEvents.

The next scenario should produce two customers, two orders, then repeat:

customers  CUST-00, CUST-01
orders     ORD-00, ORD-01
customers  CUST-02, CUST-03
orders     ORD-02, ORD-03

Customer and order batches

generators:
  - name: customers
    config:
      maxEvents: 4
    value:
      customerId: =seq(format=CUST-%02d)

  - name: orders
    config:
      maxEvents: 4
    vars:
      customer: =ref(customers)
    value:
      orderId: =seq(format=ORD-%02d)
      customerId: $customer.customerId

schedule:
  cycle: true
  stages:
    - run: [customers]
      maxEvents: 2
    - run: [orders]
      maxEvents: 2

generators[].config.maxEvents remains the lifetime total. stages[].maxEvents is only the batch size for one visit to that stage.

With cycle: true, sequences, instances, and retained relationship history continue across visits. Use cycle: false when each return to the first stage should reset that run state while lifetime event counts continue. If you omit cycle, the stages run once.

defaults.maxDuration can stop a cycling schedule before its event limits. schedule.loop is not a valid setting.

Run this file

Save the first example as scheduled-orders.yaml.

sample prints a short preview to your terminal. It does not wait for real-time pacing, and it never opens Kafka, PostgreSQL, or other destinations.

synthtraffic sample scheduled-orders.yaml --events 4 --seed 42

docker run --rm \
  --env-file ./license.env \
  --volume "${PWD}/scheduled-orders.yaml:/work/scheduled-orders.yaml:ro" \
  synthtraffic/synthtraffic:latest \
  sample /work/scheduled-orders.yaml --events 4 --seed 42

Next: give events stable identities with instances.