Introduction

What is the Trino Client? #

The @lakeql/trino-client package provides a typed HTTP client for communicating with a Trino cluster via its REST API. It handles authentication, paginated result fetching, query cancellation, and catalog metadata inspection.

Built on native fetch with zero runtime dependencies. Supports basic and bearer token authentication, automatic pagination through nextUri links, configurable retry with exponential backoff, and an async-generator streaming mode for memory-efficient processing of large result sets.

Core Capabilities #

• Query execution — Send SQL statements and collect all result pages into a single array
• Streaming — Yield rows one at a time via an async generator for large datasets
• Row transforms — Map raw row arrays to typed objects with a transform function
• Query cancellation — Cancel in-flight queries via AbortSignal or cancelQuery()
• Retry with backoff — Automatic retry on transient failures (429, 5xx, network errors)
• Metadata inspection — List schemas, tables, views, and columns for any catalog
• Authentication — Basic auth (username/password) and bearer token auth
• User impersonation — Execute queries on behalf of another user via the X-Trino-User header

Quick Example #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { TrinoClient } from "@lakeql/trino-client"

const client = new TrinoClient({
  host: "https://trino.example.com",
  port: 8443,
  auth: { type: "basic", username: "analyst", password: "secret" },
  catalog: "hive",
  schema: "sales",
})

const rows = await client.query<[string, number]>({
  sql: "SELECT region, SUM(amount) FROM orders GROUP BY region",
})

console.log(rows)
// [["us-east", 42000], ["eu-west", 31500], ...]

How It Works #

1. The client sends a POST request to /v1/statement with the SQL body
2. Trino responds with an initial result (possibly empty) and a nextUri
3. The client follows nextUri links with GET requests until no more pages remain
4. All data arrays from each page are concatenated into the final result

This pagination is handled transparently — you call query() and get back the full result set.