Trino Platform

Trino (formerly PrestoSQL) is a distributed SQL query engine designed for interactive analytics against data sources of all sizes. It’s widely used by companies like Netflix, Airbnb, and Lyft for data lake analytics.

Features

• Distributed execution - Query data across multiple workers
• Federated queries - Join data from multiple sources (S3, Hive, Iceberg, Delta)
• Session properties - Fine-grained query optimization
• Table formats - Support for Iceberg, Delta Lake, and Hive
• Starburst compatible - Works with Starburst Enterprise

Important Notes

Trino vs PrestoDB: This adapter supports Trino only, NOT PrestoDB (Meta’s fork). While they share ancestry, they have diverged significantly since 2019:

• Different Python drivers (trino vs presto-python-client)
• Different HTTP headers (X-Trino-* vs X-Presto-*)
• Diverging SQL syntax and functions

For PrestoDB, use the Presto adapter. For AWS managed Trino, use the Athena adapter.

Installation

pip install trino

pip install "trino[kerberos]"

The first command installs the Trino Python driver. The second adds authentication support.

Configuration

Connection Settings

The CLI reads connection settings from the trino section of ~/.benchbox/credentials.yaml. Values written as ${VAR} are read from the environment:

trino:
  host: trino-coordinator.example.com
  port: 8080
  username: analyst
  password: ${TRINO_PASSWORD}
  schema: benchmark

Setting	Default	Description
host	localhost	Trino coordinator hostname
port	8080	Trino coordinator port
username	trino	Trino user for query attribution
password	(none)	Password for LDAP/basic auth
schema	(from benchmark and scale)	Schema for benchmark tables
http_scheme	http, or https when a password is set	Connection scheme
verify_ssl	true	Verify SSL certificates

CLI Options

benchbox run --platform trino --benchmark tpch --scale 1.0 \
  --platform-option catalog=hive

Platform Options

Option	Default	Description
catalog	(auto-discovered)	Default catalog (hive, iceberg, delta, memory)
staging_root	(none)	S3/GCS path for data staging
table_format	memory	Table format (memory, hive, iceberg, delta)
source_catalog	(none)	Source catalog for external data loading
driver_version	(latest)	Pin the trino package version (e.g. 0.336.0)
driver_auto_install	false	Auto-install the requested driver version via uv if missing

Testing a Specific Trino Connector Version

benchbox run --platform trino --benchmark tpch \
  --platform-option driver_version=0.336.0 \
  --platform-option driver_auto_install=true \
  --platform-option catalog=hive

The driver package for Trino is trino.

See Driver Version Management for the full guide, including why uv run may revert a manually-installed version and how to work around it.

Usage Examples

Basic Benchmark Run

With host set in the credentials file:

benchbox run --platform trino --benchmark tpch --scale 1.0 \
  --platform-option catalog=hive

Iceberg Tables

benchbox run --platform trino --benchmark tpch --scale 1.0 \
  --platform-option catalog=iceberg \
  --platform-option table_format=iceberg \
  --platform-option staging_root=s3://bucket/staging/

Python API

from benchbox import TPCH
from benchbox.platforms.trino import TrinoAdapter

adapter = TrinoAdapter(
    host="trino-coordinator.example.com",
    port=8080,
    catalog="hive",
    schema="benchmark",
    username="analyst",
)

benchmark = TPCH(scale_factor=1.0)
adapter.load_benchmark(benchmark)
results = adapter.run_benchmark(benchmark)

Deployment Modes

Local Development (Memory Catalog)

docker run -d -p 8080:8080 --name trino trinodb/trino

benchbox run --platform trino --benchmark tpch --scale 0.1 \
  --platform-option catalog=memory

The first command starts Trino locally in Docker. The second runs the benchmark with the memory catalog.

If you installed Trino via Homebrew, you can start the service with:

brew install trino
brew services start trino
trino-server run

Use either brew services start trino or trino-server run to start it manually.

BenchBox automatically detects when localhost:8080 refuses connections and emits a friendly error explaining that Trino needs to be started (including the brew services start trino reminder) or that you should point BenchBox at a remote Trino cluster by setting host and port in the credentials file.

Production (Hive/Iceberg)

benchbox run --platform trino --benchmark tpch --scale 10.0 \
  --platform-option catalog=hive \
  --platform-option staging_root=s3://data-lake/staging/

Starburst Enterprise

The Trino adapter is fully compatible with Starburst Enterprise. Point the credentials file at the cluster:

trino:
  host: starburst.example.com
  port: 443
  username: analyst
  password: ${STARBURST_PASSWORD}
  http_scheme: https
  verify_ssl: true

Then run benchbox run --platform trino as usual.

Performance Tuning

Session Properties

Common session properties for optimization:

adapter = TrinoAdapter(
    host="trino.example.com",
    session_properties={
        "query_max_memory": "8GB",
        "query_max_memory_per_node": "2GB",
        "join_distribution_type": "AUTOMATIC",
    }
)

Data Format Recommendations

• Parquet: Best compression and performance for analytics
• ORC: Good alternative with predicate pushdown
• Iceberg: Recommended for updates and time-travel

Query Plan Analysis

benchbox run --platform trino --benchmark tpch \
  --capture-plans

Trino provides detailed EXPLAIN output including:

• Distributed query plan fragments
• Data exchange patterns
• Join strategies
• Partition pruning

Limitations

• No local execution - Requires Trino cluster
• Infrastructure overhead - Coordinator and workers needed
• Cold start - First queries may be slower

Troubleshooting

Connection Timeout

curl http://trino-host:8080/v1/info

This verifies that Trino is accessible.

Catalog Not Found

trino --server trino-host:8080 --execute "SHOW CATALOGS"

This lists the available catalogs.

Memory Errors

SELECT * FROM system.runtime.queries WHERE state = 'RUNNING';

This checks memory usage of the running queries.

Related Documentation

• Presto Platform - For PrestoDB (Meta fork)
• Athena Platform - AWS managed Trino service
• Spark Platform - Alternative distributed engine