tdx

Appearance

SDK API Reference / WorkflowSDK

Class: WorkflowSDK ​

Workflow operations API

Methods ​

applyPullProject() ​

applyPullProject(result, options?): Promise<void>

Apply pull result - extract files and update tdx.json

Parameters ​

result ​

PullWorkflowResult

Result from pullProject()

options? ​

PullWorkflowOptions

Original pull options (for revision)

Returns ​

Promise<void>

attempt() ​

attempt(attemptId): Promise<WorkflowAttempt>

Get a specific attempt

Parameters ​

attemptId ​

string

Attempt ID

Returns ​

Promise<WorkflowAttempt>

Workflow attempt details

Throws ​

When the get operation fails

Example ​

typescript
const attempt = await workflow.attempt('67890');

attempts() ​

attempts(options?): Promise<WorkflowAttempt[]>

List attempts (optionally filtered by project/workflow)

Parameters ​

options? ​

Filter and pagination options

includeRetried? ​

boolean

last_id? ​

string

limit? ​

number

projectName? ​

string

workflowName? ​

string

Returns ​

Promise<WorkflowAttempt[]>

Paginated list of attempts

Throws ​

When the list operation fails

Example ​

typescript
// List all attempts
const result = await workflow.attempts();

// List attempts for a project
const result = await workflow.attempts({ projectName: 'myproject' });

// List attempts for a workflow
const result = await workflow.attempts({
  projectName: 'myproject',
  workflowName: 'daily_etl'
});

delete() ​

delete(projectIdOrName): Promise<{ projectId: string; projectName: string; }>

Delete workflow project

Deletes a workflow project from Treasure Data

Parameters ​

projectIdOrName ​

string

Project ID or name

Returns ​

Promise<{ projectId: string; projectName: string; }>

Deleted project information

Throws ​

When the delete operation fails

Example ​

typescript
// Delete project by name
await workflow.delete('my_project');

// Delete project by ID
await workflow.delete('12345');

deleteSecret() ​

deleteSecret(projectIdOrName, key): Promise<{ key: string; projectName: string; }>

Delete a secret from a project

Parameters ​

projectIdOrName ​

string

Project ID or name

key ​

string

Secret key

Returns ​

Promise<{ key: string; projectName: string; }>

Project name and deleted secret key

Throws ​

When project is not found

Example ​

typescript
// Delete secret by project name
await workflow.deleteSecret('my_project', 'td.apikey');

// Delete secret by project ID
await workflow.deleteSecret('12345', 'db.password');

download() ​

download(projectIdOrName, outputDir, options?): Promise<{ filesExtracted: number; projectName: string; revision: string; }>

Download workflow project

Downloads a workflow project archive to a local directory

Parameters ​

projectIdOrName ​

string

Project ID or name

outputDir ​

string

Output directory path

options? ​

Download options

revision? ​

string

Returns ​

Promise<{ filesExtracted: number; projectName: string; revision: string; }>

Download result with project details

Throws ​

When the download operation fails

Example ​

typescript
// Download project by name
await workflow.download('my_project', './workflows');

// Download specific revision
await workflow.download('my_project', './workflows', {
  revision: 'v1.0.0'
});

executeCloneProject() ​

executeCloneProject(preview): Promise<CloneWorkflowResult>

Execute a workflow clone

Parameters ​

preview ​

CloneWorkflowPreview

Preview result from prepareCloneProject()

Returns ​

Promise<CloneWorkflowResult>

Clone result with project details

executePushProject() ​

executePushProject(result): Promise<{ projectId: string; projectName: string; revision: string; }>

Execute push - create archive and upload

Parameters ​

result ​

PushWorkflowResult

Result from preparePushProject()

Returns ​

Promise<{ projectId: string; projectName: string; revision: string; }>

Upload result with project ID, name, and revision

kill() ​

kill(attemptId, reason?): Promise<string>

Kill a running attempt

Parameters ​

attemptId ​

string

Attempt ID to kill

reason? ​

string

Optional reason for killing

Returns ​

Promise<string>

Kill response message

Throws ​

When the kill operation fails

Example ​

typescript
await workflow.kill('67890');
await workflow.kill('67890', 'manual stop');

listSecrets() ​

listSecrets(projectIdOrName): Promise<{ projectName: string; secrets: object[]; }>

List secret keys for a project

Parameters ​

projectIdOrName ​

string

Project ID or name

Returns ​

Promise<{ projectName: string; secrets: object[]; }>

Project name and array of secret keys

Throws ​

When project is not found

Example ​

typescript
// List secrets by project name
const result = await workflow.listSecrets('my_project');
console.log(result.secrets); // [{ key: 'td.apikey' }, ...]

// List secrets by project ID
const result = await workflow.listSecrets('12345');

logFiles() ​

logFiles(attemptId, taskName?): Promise<LogFileHandle[]>

