> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trino

> Connect Trino to ClarityQ

## Overview

ClarityQ talks to the Trino coordinator directly over its HTTP API. Any deployment that speaks the standard Trino protocol works — a self-managed cluster on Hadoop, Kubernetes, or bare metal, as well as commercial distributions such as Starburst.

Because Trino is a federation engine, one ClarityQ connection can reach every catalog your cluster exposes. A cluster that fronts a Hive/HDFS data lake alongside ClickHouse or Iceberg catalogs needs only a single connection: ClarityQ sends one SQL statement and Trino performs any cross-source work itself.

## Setup

### Step 1: Create a service account

Provision a dedicated user for ClarityQ in whatever identity system backs your cluster (LDAP, a password file, or your OIDC provider), for example `clarityq_user`.

Grant it, through your access-control layer (Ranger, Immuta, or file-based rules):

1. `SELECT` on every table ClarityQ should analyze
2. Read access to `information_schema` in those catalogs — ClarityQ discovers schemas by querying it
3. Permission to cancel **its own** queries, so aborting a question or hitting a timeout stops the work on your cluster rather than leaving it running

No write, DDL, or admin privileges are needed; ClarityQ only ever reads.

<Note>
  Cancellation uses Trino's `DELETE /v1/query/{queryId}` endpoint, which is authorised as
  "kill query owned by" — the permission an owner normally has over its own queries (in
  file-based access control, a `queries` rule granting `kill`). If that is unavailable,
  ClarityQ falls back to `CALL system.runtime.kill_query`, which additionally requires
  permission to execute that procedure. Granting either one is enough.
</Note>

### Step 2: Allow ClarityQ's IP addresses

Open your firewall / security groups so the coordinator port accepts connections from:

* 44.218.213.75
* 54.161.37.107
* 54.208.212.67

### Step 3: Fill in the connection form

| Form field              | What to enter                                                        |
| ----------------------- | -------------------------------------------------------------------- |
| Connection Name         | Any label, e.g. `Analytics Trino`                                    |
| Host                    | Coordinator hostname                                                 |
| Port                    | `443` for TLS deployments; plain-HTTP clusters commonly use `8080`   |
| User                    | The service account from Step 1 (Trino attributes every query to it) |
| Catalog                 | Default catalog for unqualified table names, e.g. `hive`             |
| Schema                  | Optional default schema                                              |
| HTTP Scheme             | `https` unless the cluster is plain HTTP on a trusted network        |
| Password / Access Token | See authentication below                                             |

## Authentication

Pick the one that matches your cluster; leave both empty for unauthenticated clusters.

* **Password** — for clusters using LDAP or password-file authentication.
* **Access Token** — a JWT issued by the OAuth2/OIDC provider protecting your coordinator (Keycloak and similar). Issue a long-lived token for the ClarityQ service account.

Provide `password` **or** `access_token`, never both. ClarityQ refuses to send either over plain HTTP — credentialed connections must use `https`, and the secret itself is stored in ClarityQ's secret manager, never in the database.

For managed offerings (e.g. Starburst Galaxy), copy the host, port, and user values from the connection panel of your cluster's console and use the password method; consult your vendor's documentation for how roles are encoded in the username.

## Per-user identity (optional)

By default every query runs as the single service account, so your cluster sees one
identity and ClarityQ's own permissions decide what users can reach.

Enable **per-user identity** and ClarityQ instead runs each query as the person asking
it: the query is attributed to their username, and your access-control layer — Ranger,
Immuta, or file-based rules — applies that user's grants, row filters, and column masks.
Two people asking the same question can legitimately get different rows, and someone
without access to a table simply gets a permission error.

What it requires on your side:

1. The ClarityQ service account must be allowed to act as your end users (in
   file-based access control, an `impersonation` rule; the equivalent exists in
   Starburst and Ranger deployments).
2. ClarityQ user emails must resolve to the usernames your cluster authorises.

Scheduled refreshes, catalog discovery, and other background work have no asking user,
so they continue to run as the service account.

<Note>
  With per-user identity enabled, cached results are kept separate per user, and the
  shared dashboard result cache is bypassed — a user is never served rows that were
  filtered for someone else.
</Note>

## Connection parameters reference

| Parameter           | Type    | Required | Default | Description                                               |
| ------------------- | ------- | -------- | ------- | --------------------------------------------------------- |
| `connection_name`   | string  | yes      | —       | Label for this connection                                 |
| `host`              | string  | yes      | —       | Trino coordinator hostname                                |
| `user`              | string  | yes      | —       | Service account username                                  |
| `catalog`           | string  | yes      | —       | Default catalog                                           |
| `port`              | number  | no       | `443`   | Coordinator port                                          |
| `db_schema`         | string  | no       | —       | Default schema                                            |
| `http_scheme`       | string  | no       | `https` | `https` or `http`                                         |
| `password`          | string  | no       | —       | LDAP / password-file credential                           |
| `access_token`      | string  | no       | —       | JWT credential                                            |
| `impersonate_users` | boolean | no       | `false` | Run each query as the asking user (see per-user identity) |

## Querying across catalogs

Reference tables by their fully-qualified three-part name — `catalog.schema.table` — to reach data outside the default catalog. Joins that span catalogs (for instance Hive fact tables against ClickHouse marts) execute inside Trino; nothing extra is required on the ClarityQ side.

## How ClarityQ uses the connection

* Schema discovery reads `information_schema.tables` / `information_schema.columns` of the configured catalog.
* Partition detection probes the connector's `"<table>$partitions"` metadata table, so date-partitioned Hive/Iceberg/Delta tables get partition-pruned filters automatically.
* Row-count estimates come from `SHOW STATS`; running `ANALYZE <table>` on important tables improves them.
* Every query ClarityQ starts is registered for cancellation — aborting a question in the UI kills the query on the cluster, not just the request.

## Troubleshooting

| Symptom                                                       | Likely cause                                                                                                                            |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Test connection hangs, then fails                             | Coordinator not reachable from ClarityQ's IPs, or port/scheme mismatch (e.g. `https` against a plain-HTTP port)                         |
| `Access Denied` errors                                        | The service account lacks `SELECT` on the target catalog/schema — check Ranger/Immuta/file rules                                        |
| "password/token authentication requires http\_scheme 'https'" | Credentials were combined with `http`; enable TLS on the coordinator or remove the credential on trusted networks                       |
| Tables missing after discovery                                | They live in a catalog other than the configured default — reference them as `catalog.schema.table` or add another connection           |
| Cancel appears to do nothing                                  | The account running the query may not be allowed to kill it — grant `kill` on its own queries (see the note in Step 1)                  |
| Users see more or fewer rows than expected                    | With per-user identity enabled, results reflect that user's own grants — verify the mapping between ClarityQ emails and Trino usernames |