How to Use Query Analyzer

Beta feature — Query Analyzer is disabled by default and available on demand. Contact your StarTree account team to have it enabled for your environment.

Query Analyzer is built into the StarTree Data Portal Query Console. No setup is required — open the console, write your query, and run an analysis.

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.

For a full breakdown of what each output field and recommendation type means, see Understanding Recommendations.

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.

For the full request and response schemas, see the API Reference.

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.

​Running Static Analysis

​Running Runtime Analysis

​Acting on Recommendations

​Using the API

​Prerequisites

​Static Analysis via API

​Runtime Analysis via API

​Optional Request Parameters

​Tips

Running Static Analysis

Running Runtime Analysis

Acting on Recommendations

Using the API

Prerequisites

Static Analysis via API

Runtime Analysis via API

Optional Request Parameters

Tips