List log files for an attempt

Parameters ​

attemptId ​

string

Attempt ID

taskName? ​

string

Optional task name to filter by

Returns ​

Promise<LogFileHandle[]>

Array of log file handles with pre-signed S3 URLs

Throws ​

When the list operation fails

Example ​

typescript
// List all log files
const files = await workflow.logFiles('67890');

// Filter by task
const files = await workflow.logFiles('67890', '+step1');

logs() ​

logs(attemptId, taskName?): Promise<string>

Get log content for an attempt/task

Downloads and decompresses log files from pre-signed S3 URLs

Parameters ​

attemptId ​

string

Attempt ID

taskName? ​

string

Optional task name to filter by

Returns ​

Promise<string>

Decompressed log content as string

Throws ​

When the get operation fails

Example ​

typescript
// Get all logs for an attempt
const logs = await workflow.logs('67890');

// Get logs for a specific task
const logs = await workflow.logs('67890', '+step1');

prepareCloneProject() ​

prepareCloneProject(sourceDir, newProjectName, options?): Promise<CloneWorkflowPreview>

Prepare a workflow clone - check if target exists and gather info

Creates a preview of a clone operation without executing it. Use executeCloneProject() to perform the actual clone.

Parameters ​

sourceDir ​

string

Source directory containing workflow files

newProjectName ​

string

Name for the new project

options? ​

CloneWorkflowOptions

Clone options

Returns ​

Promise<CloneWorkflowPreview>

Clone preview with existence check

Example ​

typescript
// Check if clone would overwrite existing project
const preview = await workflow.prepareCloneProject('./workflows/my-project', 'my-project-staging');
if (preview.targetExists) {
  console.log('Warning: Project already exists!');
}

// Execute the clone
const result = await workflow.executeCloneProject(preview);

preparePushProject() ​

preparePushProject(options?): Promise<PushWorkflowResult>

Prepare workflow push (sync-style)

Calculates changes between local files and remote project. Returns the result without pushing - use executePushProject() to upload.

Parameters ​

options? ​

PushWorkflowOptions

Push options

Returns ​

Promise<PushWorkflowResult>

Push result with changes

Example ​

typescript
// Prepare push and preview changes
const result = await workflow.preparePushProject();
console.log(result.summary); // { new: 1, modified: 2, deleted: 0, unchanged: 3 }

// Execute the push
const uploaded = await workflow.executePushProject(result);
console.log(uploaded.revision);

projects() ​

projects(pattern?, options?): Promise<WorkflowProject[]>

List all workflow projects

Parameters ​

pattern? ​

string

Optional glob pattern to filter project names (supports * and ?)

options? ​

Pagination options

last_id? ​

string

limit? ​

number

Returns ​

Promise<WorkflowProject[]>

Paginated list of workflow projects

Throws ​

When the list operation fails

Example ​

typescript
// List all projects
const result = await workflow.projects();

// Filter by pattern
const result = await workflow.projects('cdp_segment_*');

// Paginate results
const result = await workflow.projects(undefined, { limit: 50 });

pullProject() ​

pullProject(projectIdOrName, options?): Promise<PullWorkflowResult>

Pull workflow project (sync-style)

Downloads a workflow project and calculates changes against local files. Returns the result without applying changes - use applyPullProject() to write files.

Parameters ​

projectIdOrName ​

string

Project ID or name

options? ​

PullWorkflowOptions

Pull options

Returns ​

Promise<PullWorkflowResult>

Pull result with changes

Example ​

typescript
// Pull project and preview changes
const result = await workflow.pullProject('my_project');
console.log(result.summary); // { new: 2, modified: 1, deleted: 0, unchanged: 5 }

// Apply the changes
await workflow.applyPullProject(result);

push() ​

push(projectDir, options?): Promise<{ projectId: string; projectName: string; revision: string; }>

Push workflow project

Pushes a local workflow project directory to Treasure Data

Parameters ​

projectDir ​

string

Project directory path

options? ​

Push options

clearSchedule? ​

string[]

clearScheduleAll? ​

boolean

projectName? ​

string

revision? ​

string

scheduleFrom? ​

string

skipValidation? ​

boolean

Returns ​

Promise<{ projectId: string; projectName: string; revision: string; }>

Push result with project details

Throws ​

When the push operation fails

Example ​

typescript
// Push project with auto-generated revision
await workflow.push('./my_project');

// Push with specific revision
await workflow.push('./my_project', {
  revision: 'v1.0.0'
});

// Push with project name override
await workflow.push('./my_project', {
  projectName: 'production_workflow',
  revision: '2025-01-11'
});

resolveProjectId() ​

resolveProjectId(projectIdOrName): Promise<{ id: string; name: string; }>

Resolve project name or ID to project ID and name

Always returns both ID and the actual project name. If given a numeric ID, fetches the project to get its name. If given a name, searches for the project and returns its ID.

