> ## 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 ClarityQ talks to your Trino coordinator over its HTTP API, so 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 connection is enough for a whole cluster: by default ClarityQ discovers every catalog it exposes, and queries can span them. ClarityQ sends one SQL statement and Trino performs any cross-source work itself. ## Filling in the connection form The fields below appear in the order the form asks for them. ### Connection Name Any label you will recognise later, for example `Production Trino`. It has no effect on the connection. ### Coordinator Host The hostname of your Trino **coordinator** — the node that accepts client queries. Not a worker, and not a load balancer that fronts workers. ``` trino.example.com ``` ### Port `443` for a TLS-terminated coordinator, which is the normal production setup and the default here. Clusters behind a proxy sometimes publish a different port; use whatever your Trino URL uses. ClarityQ always connects over HTTPS. ### Default Catalog (optional) How wide ClarityQ looks: * **Empty** — every catalog on the cluster is discovered. Start here. * **Set** — discovery is confined to that catalog. `system`, `jmx`, `tpch` and `tpcds` are skipped either way, and stay queryable by full name. ### User The username ClarityQ authenticates as. Trino attributes every query to it, so it is the name that appears in your cluster's query history and the identity your access-control rules apply to. A dedicated service account is recommended; it needs read access only, and the grants are listed further down this page. ### Authentication Pick whichever your coordinator uses: * **Password** — for clusters using LDAP or a password file. Paste the service account's password. * **Access Token** — a JWT issued by the OAuth2/OIDC provider protecting your coordinator (Keycloak and similar). Paste a token for the service account; a long-lived one avoids re-entering it. Credentials are stored in ClarityQ's secret manager, never in the database, and are only ever sent over HTTPS. ### Run queries as the asking user (per-user permissions) Leave this **off** and every query runs as the service account above: your cluster sees one identity, and ClarityQ's own permissions decide what people can reach. Turn it **on** and ClarityQ instead runs each query as the person asking it. Your access-control layer — Ranger, OPA, Immuta or Trino's file-based rules — then applies that user's grants, row filters and column masks. Your cluster's query history also records the real asker rather than the service account, so your audit trail stays meaningful. Two people asking the same question can legitimately get different rows, and someone without access to a table gets a permission error. It requires two things on your side: 1. The service account must be allowed to act as your end users (an `impersonation` rule in file-based access control, or the equivalent in Starburst and Ranger). 2. Your cluster must authorise those users under the name ClarityQ sends, which is **the user's full ClarityQ email address** — `dana@yourcompany.com`, not `dana`. Either write your rules against the email, or map it to your internal username in your identity provider. Scheduled refreshes and catalog discovery have no asking user, so they continue to run as the service account. Cached results are also kept separate per user, so nobody is served rows that were filtered for someone else. Policy stays where you already keep it. ClarityQ writes nothing into your cluster and holds no copy of your grants — it states who is asking, and your engine decides. Existing Ranger or OPA policies apply to ClarityQ unchanged, with no permission model to duplicate. ## What to grant the service account Through your access-control layer, the account needs: 1. `SELECT` on every table ClarityQ should analyze 2. Read access to `information_schema` in every catalog you want discovered — that is how ClarityQ finds tables 3. Permission to cancel its own queries, so aborting a question stops the work on your cluster instead of leaving it running 4. An `impersonation` rule, only if you enable per-user permissions No write, DDL or admin privileges are needed. ClarityQ only reads. ## Network access Allow inbound connections to the coordinator from ClarityQ: * 44.218.213.75 * 54.161.37.107 * 54.208.212.67 ## Connection parameters reference | Parameter | Required | Default | Description | | - | - | - | - | | `connection_name` | yes | — | Label for this connection | | `host` | yes | — | Trino coordinator hostname | | `port` | no | `443` | Coordinator port | | `catalog` | no | — | Confines discovery to this catalog, and resolves unqualified names against it; empty discovers every catalog | | `user` | yes | — | Service account username | | `password` | one of | — | LDAP / password-file credential | | `access_token` | one of | — | JWT credential | | `impersonate_users` | no | `false` | Run each query as the asking user | ## How ClarityQ uses the connection * Table discovery reads `information_schema` — in the catalog you named, or in each catalog returned by `SHOW CATALOGS` when you named none. A catalog that cannot be read is skipped rather than failing discovery, so one misconfigured connector does not hide the rest. * A cluster-wide scan is time-boxed. On a cluster with very many catalogs it can stop early, and the catalogs it did not reach are named in ClarityQ's logs; naming a catalog on the connection avoids the scan entirely. * Partition detection probes the connector's `"$partitions"` metadata table, so date-partitioned Hive, Iceberg and Delta tables get partition-pruned filters automatically. Tables partitioned by separate `year`/`month`/`day` columns are recognised as partitioned but are not date-filtered, since no single column identifies a date. * Row counts and table sizes come from `SHOW STATS`; running `ANALYZE
` on important tables improves them. * Nested `ROW` and `ARRAY(ROW(...))` columns are expanded, so event-parameter style columns are described in the catalog. * Cancellation calls `DELETE /v1/query/{id}`, which your cluster authorises as killing a query the account owns. If that is not permitted, ClarityQ falls back to `CALL system.runtime.kill_query`, which needs permission to execute that procedure. Either one is enough. ## Troubleshooting | Symptom | Likely cause | | - | - | | Test connection hangs, then fails | The coordinator is not reachable from ClarityQ's IPs, or the port is wrong | | `Access Denied` on a table | The account being used lacks `SELECT` there — check your Ranger, OPA, Immuta or file-based rules. With per-user permissions on, that is the asking user, not the service account | | `Catalog '…' is not available on this cluster` | The catalog field is misspelled; the message lists the catalogs that do exist. Leave the field empty to use all of them | | `Cannot impersonate user …` | Per-user permissions is on but no impersonation rule grants it | | Tables missing after discovery | You named a catalog, so only that one is searched; or the service account lacks access to the catalog; or it is a benchmark catalog (`tpch`, `tpcds`) that discovery skips — those remain queryable as `catalog.schema.table` | | Tables a user cannot query still appear in the catalog | Discovery runs as the service account, so the tree reflects what it can see. Per-user rules are enforced when the query runs | | Cancelling appears to do nothing | The account may not be allowed to kill its own queries (see the note above) | | Users see more or fewer rows than expected | With per-user permissions on, results reflect that user's own grants — check that ClarityQ emails map to your Trino usernames | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.