tdx

Appearance

SDK API Reference / SegmentSDK

Class: SegmentSDK ​

Segment operations API

Methods ​

createFolder() ​

createFolder(parentIdOrName, request): Promise<CreateSegmentFolderResponse>

Create a new segment folder for organization

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

request ​

CreateSegmentFolderRequest

Folder creation request

Returns ​

Promise<CreateSegmentFolderResponse>

Created folder details

Throws ​

When the creation fails

Example ​

typescript
// Create top-level folder
const folder = await segment.createFolder('123', {
  name: 'Q1 2024 Campaigns',
  description: 'Campaign segments for Q1'
});

// Create nested folder
const folder = await segment.createFolder('My Audience', {
  name: 'West Region',
  parentFolderId: '789'
});

createParent() ​

createParent(request): Promise<CreateParentSegmentResponse>

Create a new parent segment (audience)

Parameters ​

request ​

CreateParentSegmentRequest

Parent segment creation request

Returns ​

Promise<CreateParentSegmentResponse>

Created parent segment details

Throws ​

When the creation fails

Example ​

typescript
// Create minimal parent segment
const parent = await segment.createParent({
  name: 'My Audience',
  master: {
    parentDatabaseName: 'mydb',
    parentTableName: 'customers'
  }
});

// Create with attributes and behaviors
const parent = await segment.createParent({
  name: 'Customer 360',
  description: 'Complete customer view',
  scheduleType: 'daily',
  scheduleOption: '03:00',
  master: {
    parentDatabaseName: 'customer_data',
    parentTableName: 'customers'
  },
  attributes: [
    {
      name: 'Lifetime Value',
      type: 'number',
      parentDatabaseName: 'customer_data',
      parentTableName: 'metrics',
      parentColumn: 'ltv',
      parentKey: 'customer_id',
      foreignKey: 'customer_id'
    }
  ]
});

createSegment() ​

createSegment(parentId, request): Promise<CreateSegmentResponse>

Create a new child segment with filtering rules

Parameters ​

parentId ​

string

Parent segment ID

request ​

CreateSegmentRequest

Segment creation request

Returns ​

Promise<CreateSegmentResponse>

Created segment details

Throws ​

When the creation fails

Example ​

typescript
// Create segment with simple rule
const segment = await segment.createSegment('123', {
  name: 'High Value Customers',
  description: 'Customers with LTV > 1000',
  rule: {
    type: 'And',
    conditions: [
      {
        type: 'Value',
        leftValue: { name: 'Lifetime Value' },
        operator: { type: 'Greater', rightValue: 1000 }
      }
    ]
  }
});

// Create segment in folder
const segment = await segment.createSegment('123', {
  name: 'US Customers',
  segmentFolderId: '789',
  rule: {
    type: 'And',
    conditions: [
      {
        type: 'Value',
        leftValue: { name: 'Country' },
        operator: { type: 'Equal', rightValue: 'US' }
      }
    ]
  }
});

detectResourceType() ​

detectResourceType(parentId, name): Promise<"folder" | "segment" | "ambiguous">

Detect resource type by name (folder, segment, or ambiguous)

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Resource name to detect

Returns ​

Promise<"folder" | "segment" | "ambiguous">

'folder', 'segment', or 'ambiguous' if both exist

Example ​

typescript
const type = await segment.detectResourceType('123', 'Marketing');
if (type === 'ambiguous') {
  // Prompt user to choose
}

detectResourceTypeInFolder() ​

detectResourceTypeInFolder(parentId, name, folderId?): Promise<"folder" | "segment" | "ambiguous">

Detect resource type by name within a specific folder

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Resource name to detect

folderId? ​

string

Folder ID to search within (undefined = root level)

Returns ​

Promise<"folder" | "segment" | "ambiguous">

'folder', 'segment', or 'ambiguous' if both exist

getFolder() ​

getFolder(folderId): Promise<SegmentFolderDetails>

Get segment folder details by folder ID

Parameters ​

folderId ​

string

Folder ID

Returns ​

Promise<SegmentFolderDetails>

Folder details in JSON:API format

Throws ​

When the get operation fails

Example ​

typescript
// Get folder details
const folder = await segment.getFolder('456');
console.log(folder);

getParent() ​

getParent(parentId): Promise<ParentSegment>

Get parent segment details

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<ParentSegment>

Parent segment details

Throws ​

When the get operation fails

Example ​

typescript
// Get parent segment details
const parent = await segment.getParent('123');
console.log(parent);

getParentFull() ​

getParentFull(parentIdOrName): Promise<CreateParentSegmentResponse>

Get full parent segment details including attributes and behaviors

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<CreateParentSegmentResponse>

Full parent segment details

Throws ​

When the get operation fails

Example ​

typescript
// Get full details by ID
const parent = await segment.getParentFull('123');

// Get full details by name
const parent = await segment.getParentFull('My Audience');
console.log(parent.attributes, parent.behaviors);

getParentSQL() ​

getParentSQL(parentId): Promise<string>

