Agent skill

tdx-basic

Executes tdx CLI commands for Treasure Data. Covers `tdx databases`, `tdx tables`, `tdx describe`, `tdx query`, `tdx auth setup`, context management with profiles/sessions, and output formats (JSON/TSV/table). Use when users need tdx command syntax, authentication setup, database/table exploration, schema inspection, or query execution.

View SKILL.md on GitHub Repository
Stars 16
Forks 23

Install this agent skill to your Project

npx add-skill https://github.com/treasure-data/td-skills/tree/main/tdx-skills/tdx-basic

SKILL.md

tdx CLI - Basic Operations

Setup

bash
npm install -g @treasuredata/tdx

# Interactive setup (recommended)
tdx auth setup
tdx auth setup --profile production  # Multiple accounts

# Or manual: create ~/.config/tdx/.env
TDX_API_KEY=your-key-id/your-key-secret

# Verify
tdx auth

Context Management

Context priority: CLI flags > session > project tdx.json > profile > global config

bash
# Session context (scoped to current shell, expires after 24h)
tdx use database mydb
tdx profile use production   # Switch profile
tdx status                   # View current context and auth
tdx unset database           # Clear specific context
tdx use --clear              # Clear all session context

Session database eliminates the need for fully-qualified table names across commands:

bash
tdx use database mydb
tdx tables                   # Lists mydb tables
tdx query "select * from users limit 10"  # Queries mydb.users

Profile Management

bash
tdx profile list             # List all profiles
tdx profile create staging   # Create new profile (interactive)
tdx profile set database=dev # Set profile config
tdx --profile staging query "..." # One-off with different profile

Profiles (~/.config/tdx/tdx.json)

json
{
  "profiles": {
    "production": { "site": "us01", "database": "analytics" },
    "dev": { "site": "jp01", "database": "dev_db" }
  }
}

Project Config (tdx.json in project root)

json
{
  "site": "us01",
  "database": "customer_analytics",
  "parent_segment": "active_users"
}

Core Commands

Databases

bash
tdx databases                    # List all
tdx databases "prod_*"           # Filter with pattern
tdx databases --json             # JSON output

Sites: us01 (default), jp01, eu01, ap02

Tables

When the target database is known, set context first:

bash
tdx use database mydb            # Set context first
tdx tables                       # List tables in context database
tdx tables "user_*"              # Filter by pattern within context database

# Pattern syntax
tdx tables "mydb.*"              # All tables from mydb

Avoid tdx tables "*.table_name" — cross-database wildcard search is expensive. Set the database context instead.

Schema Inspection

Use tdx describe (or tdx desc) to check table schema:

bash
tdx describe mydb.users              # Fully-qualified
tdx desc users                       # Omit database if session database is set
tdx describe mydb.users --json       # JSON output
tdx show mydb.users --limit 10       # Preview actual data (not schema)

Queries

Query output is truncated to 40 rows by default. Use --limit to return more:

bash
tdx query "select * from users" --limit 100   # Return up to 100 rows
bash
# With session database set, use unqualified table names
tdx use database mydb
tdx query "select * from users limit 10"

# Or use fully-qualified names without session context
tdx query "select * from mydb.users limit 10"

tdx query -f query.sql           # From file
tdx query -                      # From stdin
echo "select 1" | tdx query -
tdx sg sql "Segment Name" | tdx query -  # Pipe segment SQL

Output Formats

bash
tdx databases --json             # JSON
tdx query "..." --jsonl          # JSON Lines (streaming)
tdx databases --tsv              # TSV
tdx databases --output out.json  # Save to file

Global Options

bash
tdx <command> --help             # Command help
--profile <name>                 # Use specific profile
--json / --jsonl / --tsv         # Output format
--output <file>                  # Save to file
--dry-run                        # Preview without executing

TD-Specific Conventions

  • Table naming: database_name.table_name
  • Time column: Unix timestamp (seconds since epoch), not datetime
  • Time filtering: Use td_interval(time, '-1d/now') or td_time_range(time, 'start', 'end') for partition pruning
  • Timezone: UTC default; use td_interval(time, '-1d', 'JST') for Japan
sql
select time, from_unixtime(time) as datetime from mydb.events limit 1

Project Folder Structure

tdx organizes resources into conventional folders:

my-project/
├── tdx.json                    # Project config (site, database, contexts)
├── parent_segments/            # Parent segment definitions
│   ├── customer-360.yml
│   └── demo-audience.yml
├── segments/                   # Child segments and journeys (per parent)
│   └── customer-360/
│       ├── tdx.json            # { "parent_segment": "Customer 360" }
│       ├── high-value.yml      # Segment
│       ├── onboarding.yml      # Journey (type: journey)
│       └── marketing/          # Folder organization
│           └── newsletter.yml
├── workflows/                  # Digdag workflow projects
│   └── daily-etl/
│       ├── tdx.json            # { "workflow_project": "daily-etl" }
│       └── main.dig
└── agents/                     # LLM agents (per project)
    └── my-llm-project/
        ├── tdx.json            # { "llm_project": "My LLM Project" }
        ├── support-agent/
        │   ├── agent.yml
        │   └── prompt.md
        └── knowledge_bases/
            └── faq.yml

Each tdx.json stores context for its directory—commands run from any subdirectory use the nearest config.

Resources

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

treasure-data/td-skills

email-campaign

This skill should be used when the user asks to "create an email", "build an email campaign", "design an email template", "generate an email for a segment", "preview an email", or "push an email to Engage". Generates enterprise-grade HTML email templates with live preview in Treasure Studio and natural language editing, then pushes the final version to Treasure Engage.

16 23
Explore
treasure-data/td-skills

action-report

YAML format reference for action reports rendered via preview_action_report. MUST be read before writing any action report YAML — defines the report structure (title, summary, actions array) and action item fields (as_is, to_be, reason, priority, category, impact) with incremental build workflow. Required by seo-analysis and any skill that produces prioritized recommendations.

16 23
Explore
treasure-data/td-skills

grid-dashboard

YAML format reference for grid dashboards rendered via preview_grid_dashboard. MUST be read before writing any dashboard YAML — defines the page structure, 6 cell types (kpi, gauge, scores, table, chart, markdown), grid layout rules, cell merging syntax, and incremental build workflow. Required by seo-analysis and any skill that produces visual data dashboards.

16 23
Explore
treasure-data/td-skills

seo-analysis

Runs SEO and AEO (Answer Engine Optimization) analysis on websites or specific pages. Use when the user mentions SEO, AEO, search rankings, search optimization, or wants to analyze how their pages perform in search engines and AI answers. Produces a data dashboard and action report with before/after recommendations.

16 23
Explore
treasure-data/td-skills

aps-doc-core

Core documentation generation patterns and framework for Treasure Data pipeline layers. Provides shared templates, quality validation, testing framework, and Confluence integration used by all layer-specific documentation skills.

16 23
Explore
treasure-data/td-skills

aps-doc-id-unification

Expert documentation generation for ID unification layers. Documents identity resolution algorithms, merge strategies, match rules, entity graphs, and multi-workflow orchestration. Use when documenting ID unification processes.

16 23
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results