Skip to main content
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.

​
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

​
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 "<table>$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 <table> 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