> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/engine-guide/trino.md).

# Trino

Trino is a distributed SQL query engine for analytics across data lakes, databases, and object storage. Vulcan connects to Trino with the `trino` engine adapter, federating reads across many catalogs and materialising output into a lakehouse catalog. This section is the full manual; it splits into three deployment shapes because cluster ownership changes how you connect, configure, and operate.

Use the [Connect engine → Trino](https://v2.dataos.info/build/productize/connect-engine/trino) Build pages for the quick connection steps.

{% hint style="info" %}
Engine adapter type: `trino`. Model dialect: `trino`. VDE is not supported on Trino: always set `vde: false`. Identifier casing is lowercase (Trino lowercases unquoted names), the opposite of Snowflake and Spark. Tested Vulcan image: `tmdcio/vulcan-trino:0.228.1.24-beta1`.
{% endhint %}

## When to use Trino

Choose Trino when you need to query across multiple source systems (an Iceberg lakehouse, Postgres, Snowflake, and more) in one engine, and to materialise the result into a lakehouse catalog. Trino is a massively parallel processing (MPP) query engine, not a storage engine: persisted tables live in external systems, and performance is shaped by source latency, federation width (how many catalogs a query spans), and shuffle/exchange size, not by row count alone.

### Supported model kinds

`VIEW`, `FULL`, `SEED`, `INCREMENTAL_BY_TIME_RANGE`, and `INCREMENTAL_BY_PARTITION`. Trino is GA for federated read plus Iceberg materialisation. Validated federated sources are the Iceberg lakehouse, Postgres, and Snowflake; BigQuery, Databricks, Delta Lake, and MSSQL/MySQL connector templates exist but are not validated, so test them on your own depot before relying on them.

## The three deployment shapes

| Shape             | Page                                                                    | Cluster ownership                                                                   | Connect via                                                        |
| ----------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Dedicated cluster | [dedicated-trino.md](/references/engine-guide/trino/dedicated-trino.md) | Vulcan provisions and owns a coordinator and workers, one cluster per data product. | A `vulcan-dg-trino` resource with a `spec.trino` block.            |
| Minerva (shared)  | [minerva.md](/references/engine-guide/trino/minerva.md)                 | A shared, DataOS-managed Minerva (Trino) cluster, not owned by the data product.    | A `vulcan` resource pointing at the Minerva endpoint via a secret. |
| External cluster  | [external-trino.md](/references/engine-guide/trino/external-trino.md)   | A pre-existing Trino, Starburst, or self-hosted cluster outside DataOS.             | A `vulcan` resource pointing at the cluster's host and port.       |

All three use the same model, semantic, metric, and data-quality code. Only `config.yaml`, the deploy resource, and the connection secrets differ. Minerva and external Trino are both "external" from Vulcan's point of view (Vulcan does not manage the cluster); they are split into separate pages because Minerva has DataOS-specific password generation and secret projection.

## Common rules across all three shapes

These hold no matter which shape you deploy.

* Use `type: trino` in the gateway connection and `dialect: trino` in `model_defaults`.
* Use `vde: false`. Trino does not support `vde: true`; validation rejects it.
* Identifiers are lowercase. Quote with `"` only when a name collides with a reserved word. Use fully qualified three-part names (`catalog.schema.table`) for all model names, source reads, and DQ `depends_on` references.
* Prefer `TIMESTAMP(6)` for Iceberg-backed timestamp columns; declare the precision your catalog expects.
* Use a half-open window (`>= @start_dt AND < @end_dt`), not `BETWEEN`, on time-range incrementals, to avoid reprocessing or duplicating rows at the window boundary.
* Store passwords and tokens in environment variables locally and in DataOS secrets when deploying.
* Declare cross-catalog sources the linter cannot resolve in `external_models.yaml`, or it throws `Table not found` and lineage stops at the model boundary.
* Add the deploy manifest filename to `ignore_patterns` in `config.yaml` so Vulcan never parses it as a model.

## Models, semantics, and federation

SQL models compile to Trino SQL. The coordinator plans queries; workers execute them. Materialised output (`FULL` and incremental kinds) lands in the default catalog, while source reads can federate across every mounted catalog. The federated `VIEW` is the Trino superpower: a staging view can read directly from a remote source catalog.

```sql
MODEL (
  name lakehouse.staging.customers,
  kind VIEW,
  grain customer_id,
  columns (customer_id BIGINT, name VARCHAR, email VARCHAR, region VARCHAR)
);
SELECT customer_id, name, email, region
FROM abfsslhdepot.azure_spark_dp_bronze.customers;   -- reads the Iceberg source catalog
```

Declare explicit joins in semantic models; Trino broadcasts or redistributes for joins, and an unconstrained cross-catalog join is the biggest avoidable latency risk on a federated cluster. For metrics, `COUNT(DISTINCT …)` often requires distributed aggregation and can be one of the most expensive operations on large, high-cardinality data; pre-aggregate into a mart, or use `approx_distinct` where an exact count is not required (it is approximate and introduces estimation error).

## Data quality

Vulcan quality runs as Trino SQL against the catalogs: model `assertions` and `profiles` during materialisation, standalone `AUDIT(...)` after materialisation, and `kind: dq` rules after the run or on a schedule. Use fully qualified `catalog.schema.table` names in all DQ and audit SQL, keep `failed rows` queries narrow with a `samples limit`, and profile only operationally useful columns (profiling high-cardinality columns on remote Postgres or Snowflake catalogs pushes load onto the source).

## Endpoints

The Trino stack serves REST, GraphQL, and MySQL-wire endpoints. Endpoint queries push execution to Trino, so size the API track separately from the cluster but remember that expensive semantic queries still consume cluster compute. Keep API memory at or above 2 GiB for large result sets; the MySQL-wire sidecar enforces `VULCAN_API_QUERY_TIMEOUT` (default 300 seconds).

## Metadata scanning

DataOS scans the depots behind the Trino catalogs (not Trino itself) plus Vulcan's parsed model graph for lineage. Grant the scanner principal `purpose: scan` on each source depot. The scanner runs every 6 to 12 hours; lineage from model runs is available immediately after a successful `vulcan run`.

## Related

* [dedicated-trino.md](/references/engine-guide/trino/dedicated-trino.md) for the `vulcan-dg-trino` managed cluster.
* [minerva.md](/references/engine-guide/trino/minerva.md) for the shared DataOS Minerva cluster.
* [external-trino.md](/references/engine-guide/trino/external-trino.md) for bring-your-own Trino, Starburst, or self-hosted.
* [Engine guide overview](/references/engine-guide/engine-guide.md) for the cross-engine rules.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/references/engine-guide/trino.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.