Event streams and event types

An event stream is the inbound side of Amperity’s real-time pipeline: a configured flow of customer events–website activity, loyalty actions, email or SMS engagement–that Amperity ingests and processes as each event arrives. An event type is the schema Amperity applies to the events on a stream. It names the fields an event carries, the data type of each field, and the expression that produces each field’s value.

Together, event streams and event types turn raw inbound events into typed, recognized records that update profile collections and, through them, the real-time segments and real-time journeys that act on customer behavior.

Event streams

An event stream defines how Amperity receives and interprets a flow of inbound events. Each stream is configured with:

  • A recognition method that resolves every inbound event to one of the event types defined for the stream. An event whose type cannot be resolved is left unrecognized rather than processed.

  • A routing expression, a timestamp expression, and an event-id expression. These extract, respectively, the value used to route the event, the time of the event itself, and a unique identifier for the event.

  • An Event stream mode–Process, Drop, or Reject–that determines what happens to the events sent to it. Process accepts each event and processes it, and the sender receives 202 Accepted. Drop accepts the event without processing it, and the sender receives 204 No Content. Reject refuses the event, and the sender receives 409 Conflict.

Events reach a stream through the Real-time API endpoint POST /prof/events/{stream-id}. The stream’s mode governs the response the sender receives. For the exact status codes and the request constraints, see How events are processed and the Real-time API reference.

A profile collection subscribes to one or more event streams; the events on a subscribed stream are what keep the collection’s profiles current. A single stream can feed more than one collection.

Event types

An event type is the schema Amperity applies to the events on a stream. An event type is a set of fields, and each field declares:

  • A name.

  • An expression that produces the field’s value from the inbound event, written in Amperity’s expression language.

  • A data type that the produced value is coerced to.

  • Whether a value is required. When a required field produces no value, the event is marked invalid.

A field can also be designated a linking key–an identifier, such as an email address, that Amperity uses to link the event to a customer. Recognizing which customer an event belongs to is a distinct step from recognizing the event’s type, and is covered separately in real-time identity recognition. A field can additionally carry a format that constrains how its value is interpreted.

Complex and nested field types

Event-type fields are not limited to scalar values. A field’s data type can be complex, and complex types can nest:

  • An array holds an ordered list of values of a single element type–for example, the line items in a cart.

  • A struct holds a fixed set of named sub-fields, each with its own data type, as a nested record within the event.

  • A map holds a set of key-value pairs with declared key and value types.

Because the element type of an array, the value type of a map, or a sub-field of a struct can itself be complex, event types can model deeply nested payloads: an array of structs, a struct that contains an array, and so on. A decimal field also has a scale, the number of digits after the decimal point, so that monetary and other fixed-point values keep an exact representation. In the event type editor, the precision is fixed at 38 digits and you set the scale.

How Amperity processes an inbound event

Amperity does two things with an event when it arrives on a stream: it recognizes the event’s type, and it coerces the event’s fields to their declared types.

Recognition applies the stream’s recognition method to resolve the event to one of the stream’s event types. Recognition either resolves the event to an event type name, or leaves it unrecognized when the recognition method does not resolve it. An event that resolves to a name with no event type configured on the stream is ignored: it is not processed.

Coercion then evaluates each field of an event whose type is configured. Amperity evaluates each field’s expression and converts the result to the field’s declared data type. Arrays and structs are converted element by element. Map and binary fields are passed through without conversion. The event is marked invalid when a required field produces no value, a field’s expression fails to evaluate, or the event’s timestamp expression produces no value or a value that is not a timestamp. Otherwise the event is valid, and it updates the profiles its linking keys resolve to.

Configure an event type from a sample

Amperity keeps a random sample of recent events for each stream and event type: up to five events per event type each hour, for 24 hours. When you define an event type’s fields, you can work from a recognized sample event instead of declaring every field by hand: selecting a property from the sample adds a field that reads that property. Because the sample reflects the events the stream has actually received, the fields you define match the shape of your real payloads.