# Segment Commands

Manage CDP segments for audiences and activations.

Alias
`tdx sg` is an alias for `tdx segment`

## Commands

### Navigation & Discovery

| Command | Description |
|  --- | --- |
| [`use`](#use) | Set parent segment context |
| [`list`](#list) | List folders and segments |
| [`view`](#view) | Show segment details |
| [`desc`](#desc) | Show segment schema (column types) |
| [`show`](#show) | Execute segment SQL and show results |
| [`sql`](#sql) | Get SQL query for segment |
| [`fields`](#fields) | List available fields for segmentation |


### YAML Sync

| Command | Description |
|  --- | --- |
| [`pull`](#pull) | Pull child segments to YAML files |
| [`push`](#push) | Push YAML files to TD as child segments |
| [`validate`](#validate) | Validate segment and journey YAML files locally |


## Typical Usage


```bash
# 0. List available parent segments
tdx ps list

# 1. Pull all child segments from a parent to YAML files
#    (this also sets parent_segment context)
tdx sg pull "My Audience"
# Creates: segments/my-audience/

# 2. Edit YAML files locally (add/modify segments and activations)
# Edit segments/my-audience/high-value-customers.yml with your text editor

# 3. Push changes back to TD (syncs segments and activations)
tdx sg push

# 4. Review segments in TD (context already set by pull)
tdx sg list -r
```

The pull/push workflow enables version control and code review for segment definitions:


```bash
# Work from any subdirectory - push finds tdx.json automatically
cd segments/my-audience/marketing
# Edit newsletter-subs.yml
tdx sg push                # Push all changes from root
```

## How It Works

**Child segments** define filtered audiences within a parent segment. They use rules (conditions) to filter customers from the parent segment's enriched data. Each child segment can have one or more **activations** that export the filtered audience to external systems.

The `tdx sg` commands help you manage child segments as local YAML files. You can `pull` existing segments from Treasure Data, edit them locally, and `push` changes back. The YAML files include both segment rules and activation configurations.


```mermaid
flowchart TB
    subgraph LOCAL["Local"]
        YAML["segments/<parent>/*.yml"]
        CLI["tdx sg desc/show/sql"]
    end

    subgraph TD["Treasure Data"]
        API["CDP API"]
        subgraph PS["Parent Segment"]
            PARENT[("Enriched<br/>Customer Data")]
        end
        CHILD["Child Segments"]
        ACT["Activations"]
        EXT["External Systems<br/>(S3, Salesforce, etc.)"]
    end

    YAML <-->|"pull / push"| API
    CLI -.->|"query"| CHILD
    API --> CHILD
    PARENT -->|"filtered by rules"| CHILD
    CHILD -->|"activations"| ACT
    ACT -->|"export"| EXT
```

### Folder Structure

Pull creates individual YAML files for each segment, organized by folder:


```
segments/
└── my-audience/                    # Normalized from "My Audience"
    ├── tdx.json                    # { "parent_segment": "My Audience" }
    ├── active-users.yml            # Root-level segment
    ├── high-value-customers.yml    # Another root-level segment
    ├── marketing/
    │   ├── email-subscribers.yml   # Segment in Marketing folder
    │   └── newsletter-subs.yml     # Another segment in folder
    └── sales/
        ├── enterprise-leads.yml    # Segment in Sales folder
        └── q1/
            └── q1-targets.yml      # Segment in Sales/Q1 folder
```

Each segment file includes its activations (syndications), enabling file-based management of your CDP configuration.

## Context-Based Workflow

Child segment commands require a parent segment context. Set it using one of these methods:


```bash
# Option 1: Use the segment use command
tdx sg use "My Audience"

# Option 2: Pull sets context automatically
tdx sg pull "My Audience"

# Now run segment commands without specifying parent
tdx sg list                    # List folders and segments in "My Audience"
tdx sg view "Premium Users"    # View child segment details
tdx sg desc "Premium Users"    # Show segment schema
```

Names are case-sensitive. Pattern matching (`*`, `?`) is supported for filtering.

## Commands

### use

Set or show the parent segment context for subsequent commands.


```bash
tdx sg use [name]
```


```bash
# Set parent segment context
tdx sg use "My Audience"

# Show current context (no argument)
tdx sg use
```

### list

List folders and segments within the current parent segment context.


```bash
tdx sg list [folder] [options]
```

| Option | Description |
|  --- | --- |
| `-r, --recursive` | List recursively (tree view) |
| `--max-depth <n>` | Maximum recursion depth (default: 10) |
| `-w, --web` | Show web console URLs for segments |



```bash
# First, set parent segment context
tdx use parent_segment "My Audience"

# List folders and segments in context
tdx sg list

# List contents of a specific folder
tdx sg list "Marketing"

# Filter by pattern (glob)
tdx sg list "*Premium*"

# List recursively (tree view)
tdx sg list -r

# Show web console URLs for each segment
tdx sg list -w
```

JSON Output
When using `--json` or `--jsonl` output, URLs are always included in the response.

Listing Parent Segments
Use `tdx ps list` to list available parent segments.

### view

Show details of a folder or child segment within the current context.


```bash
tdx sg view [name] [options]
```

| Option | Description |
|  --- | --- |
| `-w, --web` | Open segment in web browser |



```bash
# Show folder details
tdx sg view "Marketing"

# Show child segment details (includes web console URL)
tdx sg view "Premium Users"

# Open segment in web browser
tdx sg view "Premium Users" -w

# JSON output
tdx sg view "Premium Users" --json
```

Web Console URL
The output always includes a `url` field with a link to the segment in the Treasure Data web console.

### desc

Show schema (column names and types) for a child segment.


```bash
tdx sg desc [name]
```


```bash
# Show schema for child segment
tdx sg desc "Premium Users"

# JSON output
tdx sg desc "Premium Users" --json
```

### show

Execute segment SQL query and show results.


```bash
tdx sg show [name]
```


```bash
# Execute segment SQL query and show results
tdx sg show "Premium Users"

# With output format
tdx sg show "Premium Users" --json
```

### sql

Get SQL query for a child segment.


```bash
tdx sg sql [name]
```


```bash
# Get SQL query for segment
tdx sg sql "Premium Users"

# JSON output
tdx sg sql "Premium Users" --json
```

### fields

List available fields for segmentation in the current parent segment context.


```bash
tdx sg fields
```


```bash
# List available fields (uses parent_segment context)
tdx sg fields

# JSON output
tdx sg fields --json
```

### pull

Pull all child segments from a parent segment to individual YAML files. This also sets the `parent_segment` context for subsequent commands.


```bash
tdx sg pull [parent_name]
```

The `parent_name` argument is optional if you have set a parent segment context with `tdx sg use`.

| Option | Description |
|  --- | --- |
| `-y, --yes` | Skip confirmation prompt |
| `--dry-run` | Preview changes without writing files |



```bash
# Pull all segments from parent (sets context)
tdx sg pull "My Audience"

# Preview changes without writing files
tdx sg pull "My Audience" --dry-run

# Skip confirmation prompt
tdx sg pull "My Audience" -y

# With context set (tdx sg use "My Audience")
tdx sg pull
```

**Output includes:**

- Number of segments and activations found
- New, changed, and unchanged files
- Diff preview for changed files


### push

Push individual segment YAML files to Treasure Data. Uses `parent_segment` context or detects parent from `tdx.json` in the segments directory.


```bash
tdx sg push [directory]
```

| Option | Description |
|  --- | --- |
| `-y, --yes` | Skip confirmation prompt |
| `--dry-run` | Preview changes without applying |
| `--delete` | Delete segments not in local YAML files |



```bash
# Push all segments (uses context or tdx.json)
tdx sg push

# Push from specific directory
tdx sg push segments/my-audience

# Preview changes without applying
tdx sg push --dry-run

# Skip confirmation prompt
tdx sg push -y
```

**Features:**

- Automatically creates missing TD folders
- Shows diff before applying changes (segments and activations)
- Shows segments/activations that will be deleted (exist on server but not in YAML)
- Syncs activations by name (create/update/delete)
- Creates new segments or updates existing ones based on segment name
- Asks for confirmation before applying changes


### validate

Validate segment and journey YAML files locally without pushing to Treasure Data. This is useful to catch syntax errors, missing references, and invalid configurations before pushing.


```bash
tdx sg validate [target]
```

| Argument | Description |
|  --- | --- |
| `target` | File or directory to validate (optional, defaults to context directory) |



```bash
# Validate all segments and journeys in context directory
tdx sg validate

# Validate a specific file
tdx sg validate high-value-customers.yml

# Validate a specific directory
tdx sg validate segments/my-audience
```

**Validations performed:**

For segments:

- Missing or empty `name` field
- Empty attribute values in conditions
- Invalid operator types
- Missing required operator fields (e.g., `value` for Equal, `min`/`max` for Between)
- Invalid `arrayMatching` configuration


For journeys:

- Missing `name` or empty `stages`
- Duplicate step names
- Invalid `next` step references
- Wait step condition references to undefined embedded segments
- Decision branch references to undefined segments
- A/B test variant percentages not summing to 100%
- Invalid jump step targets


**Example output:**


```
✔ high-value-customers.yml (segment)

✖ bad-journey.yml (journey): 2 error(s)

bad-journey.yml:15:7: error [MISSING_SEGMENT_REFERENCE]
Wait condition references undefined segment 'missing_segment'
    14 |     condition:
    15 |       segment: missing_segment
       |       ^
    16 |       next: to_end

bad-journey.yml:22:5: error [INVALID_NEXT_REFERENCE]
Step references non-existent step 'nonexistent'
    21 |   name: activation_step
    22 |     next: nonexistent
       |     ^
    23 |     with:

Validation failed: 1 file(s) with errors, 1 valid
```

Validation also runs automatically before `tdx sg push`, so you can catch errors early in your workflow.

## Segment YAML Schema

Each segment has its own YAML file with optional activations:


```yaml
# segments/my-audience/us-customers.yml
name: US Customers
description: All customers in the United States

rule:
  type: Value
  attribute: country
  operator:
    type: Equal
    value: US
```


```yaml
# segments/my-audience/marketing/high-value-customers.yml
name: High Value Customers
description: Customers with LTV > $1000
kind: batch        # batch, realtime, or funnel_stage
visible: true      # Show in UI (default: true)

rule:
  type: And
  conditions:
    - type: Value
      attribute: ltv
      operator:
        type: Greater
        value: 1000

activations:
  - name: Daily Salesforce Sync
    description: Sync high-value customers to SFDC daily
    connection: my-salesforce-connection
    all_columns: false
    columns:
      - email
      - first_name
      - last_name
      - ltv
    schedule:
      type: daily
      timezone: America/Los_Angeles
    connector_config:
      object: Contact
      mode: upsert

  - name: Weekly Marketing Cloud Export
    connection: marketing-cloud-export
    all_columns: true
    schedule:
      type: weekly
      repeat_sub_frequency: [1]  # Monday
      timezone: UTC
    notification:
      notify_on:
        - onSuccess
        - onFailure
      email_recipients:
        - user@example.com  # Must be TD account email
```

### Activation Schema

Activations (syndications) define how segment data is exported to external systems:

| Field | Description | Required |
|  --- | --- | --- |
| `name` | Activation name (used for matching) | Yes |
| `description` | Description | No |
| `connection` | TD Connection name (use `tdx connections` to list) | Yes |
| `all_columns` | Export all columns | No (default: false) |
| `columns` | Columns to export (if not all_columns) | No |
| `schedule` | Schedule configuration | No |
| `connector_config` | Connector-specific settings (see below) | No |
| `notification` | Notification settings (see below) | No |


Finding Connection Names
Use `tdx connections` to list available connections and their names:


```bash
tdx connections
```

**Schedule Types:**

| Type | Description | Additional Fields |
|  --- | --- | --- |
| `none` | Manual trigger only | - |
| `minutes_interval` | Run every N minutes | `repeat_frequency` (interval in minutes) |
| `hourly` | Run every hour | - |
| `daily` | Run daily | `timezone` |
| `weekly` | Run weekly | `repeat_sub_frequency` (day numbers 0-6), `timezone` |
| `monthly` | Run monthly | `repeat_sub_frequency` (day numbers 1-31), `timezone` |
| `cron` | Cron expression | `cron`, `timezone` |


**Column Format:**

Columns can be simple strings or objects with additional properties:


```yaml
columns:
  # Simple column name
  - email
  - first_name

  # Column with visibility setting
  - name: ssn
    visibility: masked  # clear or masked
```

**Notification Settings:**

Configure email notifications for activation runs:


```yaml
notification:
  notify_on:
    - onSuccess    # Notify on successful completion
    - onFailure    # Notify on failure
  email_recipients:
    - user@example.com  # Must be TD account email addresses
```

| Field | Description |
|  --- | --- |
| `notify_on` | Events to notify on: `onSuccess`, `onFailure` |
| `email_recipients` | List of email addresses (must be registered TD account emails) |


**Connector Config Settings:**

The `connector_config` field contains connector-specific settings that vary by connection type. Use `tdx connection schema <connection>` to see available fields for a specific connection.


```yaml
# Example: Treasure Data connector
connector_config:
  database_name: my_database
  table_name: my_table
  mode: append  # append or replace

# Example: Salesforce Marketing Cloud connector
connector_config:
  de_name: CustomerSegment
  shared_data_extension: false
```

Schema Validation
When pushing segments, tdx automatically validates `connector_config` against the connector's schema. Invalid values or unknown fields will show helpful error messages:


```
Error: Invalid connector_config for activation "My Activation":
  × mode: Invalid value for "Mode"
    Expected: one of: append, replace
    Received: invalid_mode
```

Use `tdx connection schema <connection>` to see valid field names and values.

### Important Behaviors

**Filename Collisions:**

When pulling segments, filenames are sanitized (lowercase, spaces to hyphens). If two segments would result in the same filename (e.g., "My Segment" and "my-segment"), numeric suffixes are added:

- `my-segment.yml` (first segment)
- `my-segment-1.yml` (second segment)


**Activation Matching:**

Activations are matched by `name` only. This has important implications:

- **Renaming an activation** in YAML will delete the old activation and create a new one (losing execution history and statistics)
- To preserve an activation's history, update its properties without changing the name


**Segment Matching:**

Segments are matched by `folder + name`. This means:

- You can have segments with the same name in different folders
- Moving a segment YAML file to a different folder creates a new segment (does not move the existing one)


### Supported Operators

All operators use the unified `value` field. When multiple values are needed (e.g., `In`, `Contain`), provide an array.

#### Comparison Operators

| Operator Type | Required Fields | Value Type | Description |
|  --- | --- | --- | --- |
| `Equal` | `value` | string, number, boolean | Exact match |
| `NotEqual` | `value` | string, number, boolean | Not equal (use `not: true` with `Equal`) |
| `Greater` | `value` | number | Greater than |
| `GreaterEqual` | `value` | number | Greater than or equal |
| `Less` | `value` | number | Less than |
| `LessEqual` | `value` | number | Less than or equal |
| `Between` | `minValue`, `maxValue` | number | Value in range (exclusive) |


#### List Operators

| Operator Type | Required Fields | Value Type | Description |
|  --- | --- | --- | --- |
| `In` | `value` | array of strings/numbers | Value in set |
| `NotIn` | `value` | array of strings/numbers | Value not in set (use `not: true` with `In`) |


#### String Operators

| Operator Type | Required Fields | Value Type | Description |
|  --- | --- | --- | --- |
| `Contain` | `value` | array of strings | Contains any substring |
| `StartWith` | `value` | array of strings | Starts with any prefix |
| `EndWith` | `value` | array of strings | Ends with any suffix |
| `Regexp` | `value` | regex pattern string | Matches regular expression |


#### Null Operators

| Operator Type | Required Fields | Description |
|  --- | --- | --- |
| `IsNull` | (none) | Checks if value is null |


#### Time Operators

| Operator Type | Required Fields | Description |
|  --- | --- | --- |
| `TimeWithinPast` | `value`, `unit` | Within past N time units |
| `TimeWithinNext` | `value`, `unit` | Within next N time units |
| `TimeToday` | (none) | Matches today |
| `TimeThis` | `from.unit` | Current period (this week, this month, etc.) |
| `TimeNext` | `from.unit` | Next period (next week, next month, etc.) |
| `TimeRange` | `from`, `to` or `from`, `duration` | Complex time range |
| `TimeInBetweenNext` | `from`, `to` | Between two future dates |


### Time Units

For time-based operators (`TimeWithinPast`, `TimeWithinNext`, etc.), the `unit` field must be one of:

| Unit | Description |
|  --- | --- |
| `year` | Years |
| `quarter` | Quarters |
| `month` | Months |
| `week` | Weeks |
| `day` | Days |
| `hour` | Hours |
| `minute` | Minutes |
| `second` | Seconds |


Both singular (`day`, `week`) and plural (`days`, `weeks`) forms are accepted. Plural forms are automatically normalized.

### Negation with `not`

Most operators support a `not` field to invert the condition:


```yaml
# Emails NOT containing "@test.com"
operator:
  type: Contain
  value: ["@test.com"]
  not: true

# Value NOT equal to "inactive"
operator:
  type: Equal
  value: inactive
  not: true
```

### Operator Examples

**In (multiple values):**


```yaml
# Match customers in US, Canada, or Mexico
operator:
  type: In
  value: ["US", "CA", "MX"]
```

**NotIn (exclude multiple values):**


```yaml
# Exclude test and spam accounts
operator:
  type: In
  value: ["test", "spam", "internal"]
  not: true
```

**Contain (multiple substrings):**


```yaml
# Match emails from specific domains
operator:
  type: Contain
  value: ["@gmail.com", "@yahoo.com", "@outlook.com"]
```

**StartWith (multiple prefixes):**


```yaml
# Match product SKUs starting with specific prefixes
operator:
  type: StartWith
  value: ["PRO-", "ENT-", "PREM-"]
```

**EndWith (multiple suffixes):**


```yaml
# Match files with specific extensions
operator:
  type: EndWith
  value: [".pdf", ".doc", ".xlsx"]
```

**Between (numeric range):**


```yaml
# Age between 18 and 65
operator:
  type: Between
  minValue: 18
  maxValue: 65
```

**TimeWithinPast:**


```yaml
operator:
  type: TimeWithinPast
  value: 30
  unit: day  # Must be singular
```

**TimeWithinNext:**


```yaml
operator:
  type: TimeWithinNext
  value: 7
  unit: day
```

**TimeThis (current period):**


```yaml
operator:
  type: TimeThis
  from:
    unit: month  # This month
```

**TimeNext (next period):**


```yaml
operator:
  type: TimeNext
  from:
    unit: week  # Next week
```

**TimeRange (complex range):**


```yaml
# Last 3 months
operator:
  type: TimeRange
  from:
    last: 3
    unit: month
  duration:
    month: 3
```

### Segment Reference Conditions

You can include or exclude members of other segments using `type: include` or `type: exclude`:


```yaml
rule:
  type: And
  conditions:
    # Include members of another segment
    - type: include
      segment: california_customers

    # Exclude members of another segment
    - type: exclude
      segment: churned_users

    # Combined with value conditions
    - type: Value
      attribute: tier
      operator:
        type: Equal
        value: premium
```

| Type | Description |
|  --- | --- |
| `type: include` | Include profiles that are members of the referenced segment |
| `type: exclude` | Exclude profiles that are members of the referenced segment |


The `segment` field references another child segment by name within the same parent segment.

### Complex Rule Example


```yaml
rule:
  type: And
  conditions:
    # High value OR premium member
    - type: Or
      conditions:
        - type: Value
          attribute: ltv
          operator:
            type: Greater
            value: 1000
        - type: Value
          attribute: membership
          operator:
            type: Equal
            value: premium

    # Active within last 30 days
    - type: Value
      attribute: last_activity
      operator:
        type: TimeWithinPast
        unit: day
        value: 30

    # Not from test accounts
    - type: Value
      attribute: email
      operator:
        type: Contain
        value:
          - "@test.com"
        not: true

    # Exclude users already in another segment
    - type: exclude
      segment: already_contacted
```

## Related Commands

For managing **parent segments** (audiences), use the dedicated `tdx parent-segment` command (alias: `tdx ps`).

See [Parent Segment Commands](/treasure-code/commands/parent-segment) for full documentation including:

- `list` - List parent segments
- `pull` - Pull configuration to YAML
- `push` - Push YAML configuration
- `validate` - Validate configuration
- `preview` - Preview sample data
- `run` - Run the workflow