Parameters ​

projectIdOrName ​

string

Project ID or name

Returns ​

Promise<{ id: string; name: string; }>

Project ID and name

Throws ​

When project is not found

retryAttempt() ​

retryAttempt(attemptId, options?): Promise<{ attemptId: string; sessionId: string; }>

Retry an attempt

Parameters ​

attemptId ​

string

Attempt ID to retry

options? ​

Retry options

force? ​

boolean

resumeFrom? ​

string

retryParams? ​

Record<string, unknown>

Returns ​

Promise<{ attemptId: string; sessionId: string; }>

Retry response with new session/attempt IDs

Throws ​

When the retry operation fails

Example ​

typescript
// Retry attempt
const result = await workflow.retryAttempt('67890');

// Resume from specific task
const result = await workflow.retryAttempt('67890', {
  resumeFrom: '+step2'
});

// Force retry with parameter override
const result = await workflow.retryAttempt('67890', {
  force: true,
  retryParams: { key: 'value' }
});

retrySession() ​

retrySession(sessionId, options?): Promise<{ attemptId: string; sessionId: string; }>

Retry a session

Parameters ​

sessionId ​

string

Session ID to retry

options? ​

Retry options

fromTask? ​

string

retryParams? ​

Record<string, unknown>

Returns ​

Promise<{ attemptId: string; sessionId: string; }>

Retry response with new session/attempt IDs

Throws ​

When the retry operation fails

Example ​

typescript
// Retry entire session
const result = await workflow.retrySession('12345');

// Resume from specific task
const result = await workflow.retrySession('12345', {
  fromTask: '+step2'
});

// Override parameters
const result = await workflow.retrySession('12345', {
  retryParams: { key: 'value' }
});

run() ​

run(workflow, params, options?): Promise<StartAttemptResponse>

Start a workflow run

Parameters ​

workflow ​

string

Workflow identifier in format "project.workflow"

params ​

Record<string, unknown> = {}

Workflow parameters

options? ​

Optional session time (defaults to now)

sessionTime? ​

string

Returns ​

Promise<StartAttemptResponse>

Started attempt information

Throws ​

When workflow format is invalid or workflow not found

Example ​

typescript
// Start with project.workflow format
const result = await workflow.run('myproject.myworkflow', { key: 'value' });

// Start with custom session time
const result = await workflow.run('myproject.myworkflow', { key: 'value' }, {
  sessionTime: '2023-08-17T18:56:24+09:00'
});

sessions() ​

sessions(options?): Promise<WorkflowSession[]>

List workflow sessions

Parameters ​

options? ​

Session filter and pagination options

fromTime? ​

string

last_id? ​

string

limit? ​

number

projectName? ​

string

status? ​

SessionStatus

toTime? ​

string

workflowName? ​

string

Returns ​

Promise<WorkflowSession[]>

Paginated list of sessions

Throws ​

When the list operation fails

Example ​

typescript
// List all sessions
const result = await workflow.sessions();

// List sessions for specific workflow
const result = await workflow.sessions({
  projectName: 'myproject',
  workflowName: 'daily_etl'
});

// Filter by status
const result = await workflow.sessions({ status: 'error' });

setSecret() ​

setSecret(projectIdOrName, key, value): Promise<{ key: string; projectName: string; }>

Set a secret for a project

Parameters ​

projectIdOrName ​

string

Project ID or name

key ​

string

Secret key

value ​

string

Secret value

Returns ​

Promise<{ key: string; projectName: string; }>

Project name and secret key

Throws ​

When project is not found

Example ​

typescript
// Set secret by project name
await workflow.setSecret('my_project', 'td.apikey', 'xxx');

// Set secret by project ID
await workflow.setSecret('12345', 'db.password', 'secret');

tasks() ​

tasks(attemptId, includeSubtasks): Promise<WorkflowTask[]>

Get tasks for an attempt

Parameters ​

attemptId ​

string

Attempt ID

includeSubtasks ​

boolean = false

Whether to include subtasks

Returns ​

Promise<WorkflowTask[]>

Array of workflow tasks

Throws ​

When the get operation fails

Example ​

typescript
const tasks = await workflow.tasks('67890');
const allTasks = await workflow.tasks('67890', true); // Include subtasks

workflows() ​

workflows(projectName?, options?): Promise<Workflow[]>

List workflows (optionally filtered by project)

Parameters ​

projectName? ​

string

Optional project name to filter by

options? ​

Pagination options

last_id? ​

string

limit? ​

number

Returns ​

Promise<Workflow[]>

Paginated list of workflows

Throws ​

When the list operation fails

Example ​

typescript
// List all workflows
const result = await workflow.workflows();

// List workflows for a specific project
const result = await workflow.workflows('myproject');

Copyright 2024-present Treasure Data