Segment Commands (CDP)

CDP (Customer Data Platform) segment management for audiences and activations with file-system-like navigation.

Alias

tdx sg is an alias for tdx segment

Command	Description
list	List folders and segments at path
use	Set current segment/folder context
info	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
pull	Pull child segments to YAML files
push	Push YAML files to TD as child segments
create	Create child segment (deprecated)
update	Update child segment (deprecated)
folder create	Create segment folder
parent	Parent segment management →

Typical Usage

# 1. Pull all child segments from a parent to YAML files
tdx sg pull "My Audience"
# Creates: segments/my-audience/

# 2. Edit YAML files locally (add/modify segments, create folders)
cd segments/my-audience
vim segments.yml

# 3. Push changes back to TD (creates folders and segments)
tdx sg push

# 4. Review segments in TD
tdx segments "My Audience" -r

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

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

Folder Structure

Pull creates a folder structure mirroring the TD folder hierarchy:

segments/
└── my-audience/              # Normalized from "My Audience"
    ├── tdx.json              # { "parent_segment": "My Audience" }
    ├── segments.yml          # Root-level segments
    ├── marketing/
    │   └── segments.yml      # Segments in Marketing folder
    └── sales/
        ├── segments.yml      # Segments in Sales folder
        └── q1/
            └── segments.yml  # Segments in Sales/Q1 folder

Path Format

• Parent segment: "My Audience"
• Child segment: "My Audience/High Value Users"
• Nested folders: "My Audience/Marketing/Campaigns/Email Q1"
• Pattern matching: "*DEMO", "test*", "*audience*"

INFO

Names are case-sensitive

Navigation Commands

# Set current context to parent or folder
tdx segment use "My Audience/Marketing"

# Clear context (back to root)
tdx segment use /

# Navigate to parent folder
tdx segment use ..

Discovery Commands

List Segments

tdx segments [path]               # List segments
tdx segment list [path]           # Same as segments

# List contents in current context (or all parents if no context)
tdx segments

# List folders + segments at specified path
tdx segments "My Audience/Marketing"

# List parents matching pattern (glob)
tdx segments "*DEMO"

# List recursively (tree view)
tdx segments -r

# Recursive tree from path
tdx segments "My Audience" -r

Info, Describe, and Show

# Show details (parent/folder/segment)
tdx segment info "My Audience/Marketing"
tdx segment describe "My Audience/Marketing"  # alias for info

# Show details using context (after `tdx use parent_segment <name>`)
tdx segment info

# Show schema (column names and types)
tdx segment desc "My Audience/Premium Users"

# Show schema using context
tdx segment desc

# Execute segment SQL query and show results
tdx segment show "My Audience/Premium Users"

# Show results using context
tdx segment show

# Get SQL query for segment
tdx segment sql "My Audience/Marketing/Premium"

# Get SQL using context
tdx segment sql

# List available fields for segmentation
tdx segment fields "My Audience"

# List fields using context
tdx segment fields

YAML-Based Workflow

The recommended way to manage child segments is using the YAML-based pull and push commands. This approach enables version control, code review, and infrastructure-as-code practices.

Pull Child Segments

Pull all child segments from a parent segment to YAML files:

# Pull all segments from parent (uses context or specify parent name)
tdx sg pull "My Audience"

# Pull using context
tdx segment use "My Audience"
tdx sg pull

# Pull specific segment file (updates existing file)
tdx sg pull segments/My_Audience/High_Value.yml

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

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

Push Child Segments

Push segments from segments.yml to Treasure Data:

# Push all segments (uses context or specify parent name)
tdx sg push "My Audience"

# Push using context
tdx segment use "My Audience"
tdx sg push

# Push from specific directory
tdx sg push segments/my_audience

# Preview changes without applying
tdx sg push "My Audience" --dry-run

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

Features:

• Automatically creates missing TD folders
• Shows diff before applying changes
• Creates new segments or updates existing ones based on segment name

Segments YAML Schema

Each folder has its own segments.yml file containing the segments in that folder:

# segments/my_audience/segments.yml (root-level segments)
segments:
  - name: US Customers
    rule:
      type: Value
      attribute: country
      operator:
        type: Equal
        value: US

