# Trino Trino

Source: https://userguide.qualytics.io/source-datastore/datastore/jdbc/trino/

Adding and configuring a Trino connection within Qualytics empowers the platform to build a symbolic link with your schema to perform operations like data discovery, visualization, reporting, syncing, profiling, scanning, anomaly surveillance, and more.

This documentation provides a step-by-step guide on adding Trino as a source datastore in Qualytics. It covers the entire process, from initial connection setup to testing and finalizing the configuration.

By following these instructions, enterprises can ensure their Trino environment is properly connected with Qualytics, unlocking the platform’s potential to help you proactively manage your full data quality lifecycle.

![trino-connection-form](https://userguide.qualytics.io/assets/source-datastores/datastore/jdbc/trino/overview/trino-connection-form.png)

Let’s get started 🚀

## Trino Setup Guide

Qualytics connects to Trino through the **Trino JDBC driver**. It uses standard SQL queries for data profiling and scanning. Since Trino is a distributed query engine, permissions are determined by the underlying data source (connector) configured in the Trino catalog (e.g., Hive, Delta Lake, Iceberg, RDBMS).

### Minimum Trino Permissions (Source Datastore)

| Permission | Purpose |
| --- | --- |
| `SELECT` on target tables | Read data from tables for profiling and scanning |
| Access to the Trino catalog | Browse available schemas and tables |
| Access to the Trino schema | Browse available tables and columns |

The actual permissions depend on the Trino security model configured for your deployment:

| Security Model | How Permissions Are Managed |
| --- | --- |
| **No security (default)** | All users have full read access to all catalogs and schemas |
| **File-based access control** | Permissions are defined in `rules.json`; ensure the Qualytics user has `SELECT` on the target catalog and schema |
| **Connector-level security** | Permissions are delegated to the underlying data source; ensure the Qualytics user has read access at the source level |

### Example: File-Based Access Control Configuration

If your Trino deployment uses file-based access control (`rules.json`), ensure the Qualytics user has appropriate access to the target catalog and schema:

```json
{
  "catalogs": [
    {
      "user": "qualytics_read",
      "catalog": "<catalog_name>",
      "allow": "read-only"
    }
  ]
}
```

> **Note**
>
> Trino permissions are managed through the underlying connector's security model (e.g., Hive, Delta Lake, Iceberg). Ensure the Trino user has the appropriate access to the backing data source.

### Troubleshooting Common Errors

| Error | Likely Cause | Fix |
| --- | --- | --- |
| `Access Denied: Cannot select from table` | The user lacks `SELECT` on the target table in the Trino access control rules or the underlying connector | Add `SELECT` permission for the user in `rules.json` or grant access in the underlying data source |
| `Catalog does not exist` | The catalog name in the connection form does not match a configured Trino catalog | Verify available catalogs with `SHOW CATALOGS` in Trino |
| `Schema does not exist` | The schema name does not exist in the specified catalog | Verify available schemas with `SHOW SCHEMAS FROM <catalog>` |
| `Connection refused` | The Trino coordinator is not reachable or the port (default 8080) is incorrect | Verify the host, port, and that the Trino coordinator is running |
| `Authentication failed` | Incorrect username or password, or the Trino server requires a different authentication method | Verify credentials and check if the Trino server uses LDAP, Kerberos, or password authentication |

### Detailed Troubleshooting Notes

#### Authentication Errors

The error `Authentication failed` indicates that the credentials are incorrect or the authentication method does not match the server configuration.

Common causes:

- **Incorrect password**: the password does not match the one configured in the Trino server.
- **Wrong authentication method**: the Trino server uses LDAP or Kerberos, but the connection form provides basic username/password.
- **HTTPS required**: the Trino coordinator requires HTTPS connections, but the connection is using HTTP.

> **Note**
>
> Trino authentication is configured at the coordinator level. Check the `password-authenticator.properties` file for the configured authentication method.

#### Permission Errors

The error `Access Denied: Cannot select from table` or `Access Denied: Cannot create table` means the user authenticated successfully but lacks access to the target resource.

Common causes:

- **File-based access control**: the `rules.json` file does not grant the required permissions to the Qualytics user.
- **Connector-level security**: the underlying data source does not grant the necessary access.

#### Connection Errors

The error `Connection refused` or `Catalog does not exist` indicates a connectivity or configuration issue.

Common causes:

- **Coordinator not reachable**: the Trino coordinator host or port (default 8080) is incorrect.
- **Wrong catalog name**: the catalog name in the connection form does not match a configured Trino catalog.
- **Coordinator not running**: the Trino coordinator process is not started.

> **Tip**
>
> Start by confirming credentials are valid (authentication errors), then verify access control rules (permission errors), and finally check coordinator connectivity (connection errors).

## Add a Source Datastore

A source datastore is a storage location Qualytics connects to so it can profile, scan, and monitor data. Adding Trino as a source lets Qualytics query it through the Trino JDBC driver and run quality operations on the tables it discovers.

Before you start, review the [Minimum Trino Permissions](https://userguide.qualytics.io/source-datastore/datastore/jdbc/trino/#minimum-trino-permissions-source-datastore) the connecting user needs.

> **Warning: The destination lives on another connector**
>
> Qualytics cannot write to Trino, so a Trino datastore cannot be used as an enrichment datastore. Create one on a supported connector, then link it as the Trino datastore's destination. See [Supported Connectors](https://userguide.qualytics.io/source-datastore/enrichment-datastore/supported-connectors/) for the list.

### Field reference

The **Add Datastore** page shows the sections below when Trino is selected. When reusing an existing connection, the **Connection Properties** and **Secrets Management** sections come already filled in and read-only: Qualytics has already validated those credentials, so you fill in only the **Location** and the **General** fields. To change a saved connection's credentials, edit the connection through the [Manage Connections](https://userguide.qualytics.io/settings/connections/manage-connections/) page; edits there apply to every datastore that reuses the connection.

#### Connection Properties

These fields define the Trino coordinator Qualytics connects to and the account it connects with. They belong to the connection: when reusing an existing connection, they come already filled in and read-only.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Connection Name** | Yes | Text | A label for the saved connection (e.g., `acme_trino_reporting`), so other datastores can reuse it later. |
| **Host** | Yes | Text | The hostname or address of the Trino coordinator. |
| **Port** | Yes | Number | The port the coordinator accepts connections on. Defaults to `8080`. |
| **User** | Yes | Text | The Trino user Qualytics connects as. Trino passes it to the underlying catalog for authorization. |
| **Password** | No | Text | The password for that user. Leave it empty on a Trino deployment that does not authenticate. |
| **Max Parallelization** | No | Number | Caps how many queries Qualytics runs at the same time against a datastore reached through this connection, from 1 to 100. Leave it empty for no explicit limit. The cap applies per datastore, so datastores sharing this connection each get their own allowance. Sits in the collapsed **Advanced** section of the form. See [Max Parallelization](https://userguide.qualytics.io/source-datastore/datastore/connection/how-it-works/#max-parallelization). |

#### Secrets Management

This group is optional: use it only if you want Qualytics to pull credentials from a secrets manager instead of typing them into the form. Turn on **HashiCorp Vault** to show the fields below. Despite the label, any secrets manager that exposes a compatible REST API works, not only HashiCorp Vault; see [HashiCorp Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/introduction/). It also belongs to the connection: read-only when reusing an existing connection.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Login URL** | Yes | Text | The full URL of the login endpoint (e.g., `https://vault.example.com/v1/auth/approle/login`). With Vault namespaces, add the namespace after `/v1/`, as in `/v1/<namespace>/auth/approle/login`. |
| **Credentials Payload** | Yes | Text | A JSON body containing the credentials Vault expects (e.g., `{"role_id":"...","secret_id":"..."}`). |
| **Token JSONPath** | Yes | Text | The JSONPath that extracts the client token from Vault's response. Defaults to `$.auth.client_token`. |
| **Secret URL** | Yes | Text | The full URL of the secret, including `https://` and the host (e.g., `https://vault.example.com/v1/secret/data/trino`). With Vault namespaces, add the namespace after `/v1/`. |
| **Token Header Name** | Yes | Text | The HTTP header name used to send the token. Defaults to `X-Vault-Token`. |
| **Data JSONPath** | Yes | Text | The JSONPath that extracts the key/value pairs from Vault's response. Use `$.data.data` for a KV version 2 secret (its API path contains `/data/`) and `$.data` for KV version 1 or the database secrets engine. The form pre-fills `$.data`. |

> **Note**
>
> Reference a key from the secret in any **Connection Properties** or **Authentication** field with `${key}`, for example `${password}`. Write it with braces (`${key}`, never `$.key`) and match the key name's case. Qualytics resolves it each time the connection is opened, so a changed value takes effect on the next connection. Setup steps, the namespace rule, and a troubleshooting page are on the [HashiCorp Vault](https://userguide.qualytics.io/source-datastore/datastore/connection/hashicorp-vault/deep-dive/introduction/) pages.

#### Location

Pick the catalog and the schema or schemas Qualytics should read from, and choose whether the connection is encrypted. You fill these in on both flows.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Catalog** | Yes | Option | The Trino catalog to read from, which is the underlying data source Trino queries (e.g., `hive`). Click the refresh icon to load the catalogs the user can see. |
| **Schema** | Yes | Option | One or more schemas inside the selected catalog. Each schema you pick becomes its own Qualytics datastore. Defaults to `default`. |
| **Use SSL** | No | Checkbox | Connect to the coordinator over TLS. Selected by default. Clear it only when the coordinator does not serve TLS, in which case the connection is made without encryption. |

> **Note: One datastore per schema**
>
> Selecting more than one schema creates one source datastore per schema, named from the **Name Template**. See [Multi-Schema Source Datastore Creation](https://userguide.qualytics.io/source-datastore/datastore/multi-schema/overview/) for details.

> **Note: Where the permissions come from**
>
> Trino is a query engine, so what you can see in a catalog depends on the data source behind it. A catalog or schema missing from the list usually means the underlying source denies access to it.

#### General

Common fields for every source datastore, shown below the **Location** section. You fill these in on both flows.

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Name Template** | No | Text | Defines the naming pattern for each source datastore being created. Use `{{schema}}` as a placeholder that gets replaced with the actual schema name (e.g., `trino_{{schema}}` becomes `trino_sales`). Left empty, the datastore is named from the connection name and the schema. |
| **Group** | No | Option | Organizes your datastores under a shared group in the navigation tree. Select an existing group or create a new one with the **Add New Group** toggle. |
| **Teams** | Yes | Option | Select one or more teams to associate with this source datastore. |
| **Initiate Sync** | No | Checkbox | Automatically sync the datastore to detect containers and fields after creation. |

Below the form, an information banner lists the **Public addresses** and **Private addresses** your datastore connections originate from. Allow the ones that match your network setup through your security groups or firewall rules; see [How Connections Work](https://userguide.qualytics.io/source-datastore/datastore/connection/how-it-works/#finding-the-addresses-to-allow) for where the addresses come from.

### Steps

There are two ways to set up the connection: reuse a connection you already saved (**Existing Connection**) or create a new one from scratch (**New Connection**). The tabs below walk through each option; pick the one you want to follow. Each field is described in the [Field reference](https://userguide.qualytics.io/source-datastore/datastore/jdbc/trino/#source-field-reference) above.

**Tab: New Connection**

**Step 1**: Navigate to the **Datastores** page.

**Step 2**: Click the **Add**  button at the top-right corner and choose **Source** .

**Step 3**: The **Add Datastore** page opens.

**Step 4**: Select **New Connection** next to the **Search**  field.

**Step 5**: Select **Trino** from the connector grid. Use the search field to filter connectors by name.

**Step 6**: Fill in the **Connection Properties**: the **Connection Name**, **Host**, **Port**, and **User**, plus the **Password** if your deployment requires one.

**Step 7**: Optionally, expand **Secrets Management** to retrieve credentials from a secrets manager.

**Step 8**: Fill in the **Location** fields (**Catalog**, **Schema**, and **Use SSL**) and the **General** fields.

**Step 9**: Click **Test connection**. A success message confirms that the connection has been verified.

> **Info**
>
> The **Finish** and **Next** buttons stay disabled until the connection test passes on the current values. If the test fails, see [Troubleshooting Common Errors](https://userguide.qualytics.io/source-datastore/datastore/jdbc/trino/#troubleshooting-common-errors).

**Step 10**: Click **Finish** to create the datastore.

> **Tip**
>
> To link a destination so Qualytics can write anomalies and metadata from the first operation, click **Next** instead of **Finish**. It has to live on a connector other than Trino; see [Link Enrichment on Datastore Creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/).

**Step 11**: A success dialog confirms that your datastore has been added. Click **Go to your datastore** to open its page.

**Tab: Existing Connection**

**Step 1**: Navigate to the **Datastores** page.

**Step 2**: Click the **Add**  button at the top-right corner and choose **Source** .

**Step 3**: The **Add Datastore** page opens.

**Step 4**: Select **Existing Connection** next to the **Search**  field.

**Step 5**: Select the saved Trino connection from the grid. Use the search field to filter connections by name. The **Connection Properties** and **Secrets Management** sections come already filled in and read-only.

> **Tip: Start a new connection from this one**
>
> To use the selected connection as a starting point for a brand-new connection instead, click the **Duplicate as a new connection**  button on the selected connection. The form switches to **New Connection** mode with the connection's settings already filled in for you to adjust.

**Step 6**: Fill in the **Location** fields (**Catalog**, **Schema**, and **Use SSL**) and the **General** fields. These are the only fields left to fill in.

**Step 7**: Click **Test connection**. A success message confirms that the connection has been verified.

> **Info**
>
> The **Finish** and **Next** buttons stay disabled until the connection test passes on the current values. If the test fails, see [Troubleshooting Common Errors](https://userguide.qualytics.io/source-datastore/datastore/jdbc/trino/#troubleshooting-common-errors).

**Step 8**: Click **Finish** to create the datastore.

> **Tip**
>
> To link a destination so Qualytics can write anomalies and metadata from the first operation, click **Next** instead of **Finish**. It has to live on a connector other than Trino; see [Link Enrichment on Datastore Creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/).

**Step 9**: A success dialog confirms that your datastore has been added. Click **Go to your datastore** to open its page.

## API Payload Examples

### Creating a Datastore

This section provides a sample payload for creating a datastore. Replace the placeholder values with actual data relevant to your setup.

#### Endpoint (Post)

`/api/datastores` *(post)*

**Tab: Creating a datastore with a new connection**

```json
    {
        "name": "your_datastore_name",
        "teams": ["Public"],
        "database": "trino_database",
        "schema": "trino_schema",
        "enrichment_only": false,
        "trigger_sync": true,
        "connection": {
            "name": "your_connection_name",
            "type": "trino",
            "host": "trino_host",
            "port": 8080,
            "username": "trino_username",
            "password": "trino_password"
        }
    }
```

**Tab: Creating a datastore with an existing connection**

```json
    {
        "name": "your_datastore_name",
        "teams": ["Public"],
        "database": "trino_database",
        "schema": "trino_schema",
        "enrichment_only": false,
        "trigger_sync": true,
        "connection_id": 123
    }
```

**Tab: Create a Source Datastore using the CLI**

```bash
# Step 1: Create a Connection
qualytics connections create \
    --type trino \
    --name "your_connection_name" \
    --host ${TRINO_HOST} \
    --port 8080 \
    --username ${TRINO_USER} \
    --password ${TRINO_PASSWORD}

# Step 2: Create a Source Datastore
qualytics datastores create \
    --name "your_datastore_name" \
    --connection-name "your_connection_name" \
    --database your_catalog \
    --schema default
```

> **Note: Use SSL**
>
> The payloads above leave **Use SSL** at its default, so the connection is encrypted. To connect
> to a coordinator that does not serve TLS, send `ssl` as `"false"` under the connection's
> `parameters`:
>
> ```json
> {
>     "connection": {
>         "name": "your_connection_name",
>         "type": "trino",
>         "host": "trino_host",
>         "port": 8080,
>         "username": "trino_username",
>         "password": "trino_password",
>         "parameters": {
>             "ssl": "false"
>         }
>     }
> }
> ```

### Link an Enrichment Destination

#### Endpoint (Patch)

`/api/datastores/{datastore-id}/enrichment/{enrichment-id}` *(patch)*

*Last updated: November 3, 2026.*