tdx

SDK API Reference / QuerySDK

Class: QuerySDK ​

Query operations SDK

Provides Trino query execution and schema introspection:

  • Execute arbitrary SQL queries
  • List databases
  • List tables
  • Describe table schema
  • Show table contents

Methods ​

describeTable() ​

describeTable(database, table): Promise<ColumnInfo[]>

Describe table schema

Descriptions come from the Trino column comment and are returned untruncated; they are null for columns without a comment.

Parameters ​

database ​

string

Database name

table ​

string

Table name

Returns ​

Promise<ColumnInfo[]>

Array of columns with their metadata

Throws ​

When the describe operation fails

Throws ​

When database or table name is invalid (empty or whitespace-only)

Example ​

typescript
const schema = await tdx.query.describeTable('mydb', 'users');
// [{ column_name: 'id', data_type: 'bigint', is_nullable: 'NO', description: 'User ID' }, ...]

execute() ​

execute<T>(sql, options?): Promise<CompleteQueryResult<T>>

Execute a Trino query

Type Parameters ​

T ​

T = unknown

Parameters ​

sql ​

string

SQL query to execute

options? ​

SDKQueryOptions

Query options (catalog, schema, timeout, etc.)

Returns ​

Promise<CompleteQueryResult<T>>

Query result with data and metadata

Throws ​

When the query execution fails

Throws ​

When SQL is invalid (empty or whitespace-only)

Example ​

typescript
// Simple query
const result = await tdx.query.execute('SELECT * FROM mydb.users LIMIT 10');
console.log(result.data);

// Query with schema
const result = await tdx.query.execute('SELECT * FROM users LIMIT 10', {
  schema: 'mydb'
});

listDatabases() ​

listDatabases(pattern?, limit?): Promise<DatabaseInfo[]>

List all databases

Parameters ​

pattern? ​

string

Optional glob pattern to filter databases

limit? ​

number = DEFAULT_LISTING_LIMIT

Maximum number of databases to return (default: DEFAULT_LISTING_LIMIT)

Returns ​

Promise<DatabaseInfo[]>

Array of databases

Throws ​

When the database list operation fails

Throws ​

When pattern is invalid (empty or whitespace-only)

Example ​

typescript
// List all databases
const dbs = await tdx.query.listDatabases();

// List databases matching pattern
const prodDbs = await tdx.query.listDatabases('prod_*');

// List first 100 databases
const dbs = await tdx.query.listDatabases(undefined, 100);

listDeletedTables() ​

listDeletedTables(opts?): Promise<DeletedTablesResponse>

List deleted tables the caller can recover (7-day retention window).

cursorId is the id of the last row from the previous page. pageSize is 1-100 (default 25 server-side).

The returned cursor_id is the id of the last row on this page; pass it back as cursorId to fetch the next page. null means this is the final page.

Parameters ​

opts? ​
cursorId? ​

number

pageSize? ​

number

Returns ​

Promise<DeletedTablesResponse>

Example ​

typescript
const { tables, cursor_id } = await tdx.query.listDeletedTables({ pageSize: 50 });
if (cursor_id !== null) {
  const next = await tdx.query.listDeletedTables({ cursorId: cursor_id, pageSize: 50 });
}

listTables() ​

listTables(database?, pattern?, databasePattern?, limit?): Promise<TableInfo[]>

List tables

Supports multiple patterns:

  • listTables() - All tables from all databases
  • listTables('mydb') - All tables from mydb
  • listTables('mydb', 'user*') - Tables matching user* from mydb
  • listTables(undefined, 'user*') - Tables matching user* from all databases

Parameters ​

database? ​

string

Optional database name to filter tables

pattern? ​

string

Optional glob pattern to filter table names

databasePattern? ​

string

Optional glob pattern to filter database names

limit? ​

number = DEFAULT_LISTING_LIMIT

Maximum number of tables to return (default: DEFAULT_LISTING_LIMIT)

Returns ​

Promise<TableInfo[]>

Array of tables

Throws ​

When the table list operation fails

Throws ​

When database or pattern is invalid (empty or whitespace-only)

Example ​

typescript
// List all tables from all databases
const allTables = await tdx.query.listTables();

// List tables from specific database
const myTables = await tdx.query.listTables('mydb');

// List tables matching pattern
const userTables = await tdx.query.listTables('mydb', 'user_*');

// List tables from databases matching pattern
const prodTables = await tdx.query.listTables(undefined, undefined, 'prod_*');

// List first 50 tables
const tables = await tdx.query.listTables(undefined, undefined, undefined, 50);

recoverTable() ​

recoverTable(id, opts?): Promise<Table>

Recover a deleted table by id.

If the table or its parent database name conflicts with an existing one, pass tableName / databaseName to rename on recovery (server returns 409 otherwise).

Translates HTTP errors from the recovery endpoint to SDKError with descriptive messages and helpText, so commands can rely on the shared BaseCommand error formatter.

Parameters ​

id ​

number

numeric table id (typically from Premium Audit Logs or listDeletedTables)

opts? ​
databaseName? ​

string

restore into a different database

tableName? ​

string

rename the recovered table

Returns ​

Promise<Table>

showTable() ​

showTable<T>(database, table, limit?, catalog?): Promise<CompleteQueryResult<T>>

Show table contents (SELECT * with limit)

Supports multiple table reference formats:

  • Two-part: database.table (uses default catalog 'td')
  • Three-part: catalog.database.table (explicit catalog)

Type Parameters ​

T ​

T = unknown

Parameters ​

database ​

string

Database name (schema)

table ​

string

Table name

limit? ​

number = 40

Maximum number of rows to retrieve (default: 40)

catalog? ​

string

Optional catalog name (client defaults to 'td' if not provided)

Returns ​

Promise<CompleteQueryResult<T>>

Query result with data and metadata

Throws ​

When the show operation fails

Throws ​

When database or table name is invalid (empty or whitespace-only)

Throws ​

When limit is invalid (non-positive)

Example ​

typescript
// Two-part reference (client uses default 'td' catalog)
const result = await tdx.query.showTable('mydb', 'users', 10);

// Three-part reference (explicit catalog)
const result = await tdx.query.showTable('mydb', 'users', 10, 'custom_catalog');

validateDatabase() ​

validateDatabase(database): Promise<boolean>

Validate that a database exists

Parameters ​

database ​

string

Database name to validate

Returns ​

Promise<boolean>

true if database exists

Throws ​

When validation query fails

validateTable() ​

validateTable(database, table): Promise<boolean>

Validate that a table exists

Parameters ​

database ​

string

Database name

table ​

string

Table name

Returns ​

Promise<boolean>

true if table exists

Throws ​

When validation query fails

Copyright 2024-present Treasure AI