Segment

tdx Segment - CDP Child Segment Management

Segment Creation Workflow

Process one segment at a time. For each segment:

1. Create the YAML file
2. Validate with tdx sg validate <file>
3. Count check — run tdx sg sql --path <file> | tdx query - and verify count > 0
   • If count is 0, the rule is too restrictive — revise before proceeding
4. Preview with preview_segment tool — get user approval before proceeding
5. Push with tdx sg push -y "<file>" — always specify the file path explicitly

Never batch multiple segments in validate or push operations.

After push succeeds, display the Console link:

https://console.treasuredata.com/app/audiences/<parent_id>/segments/<segment_id>

Editing segments safely — read this first

All segment edits go through the typed tdx sg commands. Never edit a segment with raw tdx api HTTP calls.

• Never tdx api PUT/PATCH a segment. Raw writes skip validation and can erase a segment's rule. Use the typed command for the change you want: tdx sg move to change folder, tdx sg push to change rules/activations.
• Never read-modify-write a segment. Do not GET a segment and write the object back — rule fields can come back empty from list/entities reads, so writing it back erases the rule. Always use the dedicated command for the specific change.
• To change only the folder, use tdx sg move (below). It changes the folder and nothing else.

If a typed command seems not to exist for what you need, ask the user — do not fall back to raw tdx api.

Core Commands

tdx sg use "Customer 360"             # Set parent segment context
tdx sg pull "Customer 360"            # Pull to YAML (creates segments/customer-360/*.yml)
tdx sg validate <file>                # Validate specific file locally
tdx sg push --dry-run "<file>"        # Server-side validation (quote paths with special chars)
tdx sg push -y "<file>"               # Push specific file (-y for non-interactive)

tdx sg list                           # List segments
tdx sg list -r                        # Recursive tree view
tdx sg fields                         # List available fields
tdx sg show "Segment Name"            # Preview segment data
tdx sg sql "Segment Name" | tdx query -  # Pipe segment SQL to query
tdx sg sql --path <file>              # Get SQL from local YAML (requires tdx.json)

tdx sg move <segment...> --folder <folder>  # Safely move segment(s) by ID or name to a folder (preserves rules)

Note: --path requires a project directory created by tdx sg pull. The file must be inside a folder with tdx.json.

Moving segments between folders

To move one or more segments to a different folder, use tdx sg move. It changes only the folder — the segment's rule and activations are left untouched (it re-reads and verifies the rule survived).

tdx sg move 12345 --folder 67890              # by ID
tdx sg move 12345 12346 --folder 67890        # several at once
tdx sg move 12345 --folder 67890 --dry-run    # preview, makes no changes

# By name — needs a parent segment context:
tdx sg use "Customer 360"
tdx sg move "VIP Customers" --folder "Archive"                       # by name
tdx sg move "Marketing/VIP Customers" --folder "Marketing/Archive"   # nested path

• Segments and the target folder can be given by numeric ID or by name/path (names resolve within the current parent segment context).
• Find a segment or folder by name with tdx sg list '<pattern>' -r — it searches the whole tree for names matching <pattern> (case-insensitive; a plain string matches as a substring, so 'VIP (US)' matches that name as-is; * and ? are wildcards) and prints each match with its full folder path + id, ready to pass to tdx sg move. On several matches it lists them all — pass the intended path/id, and if more than one matches, ask the user which; never assume the first. If it returns too many matches, narrow the pattern. (tdx sg list -r alone dumps the full tree.) Do not use the ids returned by tdx sg create.
• If you skip the search and run tdx sg move '<name>' with a name that matches several segments, the move refuses and lists them — pick the intended full path/id (or ask the user); it will not guess.
• In tdx sg move, name matching is case-insensitive; an ambiguous name errors and lists the matches with their IDs so you can pass the ID instead.
• Names are relative to the parent segment — do not prefix the parent segment name.
• A bare name in sg move only resolves a segment at the parent's top level. If the name is nested, sg move won't move the wrong thing: it tells you the segment is nested and prints its full path (or, if the name matches several, lists them all and refuses). Either way, take the full folder path it shows — or find it up front with tdx sg list '<name>' -r — and move by that path (Folder/Sub/Segment Name).
• Footgun: the same name can exist both at the top level and inside a folder (names are unique only within a folder). A bare sg move name then silently resolves the top-level one. When a name may not be unique, use the full folder path so you move the intended segment.
• The same name can appear in several different folders. If tdx sg list '<pattern>' -r returns more than one match, do not pick one — show the user each with its full folder path and id, and ask which they mean. Only move once you have a single unambiguous path. Never move "the first one you found".

