Parent Segment Commands

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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

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

# 2. Edit YAML file locally (add attributes, behaviors, etc.)
# Open parent_segments/customer-360.yml in your text editor

# 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

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

tdx ps list [pattern]

# 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*"

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

tdx ps use [name]

# 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

Session Context
  parent_segment: Customer 360

✔ Context set: parent_segment = Customer 360

tdx ps pull [name] [options]

# Pull to default location (normalizes name to lowercase with hyphens)
tdx ps pull "Customer 360"
# Creates: parent_segments/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

tdx ps push [name] [options]

# Push configuration (looks for parent_segments/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

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]

tdx ps validate <name> [options]

# 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

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"

tdx ps preview <name> [options]

# 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

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 │
└─────────────┴─────┴────────┴────────┘

tdx ps run <name> [options]

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

# Skip confirmation
tdx ps run customer360 -y

✔ 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

tdx ps fields [name]

# 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

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)

tdx ps view [name] [options]

# 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

┌──────────────────┬────────────────────────────────────────┐
│ 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                   │
└──────────────────┴────────────────────────────────────────┘

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

tdx ps desc [name] [options]

# Show all tables to stdout
tdx ps desc "Customer 360"

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

# Save to file
tdx ps desc "Customer 360" -o schema.json

# With context set (tdx ps use "Customer 360")
tdx ps desc
tdx ps desc -o schema.json

Output Database: cdp_audience_12345

customers (cdp_audience_12345.customers)
┌─────────────┬─────────┐
│ Column      │ Type    │
├─────────────┼─────────┤
│ customer_id │ varchar │
│ email       │ varchar │
│ age         │ integer │
│ gender      │ varchar │
└─────────────┴─────────┘

Purchases (cdp_audience_12345.behavior_purchases)
┌──────────────┬───────────┐
│ Column       │ Type      │
├──────────────┼───────────┤
│ customer_id  │ varchar   │
│ amount       │ double    │
│ purchased_at │ timestamp │
│ time         │ bigint    │
└──────────────┴───────────┘

Schema saved to schema.json
  Database: cdp_audience_12345
  Tables: 1 customers + 5 behaviors
  Columns: 42 total

{
  "database": "cdp_audience_12345",
  "parent_segment": "Customer 360",
  "parent_id": "12345",
  "customers": {
    "table": "customers",
    "columns": [
      { "name": "customer_id", "type": "varchar" },
      { "name": "email", "type": "varchar" },
      { "name": "age", "type": "bigint" }
    ]
  },
  "behaviors": [
    {
      "table": "behavior_purchases",
      "columns": [
        { "name": "customer_id", "type": "varchar" },
        { "name": "amount", "type": "double" },
        { "name": "time", "type": "bigint" }
      ]
    }
  ]
}

tdx ps sql [name]

# 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

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

tdx ps show [name] [options]

# 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

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      │
└─────────────┴─────────────────────┴─────┴────────┘

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

tdx ps rt <command>

tdx ps rt list [pattern]

# List all RT-enabled parent segments
tdx ps rt list

# Filter by pattern
tdx ps rt list "Customer*"

# JSON output
tdx ps rt list --json

✔ Found 2 RT-enabled parent segments
⚡ customer-360 (2.5M)
⚡ realtime-users (120K)

tdx ps rt validate [name]

# Validate RT config
tdx ps rt validate customer-360

# With context set
tdx ps rt validate

RT 2.0 Validate: Customer 360
════════════════════════════════════════════════════════════

RT 2.0: ⚡ Enabled
  Events: 2 configured
    ✔ page_view
    ✔ purchase
  Attributes: 3 configured
    ✔ last_page_viewed (single)
    ✔ total_purchases (counter)
    ✔ last_purchase_date (single)
  ID Stitching: td_client_id + [email, phone]
  Personalization: 1 service
    - My Service
────────────────────────────────────────────────────────────

✔ RT configuration is valid

tdx ps pz <command>

tdx ps pz init customer-360   # Scaffold template RT + personalization YAML
# Edit parent_segments/customer-360.yml to configure services
tdx ps rt validate customer-360  # Validate RT config
tdx ps push customer-360      # Push all changes (including RT/PZ sections)

tdx ps pz list [name]

# List personalization services
tdx ps pz list "Customer 360"

# With context set
tdx ps pz list

# JSON output
tdx ps pz list --json

✔ Found 2 personalization services
  Product Recommendations trigger=page_view (3 sections)
    Personalized product recommendations based on browsing behavior
  Welcome Banner trigger=session_start (1 section)
    Dynamic welcome message for returning visitors

tdx ps pz init [name]

# Add personalization template to YAML
tdx ps pz init customer-360

# With context set
tdx ps pz init

✔ Added personalization template to parent_segments/customer-360.yml
✔ Added RT 2.0 template section

Next steps:
  1. Edit parent_segments/customer-360.yml to configure your personalization service
  2. Run tdx ps push customer-360 to push the configuration

realtime:
  events:
    - name: page_view
      source_table: <database>.<table>
  attributes:
    - name: last_page_viewed
      type: single
  id_stitching:
    primary_key: td_client_id

personalization_services:
  - name: My Service
    description: Personalization service description
    trigger_event: page_view
    sections:
      - name: Default
        criteria: "true"
        attributes:
          - last_page_viewed

name: "Customer 360"

master:
  database: cdp_db
  table: customers

# ... attributes, behaviors, schedule ...

realtime:
  events:
    - name: page_view                     # Event name (required)
      source_table: web_db.pageviews      # Source table reference
    - name: purchase
      source_table: sales_db.transactions
      filter_pattern: "status=completed"  # Optional filter

  attributes:
    - name: last_page_viewed              # Attribute name (required)
      type: single                        # single, counter, set, ordered_set, list, imported_batch
      source_event: page_view             # Source event
      source_field: page_url              # Field from source event
    - name: total_purchases
      type: counter
    - name: recent_categories
      type: set

  id_stitching:
    primary_key: td_client_id             # Primary key (required)
    stitching_keys:                       # Additional keys for identity resolution
      - email
      - phone
    exclusion_patterns:                   # Patterns to exclude
      - "bot_*"

personalization_services:
  - name: Product Recommendations         # Service name (required)
    description: Personalized products    # Description
    trigger_event: page_view              # Event that triggers the service
    sections:
      - name: High Value                  # Section name
        criteria: "total_purchases > 10"  # Criteria expression
        attributes:                       # Attributes to serve
          - last_page_viewed
          - recent_categories
        batch_segments:                   # Batch segment names to include
          - VIP Customers
      - name: Default
        criteria: "true"                  # Catch-all section
        attributes:
          - last_page_viewed