Parent Segment Commands

Manage CDP parent segments (audiences) with YAML-based configuration files.

bash

tdx parent-segment <command>   # Full command
tdx ps <command>               # Shorthand alias

Command	Description
`list`	List all parent segments
`use`	Set parent segment context for subsequent commands
`pull`	Download configuration from CDP API to YAML file
`push`	Upload YAML configuration to CDP API (create/update)
`validate`	Query database tables to check schema and join statistics
`preview`	Query database tables for sample data
`run`	Push changes (if any) and trigger workflow
`fields`	List available fields for segmentation
`view`	Show parent segment details (or open in browser with `-w`)
`desc`	Show parent segment schema (column types)
`sql`	Get SQL query for parent segment
`show`	Execute SQL query and show results

Typical Usage

bash

# 1. Pull config (auto-sets context for subsequent commands)
tdx ps pull "Customer 360"
# Creates: parent_segment/customer-360.yml

# 2. Edit YAML file locally (add attributes, behaviors, etc.)
vim parent_segment/customer-360.yml

# 3. Validate configuration (name omitted - uses context)
tdx ps validate

# 4. Preview sample data
tdx ps preview --master
tdx ps preview --attribute "User Profile"
tdx ps preview --behavior "Purchases"

# 5. Push changes and run workflow
tdx ps run

# Or just push to trigger scheduled run
tdx ps push

Behavior Statistics Time Range

The default interval --interval -1d only counts behavior events from the last 24 hours. For behaviors with lower activity or weekly/monthly patterns, use a longer interval:

bash

tdx ps validate --interval -7d    # Last 7 days
tdx ps validate --interval -30d   # Last 30 days

How It Works

A parent segment defines the master customer table and its related data sources (attributes and behaviors) for CDP audience building. The YAML configuration specifies:

Master table: The primary customer/user table with unique identifiers
Attributes: Dimension tables joined to enrich customer profiles
Behaviors: Event/transaction tables for behavioral segmentation

The tdx parent-segment commands help you manage these configurations as local YAML files. You can pull existing configurations from Treasure Data, edit them locally, validate against source tables, preview sample data, and push changes back. The run command triggers the workflow execution.

When the workflow runs, it creates an output database (cdp_audience_xxx) containing the enriched customers table and behavior tables that child segments query for audience creation. Once created, you can explore this data using tdx ps desc (schema), tdx ps sql (query), and tdx ps show (sample data).

Folder Structure

Parent segment YAML files are stored in the parent_segment/ directory by convention:

parent_segment/
├── customer-360.yml
├── demo-audience.yml
└── sales-leads.yml

All commands accept <name> without the .yml suffix:

tdx ps validate customer-360 looks for parent_segment/customer-360.yml
Explicit paths still work: tdx ps validate ./other/path/file.yml

Commands

list

List all parent segments.

bash

tdx ps list [pattern]

bash

# List all parent segments (alphabetically sorted)
tdx ps list

# Filter by wildcard pattern
tdx ps list "Customer*"
tdx ps list "*Demo"

# Case-insensitive matching
tdx ps list "*test*"

Example output:

✔ Found 3 parent segments
👥 customer-360 (2.5M)
👥 customer-demo (50K)
👥 sales-leads (12.5K)

use

Set or show parent segment context. When a name is provided, sets the context. Without arguments, shows the current context.

bash

tdx ps use [name]

This is equivalent to tdx use parent_segment [name].

bash

# Show current context
tdx ps use

# Set context to a parent segment
tdx ps use "Customer 360"

# Now these commands work without specifying the name
tdx ps pull
tdx ps push
tdx ps fields
tdx ps view
tdx ps desc
tdx ps sql
tdx ps show

# Clear context
tdx use --clear parent_segment

Example output (show context):

Session Context
  parent_segment: Customer 360

Example output (set context):

✔ Context set: parent_segment = Customer 360

pull

Pull a parent segment configuration from Treasure Data to a local YAML file.

bash

tdx ps pull [name] [options]

Option	Description
`-o, --output <file>`	Output file path (default: `parent_segment/<normalized-name>.yml`)
`-y, --yes`	Skip confirmation prompt

The name argument is optional if you have set a parent segment context with tdx ps use.

Pull automatically sets the context to the pulled parent segment.

bash

# Pull to default location (normalizes name to lowercase with hyphens)
tdx ps pull "Customer 360"
# Creates: parent_segment/customer-360.yml

# Pull to specific file
tdx ps pull "Customer 360" -o custom-name.yml

# Skip confirmation
tdx ps pull "Customer 360" -y

# With context set (tdx ps use "Customer 360")
tdx ps pull

push

Push a local YAML configuration to Treasure Data (creates new or updates existing).

bash

tdx ps push [name] [options]

Option	Description
`-y, --yes`	Skip confirmation prompt

The name argument is optional if you have set a parent segment context with tdx ps use.

