RudderStack Docs – Var Groups (Features)

Archive: Entity Var

Mon, 01 Jan 0001 00:00:00 +0000

An entity_var adds a calculated (aggregated) column to the entity var tables and downstream feature views. It calculates a single value for each member of the entity (for example, each user).

entity_vars can be features for a feature view or an input to another entity_var.

- entity_var:
 name: entity_var_name
 select: SQL statement
 default_value: value
 from: inputs/table
 where: condition
 window:
 order_by:
 - orderby_column
 description: Days when the user visited the website along with the number of pages visited per date stamp.

Field	Description
`name`	Name of the `entity_var`.
`select`	SQL state, equivalent to `SELECT` statement.
`from`	Path of the input table, equivalent to `FROM` statement.
`merge`	SQL expression defining how to combine previous feature values with new calculations for incremental features. Use `{{rowset.feature_name}}` to reference the previous value from the checkpoint.
`merge_where`	Optional SQL condition that filters which rows participate in the merge operation. Use `{{rowset.column}}` for previous values from the checkpoint and `{{this.column}}` for new values.
`default_value`	Default value for `null` values.
`where`	Filtering condition, equivalent to `WHERE` statement.
`window`	Adds `order_by` key for window functions. Rows are automatically partitioned by `rudder_id`.
`description`	Description of the `entity_var`.

Example

# Basic entity
- entity_var:
 name: first_order_date
 select: min(order_date)
 from: inputs/orders
 description: First order date

# Entity that is not a feature
- entity_var:
 name: last_order_date
 select: max(order_date)
 from: inputs/orders
 is_feature: false

# Using an entity_var as an input
- entity_var:
 name: days_since_last_order
 select: "date_diff({{ end_time_sql }}, date({{user.last_order_date}}), day)"
 description: Days since user last completed an order

# Using a window function
- entity_var:
 name: campaign_source_first_touch
 select: first_value(context_campaign_source)
 from: inputs/rsIdentifies
 where: context_campaign_source is not null and context_campaign_source != ''
 window:
 order_by:
 - timestamp

# Entity var referencing an input var
- input_var:
 name: last_order
 select: last_value(order)
 from: inputs/rsTracks
 window:
 partition_by:
 - user_id
 order_by:
 - timestamp
- entity_var:
 name: is_last_order
 select: boolor_agg({{rsTracks.Var("last_order")}})
 from: inputs/rsTracks

# Incremental entity var with merge clause
- entity_var:
 name: total_purchases
 select: SUM({{orders.value}})
 merge: SUM({{rowset.total_purchases}})
 from: inputs/orders
 description: Total purchase value

Control update frequency

Entity vars inherit their update frequency from the parent var_group. To control how often a feature is computed, set time_grain on the var_group:

var_groups:
 - name: weekly_features
 entity_key: user
 time_grain: week  # Features in this group update weekly
 vars:
 - entity_var:
 name: favorite_category
 select: mode(category)
 from: inputs/orders

This is useful for:

Reducing compute costs: Features that don’t need real-time updates (like monthly aggregates) can be computed less frequently.
Organizing features by freshness: Group real-time signals separately from slow-changing attributes.

See Timegrains for available options and detailed configuration.

Incremental features

You can make entity_vars incremental by adding a merge: clause. Incremental features update existing feature values with newly arrived data instead of recalculating from the entire historical dataset, significantly improving performance for large datasets.

For detailed information about incremental features, see the following guides:

Guide	Description
Incremental Features Overview	Overview of incremental features in Profiles
Make Features Incremental	Step-by-step guide to convert features to incremental
Simple Aggregations	Direct aggregations with merge clauses (SUM, MIN, MAX, COUNT)
Compound Aggregations	Complex aggregations (AVG, MIN_BY/MAX_BY, arrays, Booleans)

Avoid `CURRENT_TIMESTAMP()` and `CURRENT_DATE` in entity vars

Do not use warehouse date/time functions like CURRENT_TIMESTAMP(), CURRENT_DATE, GETDATE(), NOW(), or SYSDATE() in entity var select or where clauses.

These functions return the wall-clock time at query execution, which makes results non-deterministic across re-runs and rebase_incremental operations. Use end_time_sql instead.

[v0.25+] end_time_sql is the recommended way to reference the run’s logical end time, replacing other variations like end_time.Format(...). It is a built-in macro automatically available in every Profiles project. It produces a warehouse-specific formatted timestamp of the current run’s logical end time. No macros.yaml definition needed — just use {{ end_time_sql }} directly in entity var where and select clauses:

In where clauses:

- entity_var:
 name: active_days_in_past_7_days
 select: count(distinct active_day)
 from: models/active_days
 where: active_day >= DATEADD(day, -7, {{ end_time_sql }})

In select clauses:

- entity_var:
 name: days_since_last_order
 select: "DATEDIFF(day, MAX({{orders.order_date}}), {{ end_time_sql }})"
 from: inputs/orders

You can define custom time-formatting macros in macros.yaml that build on end_time_sql. Pass this as an input so the macro can access the material’s temporal context via mat.WhtCtx.TimeInfo.EndTime.

Example: Define a macro that truncates the context end time to the nearest hour:
# In macros.yaml
macros:
 - name: round_ctx_to_hour
 inputs:
 - mat
 value: "{% if !(mat.WhtCtx|isnil) %}DATE_TRUNC('hour', {{ warehouse.Timestamp(mat.WhtCtx.TimeInfo.EndTime) }}){% else %}NULL{% endif %}"
