Trino

What it is for

Trino runs SQL over the Iceberg tables (catalog lake) and over PostgreSQL (catalog serving). The API’s SQL workspace, views, exports and published APIs all go through it, as do notebooks.

Where it lives

Software	/opt/trino-<version> with symlink /opt/trino; Java 25 in /opt/java25 (Trino only)
Config	/etc/lake/trino/ (node.properties, jvm.config, config.properties, catalog/*.properties)
Service	trino (step 06)
Port	8080 (HTTP)
Data	/data/trino
CLI	/usr/local/bin/trino (a wrapper around the CLI jar)

It is a single node (coordinator and worker together). Heap is TRINO_HEAP in cluster.env (about 25 % of RAM on a shared box, 30-50 % when Trino has it alone).

Keep port 8080 private

Trino here has no logins of its own. The platform enforces who may read what in the API, so Trino’s port must be reachable only from the API host and the notebook host (firewall or localhost binding). Never forward it to the internet.

Catalogs

Catalog	Points at	File
lake	Iceberg tables via Nessie (main), data in s3://lake/warehouse	catalog/lake.properties
serving	PostgreSQL database serving (older publishing path)	catalog/serving.properties (step 08)
system	Trino’s own status tables	built in

Layers are schemas: lake.bronze, lake.silver, lake.gold. A dataset is lake.gold.vendor__project__folder; a view result is lake.gold.view__<name>.

Check it

systemctl is-active trino
curl -s http://127.0.0.1:8080/v1/info              # JSON with "starting": false when ready
trino --execute "SHOW CATALOGS"

The web UI (query list) is at /ui/ (through the tunnel http://localhost:18080/ui/).

How to use it

trino                                    # interactive shell
trino --execute "SHOW SCHEMAS FROM lake"
trino --execute "SHOW TABLES FROM lake.gold"
trino --execute "DESCRIBE lake.silver.chdc_health__cleaning__hospitals"
trino --execute "SELECT count(*) FROM lake.gold.chdc_health__cleaning__hospitals"

Compare the three layers of one dataset:

SELECT 'bronze' AS layer, count(*) AS n FROM lake.bronze.<name>
UNION ALL SELECT 'silver', count(*) FROM lake.silver.<name>
UNION ALL SELECT 'gold',   count(*) FROM lake.gold.<name>;

See a table’s history and files (Iceberg metadata tables):

SELECT * FROM lake.gold."<name>$snapshots" ORDER BY committed_at DESC LIMIT 5;
SELECT * FROM lake.gold."<name>$files" LIMIT 5;

(The platform’s SQL workspace blocks these $ tables for analysts; admins use the CLI.)

See and stop queries

SELECT query_id, state, "user", date_diff('second', created, now()) AS age_s, substr(query, 1, 80) AS q
FROM system.runtime.queries ORDER BY created DESC LIMIT 15;

CALL system.runtime.kill_query(query_id => '<id>', message => 'stopped by admin');

The API sets a 60-second run-time limit per query and cancels queries when a user presses Cancel, so you rarely need this.

Configure it

config.properties is minimal: coordinator=true, node-scheduler.include-coordinator=true, http-server.http.port=8080, discovery.uri=http://127.0.0.1:8080. Catalog files hold the S3 keys, so they are mode 640 root:lake. After changing cluster.env re-run step 06 (and 08 for the serving catalog).

Things that go wrong

Symptom	Likely cause
Startup takes 30-45 s	Normal; wait for /v1/info
Query exceeded ... memory	A heavy join or aggregation; add filters, LIMIT, or raise TRINO_HEAP
Table not found right after upload	The file is still processing, or not yet processed
Native-access warning from the CLI	Step 06.5 fixes the wrapper

Resource groups (hard queueing and memory per group) are not configured yet.