# segments/my_audience/Marketing/segments.yml (Marketing folder)
segments:
  - name: High Value Customers
    description: Customers with LTV > $1000
    rule:
      type: And
      conditions:
        - type: Value
          attribute: ltv
          operator:
            type: Greater
            value: 1000

  - name: Premium Members
    kind: batch        # batch, realtime, or funnel_stage
    visible: true      # Show in UI (default: true)
    rule:
      type: Value
      attribute: membership
      operator:
        type: Equal
        value: premium

Supported Operators

Operator Type	Description	Example
Equal	Exact match	value: "active"
NotEqual	Not equal	value: "inactive"
Greater	Greater than	value: 1000
GreaterEqual	Greater or equal	value: 18
Less	Less than	value: 100
LessEqual	Less or equal	value: 65
In	In set	values: ["US", "CA"]
NotIn	Not in set	values: ["spam", "test"]
Contain	Contains substring	values: ["@gmail.com"]
StartWith	Starts with	values: ["Premium"]
EndWith	Ends with	values: [".com"]
Regexp	Regex match	value: "^[A-Z]{2}[0-9]{4}$"
IsNull	Is null check	(no value needed)
TimeWithinPast	Within past N units	value: 30, unit: day

Complex Rule Example

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
        values:
          - "@test.com"
        not: true

Management Commands (Deprecated)

Deprecation Notice

The create and update commands are deprecated. Use tdx sg pull and tdx sg push instead for YAML-based workflow.

Create Child Segment

# Create segment with simple rule (inline JSON)
tdx segment create "My Audience/High Value" \
  --description "Customers with LTV > $1000" \
  --rule '{"type":"And","conditions":[...]}'

# Create segment with rule from file
tdx segment create "My Audience/High Value US" \
  --description "High value US customers" \
  --rule-file examples/segment-rule-complex.json

# Create segment in folder
tdx segment create "My Audience/Premium" \
  --rule-file examples/segment-rule-simple.json \
  --folder "Geographic Segments"

# Create realtime segment
tdx segment create "My Audience/Realtime Active" \
  --rule-file rule.json \
  --kind 1  # 0=batch, 1=realtime, 2=funnel_stage

Parent Segment Management

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
• info - Show parent segment details
• desc - Show parent segment schema

Update Child Segments

# Update child segment
tdx segment update "My Audience/High Value" \
  --name "Super High Value" \
  --rule-file updated-rule.json

# Move segment to folder
tdx segment update "My Audience/High Value" \
  --folder "Premium Customers"

Parent Segment Updates

Use tdx ps pull and tdx ps push to update parent segment configuration. See Parent Segment Commands.

Create Folders

# Create top-level folder
tdx segment folder create "My Audience" "Q1 2024 Campaigns" \
  --description "Campaign segments for Q1"

# Create nested folder
tdx segment folder create "My Audience" "West Region" \
  --parent-folder "Geographic Segments"

Segment Rule Syntax

Supported operators:

• Comparison: Equal, NotEqual, Greater, GreaterEqual, Less, LessEqual
• Set: In, NotIn
• Text: Contains, StartsWith, EndsWith
• Pattern: Regex
• Time: TimeWithinPast

Example rule structure:

{
  "type": "And",
  "conditions": [
    {
      "type": "Value",
      "leftValue": {"name": "Lifetime Value"},
      "operator": {"type": "Greater", "rightValue": 1000}
    },
    {
      "type": "Value",
      "leftValue": {"name": "Country"},
      "operator": {"type": "In", "rightValues": ["US", "UK", "CA"]}
    }
  ]
}

Navigation Workflow Example

# List all parent segments
tdx segments
# Output:
# 👥 My Audience (50K)
# 👥 Sales Leads (12.5K)

# Navigate into a parent
tdx segment use "My Audience"

# List folders + segments
tdx segments
# Output:
# 📁 Marketing
# 📁 Sales
# 🎯 Active Users (35K)

# Recursive tree view
tdx segments -r
# Output:
# 📁 Marketing
# ├── 📁 Campaigns
# │   ├── 🎯 Email Q1 (5.23K)
# │   └── 🎯 Email Q2 (6.12K)
# └── 🎯 Email Subscribers (15K)
# 🎯 Active Users (35K)