YAML Configuration

name: High Value US Customers
kind: batch  # batch | realtime | funnel_stage

rule:
  type: And  # And | Or
  conditions:
    - type: Value
      attribute: country
      operator:
        type: In
        value: ["US", "CA"]
    - type: Value
      attribute: ltv
      operator:
        type: Greater
        value: 1000
    - type: Value
      attribute: last_purchase_date
      operator:
        type: TimeWithinPast
        value: 30
        unit: day

Condition Types

Five condition types can be used inside conditions::

Operators

Negation: Any operator supports not: true (e.g., type: Contain, value: ["test"], not: true)

Units: year | quarter | month | week | day | hour | minute | second (singular only)

TimeRange Example

"7-day window starting from 1 month ago":

operator:
  type: TimeRange
  duration:
    day: 7                       # Window length
  from:
    last: 1                      # Starting point offset
    unit: month

Behavior Conditions

Query behavior table data with aggregations. Use type: Value with source and aggregation fields.

# Sum order_total for Electronics purchases in last 90 days
- type: Value
  attribute: ""                      # Empty string for behavior aggregations
  source: behavior_purchase_history  # behavior_<table_name> (prefix required)
  aggregation:
    type: Sum                        # Count | Sum | Average | Min | Max
    column: order_total              # Required for Sum/Average/Min/Max (not Count)
  operator:
    type: Greater
    not: false
    value: 500
  timeWindow:                        # Optional: restrict to recent window
    duration: 90
    unit: day
  filter:                            # Required when using source
    type: And
    conditions:
      - type: Column                 # Use Column (not Value) inside filter
        column: category             # Use column (not attribute) field
        operator:
          type: Equal
          not: false
          value: "Electronics"

Important: Inside filter.conditions, use type: Column with column field (not type: Value with attribute).

Segment References (Include/Exclude)

Reference segments that already exist on the server by their exact name.

rule:
  type: And
  conditions:
    - type: include
      segment: "Existing Segment Name"  # Must match name exactly as shown in TD Console
    - type: exclude
      segment: "Churned Users"

Limitation: Cannot reference unpushed local segments. The segment must already exist on the server.

Nested Condition Groups

Supported, but flagged. tdx sg validate flags nested Or/And groups with a NESTED_CONDITION_GROUP warning — the segment still validates and pushes successfully. The warning exists because the Console UI's SQL preview doesn't render nested groups correctly; segment execution itself is unaffected.

Alternative for same-attribute Or: the In operator

When you need "value A OR value B" on the same attribute, In is simpler and avoids the warning entirely:

# Nested Or (works, but triggers the Console-preview warning):
- type: Or
  conditions:
    - type: Value
      attribute: activities
      operator: { type: Equal, value: "Intermediate" }
    - type: Value
      attribute: activities
      operator: { type: Equal, value: "Advanced" }

# In operator (equivalent result, no warning):
- type: Value
  attribute: activities
  operator:
    type: In
    value: ["Intermediate", "Advanced"]

Or across different attributes

Unlike same-attribute Or, there's no In-style alternative for combining different attributes (e.g. (country = "US") OR (age > 30)) — nesting is the only way to express it, and it's fine to use; just expect the NESTED_CONDITION_GROUP warning and know the Console's SQL preview won't render it correctly even though it runs correctly.

Array Matching

Add arrayMatching to Value conditions: any | all | { atLeast: N } | { atMost: N } | { exactly: N }

Folder Structure

segments/customer-360/
├── active-users.yml
├── marketing/
│   └── email-subscribers.yml

Common Issues

Related Skills

• activation - Configure activations (connections, schedule, columns)
• connector-config - connector_config fields per connector type
• validate-segment - Validate segment YAML syntax and error codes
• parent-segment - Manage parent segments

Resources

• https://tdx.treasuredata.com/commands/segment.html