Getting the entity

Every handler runs against one entity, the record moving through the flow. Most handlers inherit it from the event that triggered them and declare nothing. But the handler that receives a flow’s first event has no entity yet, so it must say where one comes from. Declare exactly one of the three modes. Declaring none, or declaring more than one, is a boot error: the package refuses to load, and swarm verify catches it before you deploy.

create_entity

Create (“mint”) a new entity at the flow’s initial state. Use it when the event starts a new item in this flow (a fresh ticket arriving):

ticket.created:
  create_entity: true
  advances_to: new

The new entity gets an auto-generated id, and the inbound event’s entity_id is ignored for state operations. Every declared field already has a value the moment the entity exists — its initial: value, or the type default — so a guard in the same handler can read any field immediately.

Cannot be combined with accumulate — an accumulator targets one entity, but create_entity mints a new one each time.
Can be combined with fan_out — one entity is created and every fanned-out event shares it.

select_entity

Attach to one existing entity, matched by a business key. The by map pairs entity fields with payload.* values from the triggering event:

fulfillment.completed:
  select_entity:
    by:
      order_id: payload.order_id     # find the order whose order_id matches
  advances_to: shipped

Exactly one entity must match. Zero matches, or more than one, both stop the handler with an error rather than letting it guess (that is what “fail closed” means throughout these docs). This is the mode you use when a result arrives from another flow and has to re-attach to the right entity; see Composing flows.

select_or_create_entity

Resolve one existing entity by the key, or mint a fresh one from that key if none matches. Use it when an event might be the first the flow has seen for a given key, or a follow-up:

order.event_received:
  select_or_create_entity:
    by:
      order_id: payload.order_id
  advances_to: active

On the create path the entity is minted at the initial stage; the key field is not written for you — write it in data_accumulation, as the accordion below shows.

Complete flows

Both examples below pass swarm verify.

create_entity then select_entity: an order through its lifecycle

The first event mints the order; every later event finds that same order by its business key. This is the most common shape: one handler creates, the rest select.

package.yaml

name: orders
version: 1.0.0
description: An order created on its first event, then advanced by later events.
platform_version: ">=0.7.0 <0.8.0"
flows: []

schema.yaml

stages:
  placed:
    initial: true
  shipped: {}
  delivered:
    terminal: true
pins:
  inputs:
    events: [order.placed, order.shipped, order.delivered]

entities.yaml

order:
  order_id: text
  customer: text

events.yaml

order.placed:
  swarm: { source: external }
  order_id: text
  customer: text
order.shipped:
  swarm: { source: external }
  order_id: text
order.delivered:
  swarm: { source: external }
  order_id: text

nodes.yaml

order-tracker:
  event_handlers:
    order.placed:                    # 1. first event: mint the order
      create_entity: true
      data_accumulation:
        writes: [order_id, customer]
        source_event: order.placed
    order.shipped:                   # 2. later events: find that order
      select_entity:
        by:
          order_id: payload.order_id
      advances_to: shipped
    order.delivered:                 # 3. and advance it
      select_entity:
        by:
          order_id: payload.order_id
      advances_to: delivered

What happens: order.placed runs create_entity, so it mints a fresh order at the placed state and records order_id and customer. When order.shipped arrives later, the handler has no entity of its own, so select_entity finds the existing order whose order_id matches the event’s payload.order_id, then advances it to shipped. order.delivered does the same and moves it to the terminal delivered state. The order_id field is what links every later event back to the order it created.

select_or_create_entity: a session that starts on its first event

Use select_or_create_entity when an event might be the first the flow has seen for a key, or a follow-up, and you do not want to handle the two cases separately.

package.yaml

name: sessions
version: 1.0.0
description: Count page views per session; the first view starts the session.
platform_version: ">=0.7.0 <0.8.0"
flows: []

schema.yaml

stages:
  active:
    initial: true
  ended:
    terminal: true
pins:
  inputs:
    events: [page.viewed, session.ended]

entities.yaml

session:
  session_id: text
  view_count:
    type: integer
    initial: 0

events.yaml

page.viewed:
  swarm: { source: external }
  session_id: text
session.ended:
  swarm: { source: external }
  session_id: text

nodes.yaml

session-tracker:
  event_handlers:
    page.viewed:                     # first view creates the session; the rest find it
      select_or_create_entity:
        by:
          session_id: payload.session_id
      data_accumulation:
        writes:
          - target_field: session_id
            expression: "payload.session_id"
          - target_field: view_count
            expression: "entity.view_count + 1"
    session.ended:
      select_entity:
        by:
          session_id: payload.session_id
      advances_to: ended

What happens: the very first page.viewed for a session_id finds no matching session, so select_or_create_entity mints one at active; every later view for that id finds the existing session. Either way the handler then writes session_id and increments view_count, so the count rises with each view. session.ended uses plain select_entity (the session must already exist by then) and moves it to ended. The computed write reads entity.view_count as it stood before this handler, which is why it increments cleanly across events.

Flows and entities

What an entity is, and how instances give each work item its own.

Getting started

Core concepts

Build a flow

Handlers

Patterns

Operating Swarm

create_entity

select_entity

select_or_create_entity

Complete flows

Flows and entities

​create_entity

​select_entity

​select_or_create_entity

​Complete flows

Flows and entities

create_entity

select_entity

select_or_create_entity

Complete flows