bash

# Push configuration (looks for parent_segment/customer360.yml)
tdx ps push customer360

# Explicit path
tdx ps push ./configs/customer360.yml

# Skip confirmation
tdx ps push customer360 -y

# With context set (tdx ps use "customer360")
tdx ps push

Example diff output:

Changes to apply to 'Customer 360':
────────────────────────────────────────────────────────────
  6   6     - name: User Profile
  7   7       columns:
  8     -       - column: age
  9     -         type: number
      8 +       - column: age
      9 +         label: "Customer Age"
     10 +         type: number
     11 +       - column: income
     12 +         label: "Annual Income"
     13 +         type: number
────────────────────────────────────────────────────────────
Apply changes to 'Customer 360'? [y/N]

validate

Validate a parent segment YAML configuration by executing schema queries and showing join statistics.

bash

tdx ps validate <name> [options]

Option	Description
`--master`	Validate only master table
`--attribute [name]`	Validate attributes (optionally filter by name)
`--behavior [name]`	Validate behaviors (optionally filter by name)
`--enriched`	Validate enriched master schema
`--interval <range>`	Time range for behavior stats (default: `-1d`)

bash

# Validate all components
tdx ps validate customer360

# Validate only master table
tdx ps validate customer360 --master

# Validate only attributes
tdx ps validate customer360 --attribute

# Validate a specific attribute
tdx ps validate customer360 --attribute "User Profile"

# Validate only behaviors
tdx ps validate customer360 --behavior

# Validate a specific behavior
tdx ps validate customer360 --behavior "Purchases"

# Validate enriched master schema
tdx ps validate customer360 --enriched

# Custom time range for behavior stats
tdx ps validate customer360 --interval -7d

Example output:

Validate: Customer 360

Master Table
  cdp_db.customers (2.5M rows)

Attributes
  User Profile — Coverage: 95.2% (2.38M rows)
  Contact Info — Coverage: 78.5% (1.96M rows)

Behaviors (-1d)
  Purchases — 1.2M customers (48.0%), 8.5M events

────────────────────────────────────────────────────────────
Configuration is valid

To view sample data:
  tdx ps preview customer360 --attribute "User Profile"
  tdx ps preview customer360 --behavior "Purchases"

preview

Show sample data from a parent segment YAML configuration.

bash

tdx ps preview <name> [options]

Option	Description
`--master`	Show master table sample
`--attribute <name>`	Show attribute sample data
`--behavior <name>`	Show behavior sample data
`--enriched`	Show enriched master sample
`--interval <range>`	Time range for behavior queries (default: `-1d`)

INFO

One of --master, --attribute, --behavior, or --enriched is required.

bash

# Show master table sample
tdx ps preview customer360 --master

# Show attribute sample data
tdx ps preview customer360 --attribute "User Profile"

# Show behavior sample data
tdx ps preview customer360 --behavior "Purchases"

# Show enriched master sample
tdx ps preview customer360 --enriched

# Custom time range
tdx ps preview customer360 --behavior "Page Views" --interval -7d

Example output:

Attribute: User Profile — Coverage: 95.2% (2.38M rows)
┌─────────────┬─────┬────────┬────────┐
│ customer_id │ age │ gender │ income │
├─────────────┼─────┼────────┼────────┤
│ C001        │  35 │ M      │  75000 │
│ C002        │  28 │ F      │  62000 │
│ C003        │  42 │ M      │  95000 │
└─────────────┴─────┴────────┴────────┘

run

Run the parent segment workflow to (re)generate the audience.

bash

tdx ps run <name> [options]

Option	Description
`-y, --yes`	Skip confirmation prompt

If a local YAML file exists for the segment, it will be pushed first before running the workflow.

bash

# Run workflow (pushes YAML if exists locally)
tdx ps run customer360

# Skip confirmation
tdx ps run customer360 -y

Example output:

✔ Workflow started
  Audience ID: 12345
  Status: running
  Session: 306281053
  Attempt: 987654321
  https://console.us01.treasuredata.com/app/workflows/44073028/sessions/306281053/attempt/987654321

To cancel: tdx wf attempt 987654321 kill

fields

List available fields for segmentation from a parent segment.

bash

tdx ps fields [name]

The name argument is optional if you have set a parent segment context with tdx ps use.

bash

# List all available fields
tdx ps fields "Customer 360"

# JSON output
tdx ps fields "Customer 360" --json

# With context set (tdx ps use "Customer 360")
tdx ps fields

Example output:

Fields for Customer 360
────────────────────────────────────────────────────────────
  Name                  Type      Source
  customer_id           string    master
  email                 string    master
  age                   number    User Profile (attribute)
  gender                string    User Profile (attribute)
  purchase_amount       number    Purchases (behavior)
  purchased_at          timestamp Purchases (behavior)

view

Show parent segment details or open in web browser.

bash

tdx ps view [name] [options]

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

