Segment Commands

Manage CDP segments for audiences and activations.

Alias

tdx sg is an alias for tdx segment

Commands

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

YAML Sync

Command	Description
`pull`	Pull child segments to YAML files
`push`	Push YAML files to TD as child segments
`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.

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

INFO

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

TIP

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

TIP

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

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

See Parent Segment Commands 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

Segment Commands ​

Commands ​

Navigation & Discovery ​

YAML Sync ​

Typical Usage ​

How It Works ​

Folder Structure ​

Context-Based Workflow ​

Commands ​

use ​

list ​

view ​

desc ​

show ​

sql ​

fields ​

pull ​

push ​

validate ​

Segment YAML Schema ​

Activation Schema ​

Important Behaviors ​

Supported Operators ​

Comparison Operators ​

List Operators ​

String Operators ​

Null Operators ​

Time Operators ​

Time Units ​

Negation with not ​

Operator Examples ​

Segment Reference Conditions ​

Complex Rule Example ​

Related Commands ​

Segment Commands

Commands

Navigation & Discovery

YAML Sync

Typical Usage

How It Works

Folder Structure

Context-Based Workflow

Commands

use

list

view

desc

show

sql

fields

pull

push

validate

Segment YAML Schema

Activation Schema

Important Behaviors

Supported Operators

Comparison Operators

List Operators

String Operators

Null Operators

Time Operators

Time Units

Negation with `not`

Operator Examples

Segment Reference Conditions

Complex Rule Example

Related Commands