# trinodb/trino architecture

> Architecture diagram of the GitHub repository trinodb/trino, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trinodb/trino
- Repository: https://github.com/trinodb/trino
- Video tour (about a minute): https://gitdiagram.com/trinodb/trino/video

## Overview

Trino is a distributed SQL analytics engine. A client submits SQL; the coordinator manages query execution, plans work into stages and schedules tasks across workers, which execute connector-backed reads or writes and return results. The graph also preserves catalog/connector access, query-session configuration, and execution statistics as distinct responsibilities. The README confirms CLI use and a broad plugin model; unsampled runtime branches are represented only where repository paths and documented capabilities support them. Source excerpts show scheduler and query-manager responsibilities, but do not expose the complete dispatch and result protocol.

Main entry points: [`core/trino-main/src/main/java/io/trino/execution/QueryManager.java`](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/execution/QueryManager.java) (Query manager), [`core/trino-main/src/main/java/io/trino/execution/scheduler/PipelinedQueryScheduler.java`](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/execution/scheduler/PipelinedQueryScheduler.java) (Stage scheduler), [`client/trino-client/src/main/java/io/trino/client/StatementClientV1.java`](https://github.com/trinodb/trino/blob/master/client/trino-client/src/main/java/io/trino/client/StatementClientV1.java) (Client protocol), [`core/trino-main/src/main/java/io/trino/connector/ConnectorServices.java`](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/connector/ConnectorServices.java) (Connector plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client access"]
  node_cli["Command-line client<br/>[Trino.java]"]
  node_jdbc["JDBC driver<br/>[TrinoDriver.java]"]
  node_clientproto["Client protocol"]
  node_querydata["Query results<br/>[QueryResults.java]"]
end

subgraph group_coordination["Query coordination"]
  node_server["Trino server"]
  node_session["Query session<br/>[Session.java]"]
  node_querymgr["Query manager<br/>[QueryManager.java]"]
  node_planner["SQL planning"]
  node_scheduler["Stage scheduler"]
end

subgraph group_execution["Distributed execution"]
  node_worker["Worker tasks"]
  node_pipelines["Operator pipelines"]
  node_exchange["Distributed exchange"]
end

subgraph group_connectors["Data access"]
  node_catalogs["Catalog management"]
  node_connectors["Connector plugins"]
  node_bigquery["BigQuery connector"]
  node_metastore["Table metadata<br/>[Storage.java]"]
end

subgraph group_runtime["Runtime services"]
  node_stats["Execution statistics"]
  node_spi["Connector type system<br/>[Type.java]"]
end

node_user(("SQL user"))
node_datasources[("External data sources")]

node_user -->|"submits SQL"| node_cli
node_user -->|"submits SQL"| node_jdbc
node_cli -.->|"runs queries"| node_clientproto
node_jdbc -.->|"uses protocol"| node_clientproto
node_clientproto -.->|"sends requests"| node_server
node_server -.->|"accepts queries"| node_querymgr
node_querymgr -->|"uses context"| node_session
node_querymgr -.->|"creates execution"| node_planner
node_querymgr -.->|"manages execution"| node_scheduler
node_scheduler -->|"schedules tasks"| node_worker
node_worker -.->|"runs operators"| node_pipelines
node_pipelines -->|"aggregates metrics"| node_stats
node_scheduler -.->|"coordinates exchange"| node_exchange
node_scheduler -.->|"resolves catalogs"| node_catalogs
node_catalogs -.->|"loads services"| node_connectors
node_connectors -.->|"includes connector"| node_bigquery
node_bigquery -.->|"accesses data"| node_datasources
node_connectors -.->|"uses metadata"| node_metastore
node_bigquery -->|"maps types"| node_spi
node_server -.->|"returns results"| node_querydata
node_querydata -.->|"decodes response"| node_clientproto

click node_cli "https://github.com/trinodb/trino/blob/master/client/trino-cli/src/main/java/io/trino/cli/Trino.java"
click node_jdbc "https://github.com/trinodb/trino/blob/master/client/trino-jdbc/src/main/java/io/trino/jdbc/TrinoDriver.java"
click node_clientproto "https://github.com/trinodb/trino/blob/master/client/trino-client/src/main/java/io/trino/client/StatementClientV1.java"
click node_session "https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/Session.java"
click node_querymgr "https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/execution/QueryManager.java"
click node_planner "https://github.com/trinodb/trino/tree/master/core/trino-main/src/main/java/io/trino/sql/planner"
click node_scheduler "https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/execution/scheduler/PipelinedQueryScheduler.java"
click node_worker "https://github.com/trinodb/trino/tree/master/core/trino-main/src/main/java/io/trino/execution"
click node_pipelines "https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/operator/PipelineContext.java"
click node_exchange "https://github.com/trinodb/trino/blob/master/plugin/trino-exchange-filesystem/src/main/java/io/trino/plugin/exchange/filesystem/ExchangeStorageWriter.java"
click node_catalogs "https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/connector/CoordinatorDynamicCatalogManager.java"
click node_connectors "https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/connector/ConnectorServices.java"
click node_bigquery "https://github.com/trinodb/trino/blob/master/plugin/trino-bigquery/src/main/java/io/trino/plugin/bigquery/BigQueryClient.java"
click node_metastore "https://github.com/trinodb/trino/blob/master/lib/trino-metastore/src/main/java/io/trino/metastore/Storage.java"
click node_querydata "https://github.com/trinodb/trino/blob/master/client/trino-client/src/main/java/io/trino/client/QueryResults.java"
click node_stats "https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/operator/PipelineContext.java"
click node_spi "https://github.com/trinodb/trino/blob/master/core/trino-spi/src/main/java/io/trino/spi/type/Type.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_jdbc,node_clientproto,node_querydata,node_user toneBlue
class node_server,node_session,node_querymgr,node_planner,node_scheduler,node_datasources toneAmber
class node_worker,node_pipelines,node_exchange toneMint
class node_catalogs,node_connectors,node_bigquery,node_metastore toneRose
class node_stats,node_spi toneIndigo
```

## Components

### Client access

- [Command-line client](https://github.com/trinodb/trino/blob/master/client/trino-cli/src/main/java/io/trino/cli/Trino.java): `client/trino-cli/src/main/java/io/trino/cli/Trino.java`
- [JDBC driver](https://github.com/trinodb/trino/blob/master/client/trino-jdbc/src/main/java/io/trino/jdbc/TrinoDriver.java): `client/trino-jdbc/src/main/java/io/trino/jdbc/TrinoDriver.java`
- [Client protocol](https://github.com/trinodb/trino/blob/master/client/trino-client/src/main/java/io/trino/client/StatementClientV1.java): `client/trino-client/src/main/java/io/trino/client/StatementClientV1.java`
- [Query results](https://github.com/trinodb/trino/blob/master/client/trino-client/src/main/java/io/trino/client/QueryResults.java): `client/trino-client/src/main/java/io/trino/client/QueryResults.java`

### Query coordination

- **Trino server**
- [Query session](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/Session.java): `core/trino-main/src/main/java/io/trino/Session.java`
- [Query manager](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/execution/QueryManager.java): `core/trino-main/src/main/java/io/trino/execution/QueryManager.java`
- [SQL planning](https://github.com/trinodb/trino/tree/master/core/trino-main/src/main/java/io/trino/sql/planner): `core/trino-main/src/main/java/io/trino/sql/planner`
- [Stage scheduler](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/execution/scheduler/PipelinedQueryScheduler.java): `core/trino-main/src/main/java/io/trino/execution/scheduler/PipelinedQueryScheduler.java`

### Distributed execution

- [Worker tasks](https://github.com/trinodb/trino/tree/master/core/trino-main/src/main/java/io/trino/execution): `core/trino-main/src/main/java/io/trino/execution`
- [Operator pipelines](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/operator/PipelineContext.java): `core/trino-main/src/main/java/io/trino/operator/PipelineContext.java`
- [Distributed exchange](https://github.com/trinodb/trino/blob/master/plugin/trino-exchange-filesystem/src/main/java/io/trino/plugin/exchange/filesystem/ExchangeStorageWriter.java): `plugin/trino-exchange-filesystem/src/main/java/io/trino/plugin/exchange/filesystem/ExchangeStorageWriter.java`

### Data access

- [Catalog management](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/connector/CoordinatorDynamicCatalogManager.java): `core/trino-main/src/main/java/io/trino/connector/CoordinatorDynamicCatalogManager.java`
- [Connector plugins](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/connector/ConnectorServices.java): `core/trino-main/src/main/java/io/trino/connector/ConnectorServices.java`
- [BigQuery connector](https://github.com/trinodb/trino/blob/master/plugin/trino-bigquery/src/main/java/io/trino/plugin/bigquery/BigQueryClient.java): `plugin/trino-bigquery/src/main/java/io/trino/plugin/bigquery/BigQueryClient.java`
- [Table metadata](https://github.com/trinodb/trino/blob/master/lib/trino-metastore/src/main/java/io/trino/metastore/Storage.java): `lib/trino-metastore/src/main/java/io/trino/metastore/Storage.java`

### Runtime services

- [Execution statistics](https://github.com/trinodb/trino/blob/master/core/trino-main/src/main/java/io/trino/operator/PipelineContext.java): `core/trino-main/src/main/java/io/trino/operator/PipelineContext.java`
- [Connector type system](https://github.com/trinodb/trino/blob/master/core/trino-spi/src/main/java/io/trino/spi/type/Type.java): `core/trino-spi/src/main/java/io/trino/spi/type/Type.java`

### Other components

- **SQL user**
- **External data sources**

## Connections

- SQL user → Command-line client: submits SQL
- SQL user → JDBC driver: submits SQL
- Command-line client → Client protocol: runs queries
- JDBC driver → Client protocol: uses protocol
- Client protocol → Trino server: sends requests
- Trino server → Query manager: accepts queries
- Query manager → Query session: uses context (evidence: `core/trino-main/src/main/java/io/trino/execution/QueryManager.java`)
- Query manager → SQL planning: creates execution (evidence: `core/trino-main/src/main/java/io/trino/execution/QueryManager.java`)
- Query manager → Stage scheduler: manages execution
- Stage scheduler → Worker tasks: schedules tasks (evidence: `core/trino-main/src/main/java/io/trino/execution/scheduler/PipelinedQueryScheduler.java`)
- Worker tasks → Operator pipelines: runs operators (evidence: `core/trino-main/src/main/java/io/trino/operator/PipelineContext.java`)
- Operator pipelines → Execution statistics: aggregates metrics (evidence: `core/trino-main/src/main/java/io/trino/operator/PipelineContext.java`)
- Stage scheduler → Distributed exchange: coordinates exchange
- Stage scheduler → Catalog management: resolves catalogs
- Catalog management → Connector plugins: loads services
- Connector plugins → BigQuery connector: includes connector
- BigQuery connector → External data sources: accesses data
- Connector plugins → Table metadata: uses metadata
- BigQuery connector → Connector type system: maps types (evidence: `plugin/trino-bigquery/src/main/java/io/trino/plugin/bigquery/BigQueryClient.java`)
- Trino server → Query results: returns results
- Query results → Client protocol: decodes response