Get SQL query for parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<string>

SQL query string

Throws ​

When the SQL retrieval fails

Example ​

typescript
// Get SQL for parent segment
const sql = await segment.getParentSQL('123');
console.log(sql);

getSegment() ​

getSegment(parentId, segmentId): Promise<Segment>

Get segment details

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

Returns ​

Promise<Segment>

Segment details

Throws ​

When the get operation fails

Example ​

typescript
// Get segment details
const segment = await segment.getSegment('123', '456');
console.log(segment);

getSegmentSQL() ​

getSegmentSQL(parentId, segmentId): Promise<string>

Get SQL query for a segment with filtering

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

Returns ​

Promise<string>

SQL query string

Throws ​

When the SQL retrieval fails

Example ​

typescript
// Get SQL for segment
const sql = await segment.getSegmentSQL('123', '456');
console.log(sql);

listActivations() ​

listActivations(parentId, segmentId): Promise<Activation[]>

List activations for a segment

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

Returns ​

Promise<Activation[]>

Array of activations

Throws ​

When the list operation fails

Example ​

typescript
// List activations for segment
const activations = await segment.listActivations('123', '456');
console.log(activations);

listFields() ​

listFields(parentIdOrName): Promise<ParentSegmentField[]>

List available fields for a parent segment (for segmentation)

Extracts fields from parent segment's attributes and behaviors by calling GET /audiences/{id} and parsing the response.

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<ParentSegmentField[]>

Array of available fields (attributes, behaviors)

Throws ​

When the list operation fails

Example ​

typescript
// List fields by ID
const fields = await segment.listFields('123');

// List fields by name
const fields = await segment.listFields('My Audience');
console.log(fields);

listFolders() ​

listFolders(parentId): Promise<SegmentFolder[]>

List segment folders under a parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<SegmentFolder[]>

Array of segment folders

Throws ​

When the list operation fails

Example ​

typescript
// List segment folders
const folders = await segment.listFolders('123');
console.log(folders);

listParents() ​

listParents(): Promise<ParentSegment[]>

List all parent segments (audiences)

Returns ​

Promise<ParentSegment[]>

Array of parent segments

Throws ​

When the list operation fails

Example ​

typescript
// List all parent segments
const segments = await segment.listParents();
console.log(segments);

listRecursive() ​

listRecursive(parentId, folderId?, depth?, maxDepth?): Promise<SegmentTreeNode[]>

Build a tree structure recursively from a parent or folder

Parameters ​

parentId ​

string

Parent segment ID

folderId? ​

string

Optional folder ID to start from

depth? ​

number = 0

Current depth (for limiting recursion)

maxDepth? ​

number = 10

Maximum depth to traverse (default: 10)

Returns ​

Promise<SegmentTreeNode[]>

Tree nodes with nested children

Example ​

typescript
// Build full tree recursively
const tree = await segment.listRecursive('123');
console.log(tree);

listSegments() ​

listSegments(parentId): Promise<Segment[]>

List segments under a parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<Segment[]>

Array of child segments

Throws ​

When the list operation fails

Example ​

typescript
// List segments under parent
const segments = await segment.listSegments('123');
console.log(segments);

listUnified() ​

listUnified(parentId, folderId?): Promise<{ folders: SegmentFolder[]; segments: Segment[]; }>

List both folders and segments under a parent or within a folder (unified view)

Parameters ​

parentId ​

string

Parent segment ID

folderId? ​

string

Optional folder ID to list contents of a specific folder

Returns ​

Promise<{ folders: SegmentFolder[]; segments: Segment[]; }>

Object with folders and segments arrays

Example ​

typescript
// List all folders and segments under parent
const { folders, segments } = await segment.listUnified('123');
console.log(`Found ${folders.length} folders and ${segments.length} segments`);

previewParentYaml() ​

previewParentYaml(yamlContent, options): Promise<PreviewResult>

Preview parent segment YAML sample data

Fetches sample data from tables - no validation, just raw data. Requires one of: master, attribute, behavior, or enriched option.

Parameters ​

yamlContent ​

YAML configuration string or parsed object

string | ParentSegmentYaml

options ​

PreviewOptions = {}

Preview options (one required: master, attribute, behavior, enriched)

Returns ​

Promise<PreviewResult>

Preview result with sample data

pullParentYaml() ​

pullParentYaml(parentIdOrName): Promise<string>

Pull parent segment configuration as YAML string

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<string>

YAML configuration string

Throws ​

When the parent segment is not found

Example ​

typescript
const yaml = await segment.pullParentYaml('Customer 360');
console.log(yaml);

pushParentYaml() ​

pushParentYaml(yamlContent): Promise<PushParentYamlResult & object>

Push parent segment configuration from YAML

This method compares the YAML configuration with the existing parent segment (if any) and returns diff information. It does NOT apply the changes automatically. Use the apply method on the result or call createParent/updateParent to apply.

Parameters ​

yamlContent ​

YAML configuration string or parsed object

string | ParentSegmentYaml

Returns ​

