Beta feature — Query Analyzer is disabled by default and available on demand. Contact your StarTree account team to have it enabled for your environment.
Running Static Analysis
Static analysis catches issues before your query runs.
- Navigate to Data Portal → Query Console
- Write or paste your SQL query
- Select Analyze → Static Analysis
Query Analyzer fetches table metadata automatically and returns results within seconds.
Running Runtime Analysis
Runtime analysis identifies issues after your query runs, using real execution statistics. Each risk flag includes the operator metrics and any correctness alerts relevant to that finding.
- Write your SQL query in the Query Console
- Select Analyze → Runtime Analysis
Runtime analysis executes your query against your Pinot cluster. For very large or expensive queries, run static analysis first to catch structural issues before proceeding.
Acting on Recommendations
Index additions — Apply through Data Portal → Table Management. Index changes require a segment reload to take effect on existing data.
Query rewrites — Apply directly in the Query Console editor. The recommendation shows a before/after diff.
Query hints — Added inline to your SQL using /*+ ... */ syntax. Take effect immediately without schema changes.
Start with rank 1 recommendations. If any risk flag carries a correctness alert, address it first — incomplete results affect how you should interpret the rest of the analysis.
Using the API
Both analysis modes are available as REST endpoints on the StarTree Cloud data-manager service. Use these when integrating Query Analyzer into CI pipelines, query validation tooling, or custom dashboards.
Prerequisites
- A valid StarTree Cloud API token (Bearer auth)
- The workspace ID for your environment (obtain from the Data Portal URL or your account team)
- Query Analyzer must be enabled for your environment
Static Analysis via API
POST /api/query-analyzer/static-analysis
Analyzes a SQL query using table metadata and explain plan only — no query execution required.
curl -X POST "https://<your-domain>/api/query-analyzer/static-analysis" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "workspace: <workspace-id>" \
-d '{
"sql": "SELECT COUNT(*) FROM orders WHERE status = '\''shipped'\'' AND ts > 1700000000"
}'
Runtime Analysis via API
POST /api/query-analyzer/runtime-analysis
Executes the query against your Pinot cluster, collects execution statistics, then runs analysis with evidence-backed findings.
curl -X POST "https://<your-domain>/api/query-analyzer/runtime-analysis" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "workspace: <workspace-id>" \
-d '{
"sql": "SELECT status, COUNT(*) FROM orders WHERE ts BETWEEN 1700000000 AND 1710000000 GROUP BY status"
}'
Runtime analysis executes your query against the cluster. For expensive queries, run static analysis first.
Optional Request Parameters
Both endpoints accept the following optional fields in the request body:
| Parameter | Type | Description |
|---|
timeout | string | ISO-8601 duration override for the LLM call (e.g. "PT60S", "PT5M"). Minimum: 10 seconds. Maximum: 10 minutes. Default: server-configured value. |
thinkingMode | boolean | Enable extended chain-of-thought reasoning in the LLM. Produces deeper analysis at the cost of higher latency. Default: server-configured value. |
Tips
- Use real queries: Query Analyzer uses column cardinality and table size to produce accurate recommendations. Simplified test queries produce weaker results.
- Static first, runtime second: Static analysis is faster. Use runtime analysis for your most important or problematic queries.
- Read the tradeoffs: Every recommendation includes tradeoffs, for example, an index that helps one query pattern may not justify the storage cost.
