Skip to main content

​
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.
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.

​
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

​
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.
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.

​
Connection parameters reference

​
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