Customer Segmentation Table

customer_segmentation_table

The Customer Segmentation table lists which customers belong to each segment at any point in time. One row per customer per segment instance. Learn more about customer segmentation.

📋
Table Guide
What You Can Answer With This Table

Which customers are in a specific segment? — filter by segment_id

How has segment membership changed over time? — compare across instance_event_date values

What is the composition of a segment? — group by segment_by to see customer ID vs email-based membership

Before You Query

A segment is a group of customers matching defined rules. A segment instance is a snapshot of that segment at a point in time (generated daily or every other day).

To match results with the Customer Segments UI, filter for the most recent segment instance per segment. Without this, queries include all historical instances and totals will appear inflated.

The join key is customer_identity. Depending on segment_by, this contains either an email address or a customer ID. When joining to other tables, match against the corresponding field (e.g., customer_id on the Orders table, or email_address on the Customers table).

Key Relationships
Table Join Key What the Join Enables
Customers customer_identity to customer_id or email_address Profile data (name, email, address, consent, tags)
Orders customer_identity to customer_id or email_address Purchase behavior (order counts, revenue, new vs returning)
Pixel Orders customer_identity to customer_id or email_address Attribution and ad-driven activity at the order level
Customer Segmentation Analytics segment_id + instance_event_date Pre-aggregated metrics around a pinned_event_date

When to Use a Different Table

Need segment performance metrics (revenue, AOV, purchase frequency) → Customer Segmentation Analytics table. This table is the membership list; Analytics has the metrics.

Need customer profiles without segment context → Customers table.

View the full Triple Whale Data Ontology →

Table	Join Key	What the Join Enables
Customers	`customer_identity` to `customer_id` or `email_address`	Profile data (name, email, address, consent, tags)
Orders	`customer_identity` to `customer_id` or `email_address`	Purchase behavior (order counts, revenue, new vs returning)
Pixel Orders	`customer_identity` to `customer_id` or `email_address`	Attribution and ad-driven activity at the order level
Customer Segmentation Analytics	`segment_id` + `instance_event_date`	Pre-aggregated metrics around a `pinned_event_date`

Dimensions

Dimensions are immutable properties that can be used for grouping data.

Title	ID	Type	Description
Customer Identity	`customer_identity`	string	The identity of the customer in the segment. Can be either `email` or `customer_id` type. Example values: `[email protected]`, `5209503793328`
Instance Created Date	`instance_created_date`	date	The timestamp when the segment instance (run/snapshot) was generated. Example value: `2025-08-25 11:08:39`
Schedule	`schedule`	string	The recurring schedule for running the segment. Example values: `once_a_day`, `once_every_other_day`
Segment By	`segment_by`	string	The audience type used to group customers in the segment. Example value: `customer_id`, `email`
Segment Created Date	`segment_created_date`	date	The date when the segment was originally created. Example value: `2023-07-20 08:33:08`
Segment ID	`segment_id`	string	The unique identifier for a segment. Example value: `64b8f144256b30501b2ea1e0`
Segment Instance ID	`segment_instance_id`	string	The unique identifier for a specific segment instance (run/snapshot). Example value: `64b8f144256b30501b2ea1e0_2025_08_25`
Segment Name	`segment_name`	string	The human-readable name of the segment, Example values: `Fourth of July Sale`, `At least 3 orders`, `Jan Non Recent Active`
Shop ID	`shop_id`	string	The unique ID of the shop (often corresponds to the shop domain). Can be used to group or filter data by shop in multi-store reports. Example values: `example-US.myshopify.com`, `example-EU.myshopify.com`
Shop Name	`shop_name`	string	The name of the shop. Can be used to group or filter data by shop in multi-store reports. Example values: `example-US`, `example-EU`

Measures

Measures are numeric fields that can be aggregated and/or combined to calculate new metrics.

Title	ID	Type	Description
Number of Customers	`num_of_customers`	numeric	The total number of unique customers included in the segment instance.
Number of Orders	`num_of_orders`	numeric	The total number of orders placed by customers in the segment during the relevant time window.
Total Revenue	`total_revenue`	numeric	The total revenue generated by customers in the segment during the relevant time window.

Updated 2 days ago