The name argument is optional if you have set a parent segment context with tdx ps use.

bash

# Show segment details
tdx ps view "Customer 360"

# Open in web browser
tdx ps view "Customer 360" -w

# JSON output for programmatic access
tdx ps view "Customer 360" --json

# With context set (tdx ps use "Customer 360")
tdx ps view
tdx ps view -w

Example output:

┌──────────────────┬────────────────────────────────────────┐
│ id               │ 12345                                  │
│ name             │ Customer 360                           │
│ description      │ Complete customer view                 │
│ populationCount  │ 2500000                                │
│ audienceDatabaseName │ cdp_audience_12345                 │
│ createdAt        │ 2024-01-15T10:30:00Z                   │
│ updatedAt        │ 2024-03-20T14:45:00Z                   │
└──────────────────┴────────────────────────────────────────┘

Example output (with -w):

✔ Opening https://console-next.us01.treasuredata.com/app/dw/parentSegments/12345

desc

Show parent segment schema (column types) by executing a DESCRIBE query.

bash

tdx ps desc [name]

The name argument is optional if you have set a parent segment context with tdx ps use.

bash

# Show schema
tdx ps desc "Customer 360"

# JSON output
tdx ps desc "Customer 360" --json

# With context set (tdx ps use "Customer 360")
tdx ps desc

Example output:

Query: 1.2s (8 rows)
┌─────────────┬─────────┬─────────┐
│ Column      │ Type    │ Extra   │
├─────────────┼─────────┼─────────┤
│ customer_id │ varchar │         │
│ email       │ varchar │         │
│ age         │ integer │         │
│ gender      │ varchar │         │
└─────────────┴─────────┴─────────┘

sql

Get the SQL query that defines a parent segment.

bash

tdx ps sql [name]

The name argument is optional if you have set a parent segment context with tdx ps use.

bash

# Get SQL query
tdx ps sql "Customer 360"

# JSON output
tdx ps sql "Customer 360" --json

# With context set (tdx ps use "Customer 360")
tdx ps sql

Example output:

sql

SELECT
  customer_id,
  email,
  age,
  gender
FROM cdp_audience_12345.customers

show

Execute the parent segment SQL query and display results.

bash

tdx ps show [name] [options]

Option	Description
`--limit <n>`	Limit number of rows (default: 100)

The name argument is optional if you have set a parent segment context with tdx ps use.

bash

# Show sample data
tdx ps show "Customer 360"

# Limit results
tdx ps show "Customer 360" --limit 10

# JSON output
tdx ps show "Customer 360" --json

# With context set (tdx ps use "Customer 360")
tdx ps show
tdx ps show --limit 10

Example output:

Query: 0.8s (100 rows)
┌─────────────┬─────────────────────┬─────┬────────┐
│ customer_id │ email               │ age │ gender │
├─────────────┼─────────────────────┼─────┼────────┤
│ C001        │ alice@example.com   │  35 │ F      │
│ C002        │ bob@example.com     │  28 │ M      │
│ C003        │ carol@example.com   │  42 │ F      │
└─────────────┴─────────────────────┴─────┴────────┘

YAML Format

yaml

name: "Customer 360"
description: "Complete customer view"

master:
  database: cdp_db
  table: customers
  filters:                      # Optional: max 2 filters
    - column: status
      values: ["active"]

schedule:
  type: daily                   # none, hourly, daily, weekly, monthly, cron
  time: "03:00"
  timezone: "America/Los_Angeles"

engine:
  hive_only: false              # false = Trino + Hive (default)
  trino_pool: null              # Optional: Trino resource pool
  hive_pool: null               # Optional: Hive resource pool

attributes:
  - name: "User Profile"        # Logical grouping name
    source:
      database: cdp_db
      table: user_profiles
    join:
      parent_key: user_id       # Key in master table
      child_key: customer_id    # Key in source table
    columns:
      - column: age             # Source column name
        label: "Age"            # Display name (optional)
        type: number
      - column: gender
        type: string

behaviors:
  - name: "Purchases"
    source:
      database: cdp_db
      table: purchase_events
    join:
      parent_key: user_id
      child_key: customer_id
    columns:
      - column: amount
        label: "Purchase Amount"
        type: number
      - column: purchased_at
        type: timestamp

  - name: "Page Views"
    source:
      database: cdp_db
      table: pageview_events
    join:
      parent_key: visitor_id
      child_key: customer_id
    all_columns: true           # Include all columns from table

Parent Segment Commands ​

Typical Usage ​

How It Works ​

Folder Structure ​

Commands ​

list ​

use ​

pull ​

push ​

validate ​

preview ​

run ​

fields ​

view ​

desc ​

sql ​

show ​

YAML Format ​

Parent Segment Commands

Typical Usage

How It Works

Folder Structure

Commands

list

use

pull

push

validate

preview

run

fields

view

desc

sql

show

YAML Format