Query Analyzer API Reference

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 exposes two REST endpoints on the StarTree Cloud data-manager service. Both return the same unified response structure.

Endpoints

Method	Path	Purpose
`POST`	`/api/data/manager/api/query-analyzer/static-analysis`	Analyze a query using table metadata and explain plan — no execution required
`POST`	`/api/data/manager/api/query-analyzer/runtime-analysis`	Execute the query, collect stage statistics, then analyze with evidence-backed findings

Authentication and Headers

All requests require a valid StarTree Cloud Bearer token. The workspace header scopes the request to a specific workspace.

Header	Required	Description
`Authorization`	Yes	`Bearer <token>`
`Content-Type`	Yes	`application/json`
`workspace`	No	Workspace ID. When omitted, the default workspace for the principal is used.

POST /api/data/manager/api/query-analyzer/static-analysis

Analyzes a SQL query using only table metadata and explain plan. Does not execute the query. Returns results within seconds.

Request Body

{
  "sql": "SELECT COUNT(*) FROM orders WHERE status = 'shipped' AND ts > 1700000000",
  "timeout": "PT60S"
}

Field	Type	Required	Description
`sql`	string	Yes	The SQL query to analyze
`timeout`	string	No	ISO-8601 duration override for the LLM call (e.g. `"PT60S"`, `"PT5M"`). Min: 10s. Max: 10 minutes.

Example Request

curl -X POST "https://<your-domain>/api/data/manager/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"
  }'

Example Response

{
  "querySummary": "Counts all orders with status 'shipped' after a given Unix timestamp.",
  "analysisType": "STATIC",
  "findings": [
    {
      "type": "MISSING_INVERTED_INDEX",
      "severity": "HIGH",
      "description": "Column 'status' is used in an equality predicate but has no inverted index. Every segment will be fully scanned.",
      "evidence": [
        {
          "type": "MISSING_INDEX",
          "detail": "status: no inverted index found"
        }
      ],
      "confidence": "HIGH"
    }
  ],
  "recommendations": [
    {
      "rank": 1,
      "title": "Add inverted index on 'status'",
      "type": "ADD_INVERTED_INDEX",
      "description": "An inverted index on 'status' will allow Pinot to skip segments that do not contain the predicate value, eliminating the full scan.",
      "suggestedChange": {
        "before": "\"invertedIndexColumns\": []",
        "after": "\"invertedIndexColumns\": [\"status\"]"
      },
      "expectedImpact": "HIGH",
      "confidence": "HIGH",
      "tradeoffs": "Adds a small amount of index storage per segment. Requires a segment reload to take effect on existing data."
    }
  ]
}

POST /api/data/manager/api/query-analyzer/runtime-analysis

Executes the query against your Pinot cluster using the multi-stage engine (MSE), collects stage execution statistics, then produces evidence-backed findings tied to measured operator metrics. If the query is not MSE-compatible, the service automatically falls back to static analysis. The response analysisType field reflects which mode was used, and mseIncompatibleReason is populated on fallback.

Request Body

{
  "sql": "SELECT status, COUNT(*) FROM orders WHERE ts BETWEEN 1700000000 AND 1710000000 GROUP BY status",
  "timeout": "PT120S"
}

Field	Type	Required	Description
`sql`	string	Yes	The SQL query to execute and analyze
`timeout`	string	No	ISO-8601 duration override for the LLM call. Min: 10s. Max: 10 minutes.

Runtime analysis executes your query against the cluster. For very large or expensive queries, run static analysis first to catch structural issues before spending compute.

Example Request

curl -X POST "https://<your-domain>/api/data/manager/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"
  }'

Example Response

{
  "querySummary": "Counts orders grouped by status within a time window.",
  "analysisType": "RUNTIME",
  "findings": [
    {
      "type": "MISSING_RANGE_INDEX",
      "severity": "HIGH",
      "description": "Column 'ts' is used in a BETWEEN predicate but has no range index. All segments are being scanned.",
      "evidence": [
        {
          "type": "MISSING_INDEX",
          "detail": "ts: no range index found"
        },
        {
          "type": "HIGH_POST_FILTER_SCAN",
          "detail": "numEntriesScannedPostFilter: 48,200,000"
        }
      ],
      "confidence": "HIGH",
      "operator": "TABLE_SCAN",
      "metrics": {
        "executionTimeMs": 3420,
        "memoryAllocatedBytes": 0,
        "rowsProduced": 12400
      }
    }
  ],
  "recommendations": [
    {
      "rank": 1,
      "title": "Add range index on 'ts'",
      "type": "ADD_RANGE_INDEX",
      "description": "A range index on 'ts' allows Pinot to prune segments outside the time window, reducing the scan to only matching segments.",
      "suggestedChange": {
        "before": "\"rangeIndexColumns\": []",
        "after": "\"rangeIndexColumns\": [\"ts\"]"
      },
      "expectedImpact": "HIGH",
      "confidence": "HIGH",
      "tradeoffs": "Adds index storage per segment. Requires a segment reload to take effect on existing data."
    }
  ]
}

Response Schema

Both endpoints return a QueryAnalysisResponse object.

Field	Type	Description
`querySummary`	string	Plain-English description of what the query does
`analysisType`	string	`RUNTIME` when MSE execution succeeded; `STATIC` when the service fell back to static analysis
`mseIncompatibleReason`	string	Reason MSE execution was not possible. Null when `analysisType` is `RUNTIME`.
`findings`	array	Risk flags detected, each with type, severity, description, evidence, confidence, and (runtime only) operator and metrics
`recommendations`	array	Ranked, actionable suggestions with title, type, description, suggested change, expected impact, confidence, evidence references, tradeoffs, and correctness notes
`error`	object	Structured error. Null on success. See Error Response.

Error Response

When a request fails, the response body contains an error object and the HTTP status reflects the failure category.

{
  "error": {
    "errorType": "BAD_REQUEST",
    "description": "Invalid timeout value 'PT1S'. Expected ISO-8601 duration (e.g. PT60S, PT5M)."
  }
}

Field	Type	Description
`errorType`	string	Machine-readable error category (e.g. `BAD_REQUEST`, `PINOT_UNAVAILABLE`, `LLM_ERROR`, `UNKNOWN`)
`description`	string	Human-readable explanation of the failure
`cause`	object	Optional nested cause chain for debugging

Common HTTP status codes:

Status	When
`200`	Analysis completed successfully
`400`	Malformed request (e.g. missing `sql`, invalid `timeout` format, timeout out of bounds)
`401`	Missing or invalid authentication token
`403`	The authenticated principal does not have access to the requested tables
`500`	Internal error — contact support if it persists

How to Use Query Analyzer

Step-by-step guide to running analysis from the Query Console and via API.

Understanding Recommendations

Full reference for every finding type, recommendation category, operator type, and evidence field in the response.

Security and Compliance

What data is sent to the LLM, access controls, and platform compliance posture.

​Endpoints

​Authentication and Headers

​POST /api/data/manager/api/query-analyzer/static-analysis

​Request Body

​Example Request

​Example Response

​POST /api/data/manager/api/query-analyzer/runtime-analysis

​Request Body

​Example Request

​Example Response

​Response Schema

​Error Response

​Related Documentation

How to Use Query Analyzer

Understanding Recommendations

Security and Compliance

Endpoints

Authentication and Headers

POST /api/data/manager/api/query-analyzer/static-analysis

Request Body

Example Request

Example Response

POST /api/data/manager/api/query-analyzer/runtime-analysis

Request Body

Example Request

Example Response

Response Schema

Error Response

Related Documentation