Promise<PushParentYamlResult & object>

Push result with diff information and apply method

Throws ​

When YAML parsing fails or validation errors occur

Example ​

typescript
// Preview changes
const result = await segment.pushParentYaml(yamlContent);
if (result.hasChanges) {
  console.log(result.diffFormatted);
  // Apply changes
  await result.apply();
}

resolveFolderId() ​

resolveFolderId(parentId, name): Promise<string>

Resolve folder name to ID within a parent

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Folder name (case-sensitive)

Returns ​

Promise<string>

Folder ID

Throws ​

When the folder is not found

Example ​

typescript
// Resolve folder name to ID
const folderId = await segment.resolveFolderId('123', 'Marketing');
console.log(folderId); // '789'

resolveParentId() ​

resolveParentId(name): Promise<string>

Resolve parent segment name to ID

Parameters ​

name ​

string

Parent segment name (case-sensitive)

Returns ​

Promise<string>

Parent segment ID

Throws ​

When the parent segment is not found

Example ​

typescript
// Resolve parent name to ID
const parentId = await segment.resolveParentId('My Audience');
console.log(parentId); // '123'

resolvePathToResource() ​

resolvePathToResource(path): Promise<ResolvedSegmentPath>

Resolve a path string to a resource

Parameters ​

path ​

string

Path string (e.g., "My Audience/Marketing/High Value")

Returns ​

Promise<ResolvedSegmentPath>

Resolved path with IDs and type

Throws ​

When path is invalid or resource not found

Example ​

typescript
// Resolve path to segment or folder
const resolved = await segment.resolvePathToResource('My Audience/Marketing');
console.log(resolved.type); // 'folder'
console.log(resolved.folderId); // '456'

resolveSegmentId() ​

resolveSegmentId(parentId, name): Promise<string>

Resolve child segment name to ID within a parent

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Child segment name (case-sensitive)

Returns ​

Promise<string>

Child segment ID

Throws ​

When the child segment is not found

Example ​

typescript
// Resolve child segment name to ID
const segmentId = await segment.resolveSegmentId('123', 'High Value Users');
console.log(segmentId); // '456'

runParent() ​

runParent(parentIdOrName): Promise<AudienceExecution>

Run workflow to (re)generate a parent segment

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<AudienceExecution>

Workflow execution details

Throws ​

When the parent segment is not found or run fails

Example ​

typescript
// Run parent segment workflow by name
const execution = await segment.runParent('My Audience');
console.log(`Workflow started: ${execution.workflowSessionId}`);

traversePath() ​

traversePath(pathSegments): Promise<ResolvedSegmentPath>

Traverse a multi-level path and resolve to final resource

Parameters ​

pathSegments ​

string[]

Array of path components (e.g., ['My Audience', 'Marketing', 'Campaigns'])

Returns ​

Promise<ResolvedSegmentPath>

Resolved path with IDs and type

Example ​

typescript
const resolved = await segment.traversePath(['My Audience', 'Marketing', 'High Value']);
console.log(resolved.type); // 'folder' or 'segment'

updateParent() ​

updateParent(parentIdOrName, request): Promise<CreateParentSegmentResponse>

Update an existing parent segment (audience)

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

request ​

CreateParentSegmentRequest

Parent segment update request

Returns ​

Promise<CreateParentSegmentResponse>

Updated parent segment details

Throws ​

When the update fails

Example ​

typescript
// Update by ID
const updated = await segment.updateParent('123', {
  description: 'Updated description',
  attributes: [...] // Add new attributes
});

// Update by name
const updated = await segment.updateParent('My Audience', {
  scheduleType: 'weekly',
  scheduleOption: '0' // Sunday
});

updateSegmentById() ​

updateSegmentById(parentId, segmentId, request): Promise<UpdateSegmentResponse>

Update an existing child segment

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Child segment ID

request ​

UpdateSegmentRequest

Segment update request

Returns ​

Promise<UpdateSegmentResponse>

Updated segment details

Throws ​

When the update fails

Example ​

typescript
// Update segment name and description
const updated = await segment.updateSegmentById('123', '456', {
  name: 'Super High Value',
  description: 'LTV > 5000'
});

// Update segment rule
const updated = await segment.updateSegmentById('123', '456', {
  rule: {
    type: 'And',
    conditions: [
      {
        type: 'Value',
        leftValue: { name: 'Lifetime Value' },
        operator: { type: 'Greater', rightValue: 5000 }
      }
    ]
  }
});

validateParentYaml() ​

validateParentYaml(yamlContent, options): Promise<PreviewResult>

Validate parent segment YAML configuration

Validates schema and gathers statistics for a parent segment YAML before pushing. Does NOT fetch sample data - use previewParentYaml for that.

Parameters ​

yamlContent ​

YAML configuration string or parsed object

string | ParentSegmentYaml

options ​

ValidateOptions = {}

Validate options for filtering what to validate

Returns ​

Promise<PreviewResult>

Preview result with validation and statistics

Copyright 2024-present Treasure Data