> 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/build/productize/connect-engine/trino.md).

# Trino

Connect Vulcan to Trino for federated SQL across catalogs and data lakes.

Trino is a distributed SQL query engine for analytics across data lakes, databases, and object storage. Use the `trino` adapter. The one decision to make here is who owns the cluster: that decides which path you follow.

| Path                                                                                               | Use when                                                                                                       |
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [Dedicated Trino](https://v2.dataos.info/build/productize/connect-engine/trino/dedicated-trino.md) | The cluster should be part of the Data Product deployment. Vulcan provisions and owns one cluster per product. |
| [Minerva](https://v2.dataos.info/build/productize/connect-engine/trino/minerva.md)                 | You connect to DataOS Minerva, a shared, DataOS-managed Trino cluster in your tenant.                          |
| [External Trino](https://v2.dataos.info/build/productize/connect-engine/trino/external-trino.md)   | You bring your own Trino-compatible endpoint, such as Starburst or self-hosted Trino.                          |

For the full Trino reference, including cluster tuning, failure modes, and local development, see the [Trino engine manual](https://v2.dataos.info/references/engine-guide/trino-1) in References.

## Rules for every Trino path

* `connection.type` is `trino`; `model_defaults.dialect` is `trino`.
* `vde: false`. Trino doesn't support `vde: true`.
* Store passwords and tokens in environment variables locally, and in DataOS Secrets when deploying.
* Use lowercase identifiers, and fully qualified three-part names (`catalog.schema.table`) for every model name, source read, and DQ `depends_on` reference. Trino lowercases unquoted names; quote with `"` only for reserved words.
* 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.
* Declare cross-catalog sources the linter can't resolve in `inputs.yaml`, or it throws `Table not found`.

Pick the path that matches cluster ownership. If the cluster already exists and Vulcan only needs to connect, use [Minerva](https://v2.dataos.info/build/productize/connect-engine/trino/minerva.md) for a shared, DataOS-managed cluster, or [External Trino](https://v2.dataos.info/build/productize/connect-engine/trino/external-trino.md) for your own. If the cluster should ship with the product, use [Dedicated Trino](https://v2.dataos.info/build/productize/connect-engine/trino/dedicated-trino.md).

## Model kinds and federation

`VIEW`, `FULL`, `SEED`, `INCREMENTAL_BY_TIME_RANGE`, and `INCREMENTAL_BY_PARTITION`. `VIEW` is Trino's superpower — a staging view can read directly from a remote source catalog, federating across every mounted catalog, while `FULL` and the incremental kinds materialize into the default catalog (the first entry in `deployment.depots` in `config.yaml` on a dedicated cluster, or whatever `TRINO_CATALOG` resolves to on Minerva/external). Python models are not supported on Trino.

{% hint style="warning" %}
Views require a catalog whose `iceberg.catalog.type` supports them — `hive_metastore`, `glue`, or `rest`. The `jdbc` and native `nessie` catalog types do **not** support views and are incompatible with Vulcan, since Vulcan's virtual layer is built from views (DataOS lakehouse depots use the REST type, so this is rarely an issue on the standard depot path). Materialized views and `SECURE` views aren't supported either — Vulcan passes `SECURE` through unchanged and Trino rejects it at apply, not at plan. Vulcan-created views run with definer semantics (the service principal's privileges, not the querying user's) — don't rely on a Trino view as an access-control boundary; use Trino access control, DataOS policies, and depot `purpose: query` credentials instead. `INCREMENTAL_BY_PARTITION` is not supported on Postgres catalogs (use `FULL` or `VIEW`), and Databricks catalogs are read-only.
{% endhint %}

## Endpoints and metadata scanning

The Trino stack serves REST, GraphQL, and MySQL-wire endpoints; queries push execution to Trino, so size the API track separately from the cluster and keep API memory at or above 2 GiB for large result sets. DataOS scans the depots behind the Trino catalogs (not Trino itself) for lineage every 6–12 hours; on a dedicated cluster, grant the scanner principal `purpose: scan` on each source depot in `deployment.depots`.

## Troubleshooting across all three shapes

| Symptom                                       | Likely cause                                                    | Fix                                                                                 |
| --------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `Table not found` for a source                | Cross-catalog source not declared, or wrong catalog name        | Add it to `inputs.yaml`; use `catalog.schema.table`.                                |
| `vulcan plan` works locally, fails in DataOS  | Depot/catalog missing or misnamed, or wrong default catalog     | Verify with `SHOW CATALOGS`; check what resolves as the default.                    |
| Catalog present but queries fail              | Missing credentials, or permission/schema issues                | `SHOW SCHEMAS FROM <catalog>;` then a 1-row `SELECT`; fix credentials and re-apply. |
| Time-range incremental reprocesses everything | Missing/wrong `time_column`, or no `@start_dt`/`@end_dt` filter | Set `time_column` and filter the source with the interval macros.                   |
| Deploy manifest parsed as a model             | `*-deploy.yaml` not ignored                                     | Add it to `ignore_patterns` in `config.yaml`.                                       |

Shape-specific failure modes (cluster formation, JVM heap, plugin loading, connector setup) live on the [Dedicated Trino](https://v2.dataos.info/build/productize/connect-engine/trino/dedicated-trino.md) and [Minerva](https://v2.dataos.info/build/productize/connect-engine/trino/minerva.md) pages, and the full reference in the [Trino engine manual](https://v2.dataos.info/references/engine-guide/trino-1).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/build/productize/connect-engine/trino.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
