Chapter 8: Your First Segment

The Problem

You know what audience you want: high-value customers who purchased recently. You've explored the data. Now you need to create an actual segment that can be activated to marketing channels.

The Key Idea

Core concept

A segment is a saved audience definition. Tell AI who you want to reach, and AI creates a YAML file that defines the targeting rules.

Once created, this segment can be synced to Salesforce, Google Ads, HubSpot—anywhere you need to reach these customers.

Creating Your First Segment

Start with a clear description of who you want:

> "Create a segment for high-value customers who purchased in the last 30 days"

AI generates a YAML file:

name: High-Value Recent Buyers
description: Customers with lifetime value over $1000 who purchased in the last 30 days

rule:
  type: And
  conditions:
    - type: Value
      attribute: lifetime_value
      operator:
        type: Greater
        value: 1000
    - type: Value
      attribute: last_purchase_date
      operator:
        type: TimeWithinPast
        value: 30
        unit: day

AI also tells you:

Created segment file: segments/high-value-recent-buyers.yaml

This segment targets customers where:
- lifetime_value > $1000 AND
- last_purchase_date within 30 days

Estimated audience size: 3,247 customers

Understanding the YAML

Let's break down what AI created:

name: High-Value Recent Buyers

The segment's display name—what you'll see in reports and the UI.

description: Customers with lifetime value over $1000...

Human-readable explanation for your team.

rule:
  type: And
  conditions:

The targeting criteria. type: And means all conditions must match.

    - type: Value
      attribute: lifetime_value
      operator:
        type: Greater
        value: 1000

First condition: lifetime_value > 1000.

    - type: Value
      attribute: last_purchase_date
      operator:
        type: TimeWithinPast
        value: 30
        unit: day

Second condition: last_purchase_date within past 30 days.

With type: And, this segment includes customers who match both conditions.

The Workflow

Creating a segment follows this pattern:

1. Describe — Tell AI who you want to target
2. AI Generates — Segment YAML file created
3. Review — Check the rules make sense
4. Validate — tdx checks for errors
5. Push — Segment goes live

Let's complete steps 3-5.

Reviewing the Segment

Read through the YAML. Ask yourself:

• Does the name clearly describe the audience?
• Are the rules targeting who I actually want?
• Are the values correct ($1000? 30 days?)

If something's off:

> "Change the lifetime value threshold to $500"

AI updates the file:

  - attribute: lifetime_value
    operator: Greater
    value: 500  # Changed from 1000

Validating the Segment

Before pushing to production, validate:

> "Validate the segment"

AI runs tdx sg validate:

✓ Segment syntax is valid
✓ All attributes exist in parent segment
✓ All behaviors exist in parent segment
✓ Operators are valid for field types

Segment is ready to push.

If there are errors:

✗ Attribute 'ltv' not found
  Did you mean 'lifetime_value'?

AI helps you fix issues before they reach production.

Previewing the Audience

See who will be included:

> "Preview the segment"

Segment: High-Value Recent Buyers
Estimated size: 3,247 customers

Sample members:
- sarah@example.com (LTV: $2,450, last purchase: 3 days ago)
- mike@example.com (LTV: $1,890, last purchase: 12 days ago)
- lisa@example.com (LTV: $1,234, last purchase: 28 days ago)

This confirms the segment is targeting the right people.

Pushing to Production

When you're satisfied:

> "Push the segment"

AI runs tdx sg push:

Pushing segment: High-Value Recent Buyers

Changes:
  + New segment: High-Value Recent Buyers
  + 2 rules configured
  + No activations configured yet

Proceed? [y/N]

Confirm, and the segment is live in Treasure Data.

Mental Model: Saved Searches

Think of a segment as a saved search that runs continuously:

• Search criteria: lifetime_value > 1000 AND last_purchase_date within 30 days
• Results: automatically updated as customers qualify or disqualify
• Actions: can trigger activations to external systems

Unlike a static list, segments are dynamic. A customer who makes a purchase today will automatically enter the segment tomorrow.

Dry Run: See Before You Change

Not ready to commit? Use dry run:

> "Push the segment with dry run"

DRY RUN - No changes will be made

Would create segment: High-Value Recent Buyers
Would add 2 rules
Would affect approximately 3,247 customers

No changes were made. Remove --dry-run to apply.

This shows exactly what would happen without actually doing it.

Pitfalls

"The audience size is 0."

Your rules might be too restrictive. Try relaxing criteria:

> "What if we change to purchased in last 90 days instead?"

"The audience size is too large."

Add more rules to narrow down:

> "Add a rule: must have opened email in last 14 days"

"I'm not sure about the operator."

Ask AI to explain options:

> "What operators can I use for lifetime_value?"

What You've Learned

• Segments are saved audience definitions in YAML
• AI generates segments from plain English descriptions
• Rules define who's included (attributes and behaviors)
• Validate before pushing to catch errors
• Preview to verify the audience looks right
• Dry run shows changes without applying them

Next Step

You've built a segment with two rules. Chapter 9 explores more complex targeting—combining rules with AND/OR logic, excluding audiences, and referencing other segments.

---

You've built your first segment. Next, you'll learn to build complex ones.