Then call it with this in an entity var:
- entity_var:
 name: events_in_current_hour
 select: count(*)
 from: inputs/events
 where: DATE_TRUNC('hour', {{events.timestamp}}) = {{ round_ctx_to_hour(this) }}

Archive: Input Var

Mon, 01 Jan 0001 00:00:00 +0000

An input_var adds a calculated column to an input table. It calculates a single value per row of the input table which can be used as an input for entity_vars.

Performance consideration: Input vars scan all input data on every run, which can be expensive for large datasets.

Consider using the following approaches for better performance:

entity_var with Incremental Features for aggregations like SUM, COUNT, MIN, MAX

Incremental SQL Models for complex transformations

Use input_var only when you need row-level calculations on the input table before entity-level aggregation (for example, window functions like ROW_NUMBER() or LAG()).

- input_var:
 name: input_var_name
 select: SQL statement
 from: inputs/table
 window:
 partition_by:
 - partition_column
 description: description

Field	Description
`name`	Name of the `input_var`.
`select`	SQL state, equivalent to `SELECT` statement.
`from`	Path of the input table, equivalent to `FROM` statement.
`where`	Filtering condition, equivalent to `WHERE` statement.
`window`	Adds `partition_by` and/or `order_by` keys for window functions
`description`	Description of the `input_var`.

Example

- input_var:
 name: page_count
 description: Adds column to a SQL model to get a page count per date.
 select: count(distinct url)
 from: models/pages_orderby_table
 window:
 partition_by:
 - profile_id
 - date

Migrate input vars to incremental alternatives

Input vars scan all input data on every run and block incremental processing for any entity var that depends on them. When migrating a project to incremental mode, you must convert or replace every input var.

Decision tree

For each input var, follow this decision tree to choose the best replacement:

Input Var
+-- Uses LAST_VALUE / FIRST_VALUE window function?
| +-- Yes: Convert to entity_var using MAX_BY / MIN_BY
|
+-- Uses a simple aggregation with partition_by?
| +-- Yes: Convert to entity_var with merge clause
|
+-- Requires complex multi-step logic?
 +-- Yes: Create an incremental SQL model and
 reference it from entity vars

Option 1: Convert to entity var (most common)

You can replace window functions like LAST_VALUE and FIRST_VALUE with MAX_BY and MIN_BY:

# Before (input var with LAST_VALUE)
- input_var:
 name: last_known_city
 select: last_value(city)
 from: inputs/events
 window:
 partition_by:
 - user_id
 order_by:
 - timestamp
 where: city IS NOT NULL

# After (entity var with MAX_BY + ordering helper)
- entity_var:
 name: last_known_city
 select: MAX_BY({{events.city}}, {{events.timestamp}})
 merge: MAX_BY({{rowset.last_known_city}}, {{rowset.last_known_city_by_param}})
 from: inputs/events
 where: {{events.city}} IS NOT NULL

- entity_var:
 name: last_known_city_by_param
 select: MAX({{events.timestamp}})
 merge: MAX({{rowset.last_known_city_by_param}})
 from: inputs/events
 where: {{events.city}} IS NOT NULL
 is_feature: false

For detailed patterns, see the following sections:

Option 2: Create an incremental SQL model

When the input var logic is too complex for an entity var (multi-step transformations, complex joins, or logic that truly requires row-level windowing), create an Incremental SQL Model that handles the computation incrementally, then reference it from entity vars.

Archive: Window Functions

Mon, 01 Jan 0001 00:00:00 +0000

Window functions are SQL functions that you can use with input_vars and entity_vars.

SQL window functions perform calculations across rows related to the current row, enabling complex analytics like rankings, running totals, and running averages.

window:
 order_by:
 - order_column (desc)
 frame_clause: ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
 partition_by:
 - partition_column

Field	Description
`order_by`	Column to order rows by, for example, add `desc` for descending order.
`frame_clause`	Specify the set of rows (or window) the calculation is applied to, see the specific warehouse documentation for more details.
`partition_by`	Column to partition the rows by. Applies only to `input_vars`.

Window function references

Example

# Order by
- entity_var:
 name: order_number
 select: rank() # DO NOT specify frame clause when a ranking window function is used
 window:
 order_by:
 - order_date

# Partition by and Input var
- input_var:
 name: session_start_time
 from: models/rsTracksUnionPages
 select: min(timestamp)
 window:
 partition_by:
 - context_session_id
 - rudder_id
 description: Describes the start time of session of a specific context_id

# Using frame clause

- entity_var:
 name: first_num_b_order_num_b
 select: first_value(tbl_c.num_b) # Specify frame clause as aggregate window function is used
 from: inputs/tbl_c
 default_value: -1
 where: tbl_c.num_b >= 10
 window:
 order_by:
 - tbl_c.num_b desc
 frame_clause: ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING

RudderStack Docs – Var Groups (Features)

Archive: Entity Var

Example

Control update frequency

Incremental features

Avoid CURRENT_TIMESTAMP() and CURRENT_DATE in entity vars

Archive: Input Var

Example

Migrate input vars to incremental alternatives

Decision tree

Option 1: Convert to entity var (most common)

Option 2: Create an incremental SQL model

Archive: Window Functions

Window function references

Example

Avoid `CURRENT_TIMESTAMP()` and `CURRENT_DATE` in entity vars