Title: Virtual Events
Locale: en
URL: https://sensorswave.com/en/docs/data-center/data-dictionary/virtual-events/
Description: Learn how to create and use virtual events to merge multiple tracked events into a unified analysis unit or split one event into multiple
Virtual events allow you to merge multiple tracked events using OR logic into a single logical event, which can be used as a unified metric in analysis. Virtual events do not generate new data storage — they are automatically expanded into a union of all constituent events at query time.

Virtual events have two typical use cases:

- **Merging multiple events**: Combine several similar tracked events into a single unified metric. For example, merge "WeChat Payment Success", "Alipay Payment Success", and "Bank Card Payment Success" into "Payment Success"
- **Splitting one event**: Create multiple virtual events from the same tracked event by applying different filter conditions. For example, split the "Page View" event by page URL into "Home Page View", "Product Page View", "Checkout Page View", etc.

## Core Concepts

### Constituent Events

A virtual event is composed of 1 to 25 tracked events, called "constituent events". At query time, the system expands the virtual event into OR conditions for all constituent events.

### Filter Conditions

Each constituent event can have independent filter conditions, supporting AND/OR logic combinations. For example, a "Page View" event can be filtered by the `page_url` property to include only specific pages. Filter conditions are key to implementing the "event splitting" use case.

### Property Union

The properties of a virtual event are the union of all constituent events' properties. If a constituent event does not have a certain property, its data will be shown as "Not Set" when grouped by that property.

## Creating a Virtual Event

1. Go to **Data Center** > **Data Dictionary**
2. Switch to the **Virtual Events** tab
3. Click **Create Virtual Event**
4. Fill in basic information:
   - **Event Name**: The unique identifier for the virtual event, cannot be modified after creation. The system automatically adds a `$Virtual/` prefix
   - **Display Name**: The name displayed in analysis interfaces
   - **Description**: Explains the purpose and meaning of the virtual event
5. Add constituent events:
   - Click **Add Event** and select from existing tracked events
   - To add filters, click **Add Filter Condition** next to the event and set property filter rules
   - Repeat the above steps to add all events to be merged
6. Click **Save**

### Example: Creating a "Payment Success" Virtual Event

**Scenario**: Your product has three payment methods, each corresponding to a separate tracked event. You want to analyze all payment behaviors as a whole.

**Configuration**:

| Field | Value |
|-------|-------|
| Event Name | PaymentSuccess |
| Display Name | Payment Success |
| Description | Merges all payment channel success events |

**Constituent Events**:

| Constituent Event | Filter Condition |
|-------------------|------------------|
| WeChat Payment Success | None |
| Alipay Payment Success | None |
| Bank Card Payment Success | None |

Once created, you can find the "Payment Success" event with a `[Virtual]` tag in the event selector of any analysis model.

### Example: Splitting "Page View" into Multiple Virtual Events

**Scenario**: Your product has a single generic "Page View" tracked event with a `page_url` property recording the page address. You want to directly select "Home Page View" or "Product Page View" in analysis, rather than manually adding filter conditions each time.

**Approach**: Create multiple virtual events from the same tracked event with different filter conditions.

**Virtual Event 1 — Home Page View**:

| Field | Value |
|-------|-------|
| Event Name | HomePageView |
| Display Name | Home Page View |

| Constituent Event | Filter Condition |
|-------------------|------------------|
| Page View | `page_url` equals `/home` |

**Virtual Event 2 — Product Page View**:

| Field | Value |
|-------|-------|
| Event Name | ProductPageView |
| Display Name | Product Page View |

| Constituent Event | Filter Condition |
|-------------------|------------------|
| Page View | `page_url` contains `/product/` |

This way, you can split a generic tracked event into more granular virtual events and directly use "Home Page View → Product Page View → Checkout Page View" to build a conversion funnel in Funnel Analysis.

## Editing a Virtual Event

1. Find the target event in the virtual events list
2. Click the event name to enter the detail page, or click **Edit** in the actions column
3. Modify the display name, description, or constituent event configuration
4. Click **Save**

> **Note**: The event name (unique identifier) cannot be modified after creation. To change the name, you need to delete and recreate the virtual event.

## Deleting a Virtual Event

1. Find the target event in the virtual events list
2. Click **Delete** in the actions column
3. The system checks whether the virtual event is referenced by charts, dashboards, or cohorts
   - If there are no references, confirm to delete
   - If references exist, all assets referencing the event will be listed. You can choose to:
     - **Cancel deletion** and first remove references to the virtual event from related assets
     - **Force delete** the virtual event directly. After force deletion, charts, dashboards, cohorts, and other assets referencing this event will become invalid and unable to display data

> **Note**: Force deletion is irreversible. Related assets will become invalid immediately. Please confirm the impact before proceeding.

## Using in Analysis Models

Virtual events can be used in all of the following analysis models, with the same operations as tracked events:

- **Event Analysis**: Select virtual events as analysis metrics, supporting all measure types (total count, user count, per-user count, etc.)
- **Funnel Analysis**: Use virtual events as steps in a funnel
- **Retention Analysis**: Use virtual events as initial or return events
- **User List**: Use virtual events as filter conditions
- **User Sequence**: View virtual events in behavior sequences
- **Cohorts**: Create cohorts based on virtual event triggers

### Notes on Property Grouping

When grouping analysis results by a certain property, if some constituent events do not have that property, their data will fall into the "Not Set" group.

For example, the virtual event "Payment Success" consists of "WeChat Payment Success" and "Alipay Payment Success". "WeChat Payment Success" has a `channel_name` property, but "Alipay Payment Success" does not. When grouping by `channel_name`, Alipay data will appear in the "Not Set" group.

## Limitations

| Limitation | Description |
|------------|-------------|
| Constituent event count | Maximum 25, minimum 1 |
| Nested virtual events | Not supported; constituent events can only be tracked events |
| Event name modification | Cannot be modified after creation |
| Custom SQL | Virtual events cannot be used directly in SQL queries |
| Event logic | Only OR merging is supported; AND, sequence, and NOT logic are not supported |

## Best Practices

### 1. Use Meaningful Names

Name virtual events to reflect business meaning, rather than listing constituent events. For example:

- Recommended: "Payment Success", "Content Interaction", "Registration Complete"
- Not recommended: "WeChat Payment + Alipay Payment + Bank Card Payment"

### 2. Control Constituent Event Count

Although up to 25 constituent events are supported, keep the number within a reasonable range. Too many constituent events increase complexity and may affect query performance.

### 3. Add Clear Descriptions

Include the business meaning and constituent events in the description to help team members understand and use the virtual event.

### 4. Regular Maintenance

When tracking changes occur (e.g., a new payment channel is added), promptly update the virtual event's constituent events to ensure analysis results remain complete.

## FAQ

### Do virtual events affect data storage?

No. Virtual events do not generate new data writes. They are only dynamically expanded into union conditions of constituent events at query time.

### Will historical data change after modifying a virtual event?

Yes. Since virtual events are computed at query time, after modifying constituent events, query results across all time ranges will be calculated using the new definition.

### What happens if a constituent tracked event is deleted?

The virtual event can still be viewed and edited, but queries will return an error indicating the virtual event is invalid. It is recommended to promptly update the virtual event definition and remove the deleted constituent event.

### Can virtual events be used in Custom SQL queries?

No. Virtual events rely on the query engine to automatically expand them at execution time. Custom SQL queries do not go through this expansion process. To achieve a similar effect in SQL, you can manually write OR conditions to combine multiple events.

---

**Last updated**: April 3, 2026