# 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](https://www.salesforce.com), [Google Ads](https://ads.google.com), [HubSpot](https://www.hubspot.com)—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:


```yaml
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:


```yaml
name: High-Value Recent Buyers
```

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


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

Human-readable explanation for your team.


```yaml
rule:
  type: And
  conditions:
```

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


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

First condition: `lifetime_value > 1000`.


```yaml
    - 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:


```mermaid
flowchart LR
    A[Describe] --> B[AI Generates]
    B --> C[Review]
    C --> D[Validate]
    D --> E[Push]
```

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:


```yaml
  - 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](/treasure-code/book/09-segment-rules) 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.*