# Parent Segment Commands Manage CDP parent segments (audiences) with YAML-based configuration files. ```bash tdx parent-segment # Full command tdx ps # Shorthand alias ``` | Command | Description | | --- | --- | | [`list`](#list) | List all parent segments | | [`use`](#use) | Set parent segment context for subsequent commands | | [`pull`](#pull) | Download configuration from CDP API to YAML file | | [`push`](#push) | Upload YAML configuration to CDP API (create/update) | | [`validate`](#validate) | Query database tables to check schema and join statistics | | [`preview`](#preview) | Query database tables for sample data | | [`run`](#run) | Push changes (if any) and trigger workflow | | [`fields`](#fields) | List available fields for segmentation | | [`view`](#view) | Show parent segment details (or open in browser with `-w`) | | [`desc`](#desc) | Show parent segment schema (column types) | | [`sql`](#sql) | Get SQL query for parent segment | | [`show`](#show) | Execute SQL query and show results | | [`rt`](#rt-2-0-commands) | RT 2.0 configuration management (`list`, `validate`) | | [`pz`](#personalization-commands) | Personalization service management (`list`, `init`) | ## Typical Usage ```bash # 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 ``` 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). ```mermaid flowchart TB subgraph LOCAL["Local"] YAML["parent_segments/*.yml"] end subgraph TD["Treasure Data"] API["CDP API"] DB[("Source Tables")] WF["Treasure Workflow"] subgraph CDP["cdp_audience_xxx database"] TABLES[("customers
behavior tables")] end CHILD["Child Segments"] end YAML <-->|"pull / push"| API YAML -.->|"validate / preview"| DB API -->|"run / scheduled"| WF DB -->|"input"| WF WF -->|"creates"| TABLES CHILD -.->|"queries"| TABLES ``` ## Folder Structure Parent segment YAML files are stored in the `parent_segments/` directory by convention: ``` parent_segments/ ├── customer-360.yml ├── demo-audience.yml └── sales-leads.yml ``` All commands accept `` without the `.yml` suffix: - `tdx ps validate customer-360` looks for `parent_segments/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 ` | Output file path (default: `parent_segments/.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_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 ``` ### 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_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 ``` **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 [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 ` | 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 [options] ``` | Option | Description | | --- | --- | | `--master` | Show master table sample | | `--attribute ` | Show attribute sample data | | `--behavior ` | Show behavior sample data | | `--enriched` | Show enriched master sample | | `--interval ` | Time range for behavior queries (default: `-1d`) | 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 [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 output database schema (column types) for the `customers` table and behavior tables. ```bash tdx ps desc [name] [options] ``` | Option | Description | | --- | --- | | `-o, --output ` | Output file path | The `name` argument is optional if you have set a parent segment context with `tdx ps use`. ```bash # 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 ``` **Example output (stdout):** ``` 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 │ └──────────────┴───────────┘ ``` **Example output (--output):** ``` Schema saved to schema.json Database: cdp_audience_12345 Tables: 1 customers + 5 behaviors Columns: 42 total ``` **JSON file structure (one column per line for grep):** ```json { "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" } ] } ] } ``` ### 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 ` | 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 ``` ## RT 2.0 Commands Manage RT (Real-Time) 2.0 configuration for parent segments. RT enables real-time event processing and attribute updates for personalization use cases. ```bash tdx ps rt ``` | Command | Description | | --- | --- | | [`rt list`](#rt-list) | List RT-enabled parent segments | | [`rt validate`](#rt-validate) | Validate RT 2.0 configuration from YAML | Pushing RT configuration Use `tdx ps push` to push the full parent segment configuration including `realtime:` and `personalization_services:` sections. The diff will show exactly which sections changed. ```bash tdx ps push customer-360 # Shows diff of all changes (including RT/PZ) ``` ### rt list List parent segments that have RT 2.0 enabled. Only shows RT-enabled segments (not all parent segments). ```bash tdx ps rt list [pattern] ``` ```bash # 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 ``` **Example output:** ``` ✔ Found 2 RT-enabled parent segments ⚡ customer-360 (2.5M) ⚡ realtime-users (120K) ``` ### rt validate Validate RT 2.0 configuration from a parent segment YAML file. Checks events, attributes, ID stitching, and personalization services. ```bash tdx ps rt validate [name] ``` The `name` argument is optional if you have set a parent segment context with `tdx ps use`. ```bash # Validate RT config tdx ps rt validate customer-360 # With context set tdx ps rt validate ``` **Example output:** ``` 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 ``` ## Personalization Commands Manage personalization services for parent segments. Personalization services define how real-time attributes are served to end users based on trigger events and criteria. ```bash tdx ps pz ``` | Command | Description | | --- | --- | | [`pz list`](#pz-list) | List personalization services | | [`pz init`](#pz-init) | Add template personalization section to YAML | **Typical workflow:** ```bash 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) ``` ### pz list List personalization services configured for a parent segment. ```bash tdx ps pz list [name] ``` The `name` argument is optional if you have set a parent segment context with `tdx ps use`. ```bash # List personalization services tdx ps pz list "Customer 360" # With context set tdx ps pz list # JSON output tdx ps pz list --json ``` **Example output:** ``` ✔ 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 ``` ### pz init Add a template `realtime:` and `personalization_services:` section to an existing parent segment YAML file. ```bash tdx ps pz init [name] ``` The `name` argument is optional if you have set a parent segment context with `tdx ps use`. ```bash # Add personalization template to YAML tdx ps pz init customer-360 # With context set tdx ps pz init ``` **Example output:** ``` ✔ 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 ``` The generated template adds these sections to your YAML: ```yaml realtime: events: - name: page_view source_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 ``` ## RT 2.0 YAML Format The `realtime:` and `personalization_services:` sections are added to the parent segment YAML alongside the existing `master:`, `attributes:`, and `behaviors:` sections. ```yaml 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 ``` ### RT attribute types | Type | Description | | --- | --- | | `single` | Latest value (overwrites on each event) | | `counter` | Incrementing count | | `set` | Unordered set of unique values | | `ordered_set` | Ordered set of unique values | | `list` | API alias for `set` | | `imported_batch` | Batch-imported attribute from parent segment |