> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up realtime traits

> Realtime traits calculate values such as order counts, spend, and last viewed category from streaming events, and update as each event arrives. Use them in realtime audiences and journeys, or read them from your app.

## Before you begin

* A configured [Customer Studio schema](https://docs.hightouch.com/customer-studio/schema.md) with a parent model that has a primary key
* An event source sending events to Hightouch (Hightouch Events, Segment, RudderStack, or Snowplow)
* A [realtime event](https://docs.hightouch.com/real-time/setup.md#step-2-create-a-realtime-event) related to the parent model
* For traits that look back more than 24 hours, warehouse data that covers the same history: a precomputed column, or a warehouse event model related to the parent model

## Overview

[Traits](https://docs.hightouch.com/customer-studio/traits.md) calculate values that aren't already columns in your customer data. A realtime trait is a trait calculated from a [realtime event](https://docs.hightouch.com/real-time/setup.md#step-2-create-a-realtime-event) instead of a warehouse model. Hightouch updates the value as each event arrives, so the trait reflects what a customer did seconds ago.

For example, `Orders in the last 24 hours` counts `Order Completed` events as they stream in. A realtime audience can use it to stop showing a promotion right after a customer's second purchase.

Where a realtime trait gets its data depends on how far back it looks:

* **The last 24 hours or less** — Hightouch calculates the trait from the event stream alone.
* **More than 24 hours, or all time** — Hightouch combines history from your warehouse with the event stream. You choose the warehouse data when you create the trait.

This guide walks you through the five steps to create a realtime trait:

1. Choose a calculation method
2. Choose the realtime event
3. Set the time window
4. Back the trait with warehouse data, if the window is longer than 24 hours
5. Name and save the trait

## 1. Choose a calculation method

1. Go to **Customer Studio > [Traits](https://app.hightouch.com/traits?from=docs)**.

2. Select **Create > New trait**.

3. Select the parent model the trait belongs to.

4. Select a calculation method that works with realtime events:

| Method | Calculates | Example |
| - | - | - |
| **Count** | The number of matching events | Orders in the last 24 hours |
| **Aggregation** | The sum or average of a numeric event property | Spend in the last 30 days |
| **Occurrence** | The first or last value of an event property | Last viewed category |

5. Click **Continue**.

The other methods, such as **List** and **SQL Aggregation**, only work with warehouse models. To calculate a value from other realtime traits, see [Combine realtime traits with a formula](#combine-realtime-traits-with-a-formula).

## 2. Choose the realtime event

In **Related or event model**, select a realtime event. Realtime events have a lightning icon. A warehouse event model in the same list creates a standard trait, which updates when your warehouse data does.

![The Related or event model picker listing warehouse event models and realtime events](https://mintcdn.com/hightouch-3c037897/HhOvHUvBcZDm4Tt7/images/real-time/traits/rtt-realtime-event-model.png?fit=max\&auto=format\&n=HhOvHUvBcZDm4Tt7\&q=85\&s=80f8fc9f47f9047575fdb6dc4ea6adc8)

Then configure the calculation:

* **Add filter** — Count only the events that match conditions on event properties, such as `category` equals `shoes`.
* **Aggregation type** — For **Aggregation**, select **Sum** or **Average**, then select the numeric property to aggregate.
* **Occurrence type** — For **Occurrence**, select **First / Min** or **Last / Max**. Select the property to return in **Trait value** and the property that orders the events in **Order by**.

A realtime **Count** trait always counts events, so it has no **Count by** column.

> [!NOTE]
>
> **Preview results** isn't available for realtime traits.

## 3. Set the time window

**Time window** controls how far back events count toward the trait.

| Option | Use when | Example |
| - | - | - |
| **All time** | The trait covers a customer's full history | Lifetime spend |
| **Within the last…** | The trait covers a recent period, in minutes, hours, or days | Orders in the last 24 hours |

![Time window set to Within the last 24 hours on a Count trait](https://mintcdn.com/hightouch-3c037897/HhOvHUvBcZDm4Tt7/images/real-time/traits/rtt-time-window.png?fit=max\&auto=format\&n=HhOvHUvBcZDm4Tt7\&q=85\&s=4b71862f556c36dcfe809956130e57de)

A window of 24 hours or less needs no other setup, so you can skip to [step 5](#step-5-name-and-save-the-trait). If you select **All time** or a window longer than 24 hours, a **Backing model** field appears.

## 4. Back the trait with warehouse data

Hightouch calculates the last 24 hours of a realtime trait from the event stream. A trait that looks further back also needs history from your warehouse. The backing model is the warehouse data that holds that history.

Hightouch reads the warehouse value for each customer, then adds the events that arrive afterward. The trait stays current between warehouse updates without querying your warehouse for every event.

In **Backing model**, select where the history comes from:

| Backing model | What Hightouch does | Available for |
| - | - | - |
| The parent model, or a model merged into it | Copies a column you already maintain, such as `LIFETIME_SPEND` | **All time** traits, except **Average** |
| A warehouse event model related to the parent model | Calculates the value from the event rows | Every trait that needs a backing model |

![The Backing model picker with tabs for parent models and event models](https://mintcdn.com/hightouch-3c037897/HhOvHUvBcZDm4Tt7/images/real-time/traits/rtt-backing-model-picker.png?fit=max\&auto=format\&n=HhOvHUvBcZDm4Tt7\&q=85\&s=bdd9435ec52fa4366781c220f280dbfa)

### Use a precomputed column

Select the parent model, or a model merged into it, when your warehouse already holds the value. For example, your data team maintains a `LIFETIME_SPEND` column on the `Users` table.

* **Value column** — The column that holds the precomputed value.
* **Order-by column** — For **Occurrence** traits only. The column that holds the ordering value for the precomputed value, such as the timestamp stored next to a "most recent value" column. Hightouch compares it with incoming events to decide whether the warehouse value or a newer event wins.

  ![An All time Sum trait backed by the LIFETIME\_SPEND column on the Users parent model](https://mintcdn.com/hightouch-3c037897/HhOvHUvBcZDm4Tt7/images/real-time/traits/rtt-backing-column.png?fit=max\&auto=format\&n=HhOvHUvBcZDm4Tt7\&q=85\&s=8f4885212dd6cac6d67bc0349bc1f49f)

**Average** traits and **Within the last…** windows can't use a precomputed column. Hightouch can't combine a precomputed average with new events, and a precomputed column can't follow a moving time window. Select a warehouse event model instead.

> [!TIP]
>
> Keep the precomputed column up to date. Hightouch treats the column as
> complete at the time it reads it, and adds only the events that arrive after
> that.

### Use a warehouse event model

Select a warehouse event model when the history lives as event rows, such as a `Purchases` table. Hightouch calculates the trait from those rows over the trait's time window.

* **Value column** — For **Sum** and **Average**, the numeric column to aggregate. For **Occurrence**, the column whose value the trait returns. **Count** traits don't need one.
* **Order-by column** — For **Occurrence** traits only. The column that decides which row comes first or last, such as the event timestamp.
* **Filter events** — Optional conditions on the warehouse event model's columns.

  ![A Sum trait over the last 30 days backed by the Purchases event model, with a value column and optional event filters](https://mintcdn.com/hightouch-3c037897/HhOvHUvBcZDm4Tt7/images/real-time/traits/rtt-backing-events.png?fit=max\&auto=format\&n=HhOvHUvBcZDm4Tt7\&q=85\&s=90a6b7b68b6aa369a034431ce2c8288d)

> [!NOTE]
>
> Filters on the trait apply to the realtime event's properties. They don't run
> against the warehouse event model. If the trait has filters, add the same
> conditions in **Filter events** so the warehouse history counts the same
> events.

The backing event model must be a warehouse event model with a timestamp column, related to the parent model. If no model qualifies, the field shows **No backing models available**. Add the relationship in your [schema](https://docs.hightouch.com/customer-studio/schema.md), then return to the trait.

## 5. Name and save the trait

1. Click **Continue**.

2. Enter a **Name** and an optional **Description**. See [Name and describe the trait](https://docs.hightouch.com/customer-studio/traits.md#name-and-describe-the-trait) for naming guidance.

3. Click **Create trait**.

Realtime traits show a **Realtime** badge in the traits list.

![The traits list with a Realtime badge next to each realtime trait](https://mintcdn.com/hightouch-3c037897/HhOvHUvBcZDm4Tt7/images/real-time/traits/rtt-traits-list.png?fit=max\&auto=format\&n=HhOvHUvBcZDm4Tt7\&q=85\&s=6874931554408db4db2a8dcab874a55b)

## Combine realtime traits with a formula

Use the **Realtime formula** method to calculate a value from other realtime traits. For example, divide `Lifetime spend` by `Lifetime orders` to get `Average order value`.

**Realtime formula** appears in the method list after the parent model has at least one numeric realtime trait.

![The calculation method list with Realtime formula selected](https://mintcdn.com/hightouch-3c037897/HhOvHUvBcZDm4Tt7/images/real-time/traits/rtt-formula-method.png?fit=max\&auto=format\&n=HhOvHUvBcZDm4Tt7\&q=85\&s=aca3f97ac4b6e8ac2eaf57a50e863d14)

To create a formula trait:

1. Create the realtime traits the formula uses.
2. Select **Create > New trait**, select the parent model, and select **Realtime formula**.
3. In **Formula**, type a trait name and select it from the suggestions. Combine traits and numbers with `+`, `-`, `*`, `/`, and parentheses.
4. Optional: Expand **Advanced configuration** and set a **Default value**. Hightouch uses it when the formula has no result, for example when it divides by zero or one of its traits has no value yet.
5. Name and save the trait.

![A formula that divides the Lifetime spend trait by the Lifetime orders trait](https://mintcdn.com/hightouch-3c037897/HhOvHUvBcZDm4Tt7/images/real-time/traits/rtt-formula.png?fit=max\&auto=format\&n=HhOvHUvBcZDm4Tt7\&q=85\&s=bda167af0d71c8606d1ce9ae6e12a25f)

A formula can use count, sum, and average traits, and first or last traits that return a number. It can't use another formula.

## Use realtime traits

### Filter realtime audiences and journeys

Realtime traits appear with your other traits when you add a filter in a [realtime audience](https://docs.hightouch.com/real-time/setup.md) or a realtime journey. For example:

* An audience of customers where `Orders in the last 24 hours` is at least 2
* A journey **Segment** tile that routes customers where `30-day spend` is greater than 500
* A journey **Hold until** tile that releases a customer when `Lifetime orders` reaches 1

Hightouch re-evaluates the condition each time an event changes the trait's value.

Standard audiences and journeys run against your warehouse on a schedule, so realtime traits aren't available in them.

### Send trait values to destinations

Map realtime traits to destination fields in a [realtime sync](https://docs.hightouch.com/real-time/setup.md#option-1-realtime-syncs), or in a **Send to destination** tile in a realtime journey. Hightouch sends the value the trait has when the sync or tile sends.

### Read trait values from your app

Your app can request a customer's current realtime trait values over HTTP. The endpoint is on the [Personalization API](https://docs.hightouch.com/real-time/personalization-api.md#make-api-requests) host and takes a standard [Hightouch API key](https://docs.hightouch.com/developer-tools/api-guide.md#create-an-api-key).

| Verb | Path |
| - | - |
| GET | /v1/models/`:parent_model_id`/users/`:user_id`/traits |

A request looks like this:

```bash theme={null}
curl -X GET \
     -H "Authorization: Bearer <API_KEY>" \
     "https://personalization.us-west-2.hightouch.com/v1/models/1234567/users/123xyz/traits"
```

The response lists every realtime trait on the parent model, keyed by trait ID:

```json theme={null}
{
  "parent_model_id": "1234567",
  "user_id": "123xyz",
  "trait_values": {
    "9781679e-bc06-4d6a-804a-e98df59459b0": 520,
    "01d59bd0-9f41-4f78-bc42-5a357fcd3fae": 2
  }
}
```

The trait ID appears in the URL when you open a trait in **Customer Studio > Traits**. The API returns a `404` when Hightouch has no events or warehouse data for the user.

## Warehouse values refresh daily

When you save a trait with a backing model, Hightouch creates a sync for the parent model and runs it once a day. The sync reads each customer's warehouse value for every backed trait. Hightouch manages this sync, so you don't configure or schedule it.

Between runs, Hightouch adds each new event to the last warehouse value. For example, with `Lifetime spend` backed by a `LIFETIME_SPEND` column:

1. The daily sync reads `LIFETIME_SPEND = 480` for a customer.
2. The customer completes a \$40 order. The trait updates to `520` when the event arrives.
3. The next daily sync reads the new warehouse value. Hightouch adds only the events that arrive after that read.

If you change a backed trait's calculation, time window, or backing model, Hightouch recalculates its warehouse values on the next sync run.

## Constraints

Keep the following limitations in mind when designing realtime traits:

* **Occurrence** traits support **First / Min** and **Last / Max** only. **Most frequent** and **Least frequent** need a warehouse model.
* Without warehouse values, conditions on a trait with a backing model don't match.
* For **Occurrence** traits with a **Within the last…** window, **Order by** must be a number or a timestamp. By default, Hightouch skips events whose trait value is larger than 32 bytes, such as long URLs.
* [Trait value suggestions](https://docs.hightouch.com/customer-studio/traits.md#suggest-trait-values-in-the-audience-builder) aren't available for realtime traits.
* [SQL Formula](https://docs.hightouch.com/customer-studio/traits.md#sql-formula) traits can't reference realtime traits.

## Next steps

* [Set up realtime audiences](https://docs.hightouch.com/real-time/setup.md)
* [Personalization API](https://docs.hightouch.com/real-time/personalization-api.md)
* [Traits](https://docs.hightouch.com/customer-studio/traits.md)
