Query Analyzer is an opt-in, AI-powered feature in StarTree Cloud. This page describes how your data is handled, which security controls apply, and how Query Analyzer inherits StarTree Cloud’s platform compliance posture.Documentation Index
Fetch the complete documentation index at: https://docs.startree.ai/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Query Analyzer is request-scoped: it processes one analysis per request and does not persist query text, metadata, or LLM responses to any database or customer-accessible storage.Data Flows
Collected from Pinot
For normal (non-direct) analysis, Query Analyzer uses your authenticated identity to call Pinot Controller admin APIs on your cluster. The following operations run per table referenced in your SQL (except explain and query execution, which run once per analysis request).| Operation | Pinot API | Static Analysis | Runtime Analysis | API reference |
|---|---|---|---|---|
| Fetch table config and schema | GET /tableConfigs/{tableName} | Yes | Yes | Get table configs |
| Infer index configuration | POST /tables/inferIndexes | Yes | Yes | StarTree extension API (normalizes index config for analysis) |
| Fetch table statistics | GET /tables/{tableName}/metadata | Yes | Yes | Get aggregate table metadata |
| Run explain plan | POST /sql with EXPLAIN PLAN FOR and useMultistageEngine=true;explainAskingServers=true (falls back to single-stage engine if needed) | Yes | Yes | Pinot Controller SQL query API |
| Execute the SQL query | POST /sql with useMultistageEngine=true;collectGcStats=true | No | Yes | Pinot Controller SQL query API |
The
POST /sql endpoint is the Pinot Controller SQL query API. It is used for explain plans and, in runtime analysis, to execute your query and collect stageStats. This is separate from the broker query API (POST /query/sql) used for interactive querying in some deployments.Sent to the LLM
What is never included in the LLM prompt
What is included in the LLM prompt
| Data | Source | Notes |
|---|---|---|
| SQL query text | User input | The query you submit for analysis |
| Table config (reduced) | Pinot | Stripped and masked (see note below) |
| Schema | Pinot | Field types, encoding, and index configuration |
| Column cardinality estimates | Pinot | Approximate distinct value counts per column |
| Explain plan | Pinot | Execution structure only |
| Execution statistics | Pinot | Operator timing and memory metrics (runtime analysis only) |
Before transmission, StarTree Cloud masks credentials and secret references in table configuration JSON and strips non-essential sections (ingestion config, task definitions, tenants, metadata, and routing).
Data Lifecycle and Retention
| Aspect | Behavior |
|---|---|
| Persistence | No query text, metadata, or LLM responses are written to durable storage |
| In-memory scope | Analysis data exists only for the duration of the HTTP request |
| Application logs | StarTree Cloud application logs may record SQL text at INFO level; subject to platform log retention and access controls |
AI Model and Provider
| Deployment | AI Provider | Model |
|---|---|---|
| AWS | Amazon Bedrock | Claude (Anthropic), us.anthropic.claude-sonnet-4-20250514-v1:0 |
| Google Cloud (Coming Soon) | Vertex AI | Not yet available |
| Azure (Coming Soon) | Azure AI Foundry | Not yet available |
Access Controls
Query Analyzer uses the same authentication and authorization model as other StarTree Cloud APIs. See Manage Security for OIDC identity provider setup, RBAC policies, and API tokens.| Control | Behavior |
|---|---|
| Authentication | Required for POST /api/query-analyzer/static-analysis and POST /api/query-analyzer/runtime-analysis |
| Authorization | Governed by StarTree Cloud RBAC and Pinot cluster policies for the tables in your query |
| Workspace scoping | Use the workspace header to scope requests to a specific workspace |
| Feature availability | Disabled by default. Contact your StarTree account team to enable. |
Encryption
| Layer | Control |
|---|---|
| In transit | TLS 1.2+ between Data Portal, StarTree Cloud, Pinot, and the LLM provider |
| At rest | Query Analyzer does not write analysis data to disk; platform policies apply to operational logs |
| Secrets | LLM API keys are managed through StarTree’s secure deployment configuration and are not embedded in customer-facing payloads |
Platform Compliance
Query Analyzer runs within StarTree Cloud infrastructure and inherits platform certifications:- SOC 2 Type 2
- ISO 27001
- HIPAA readiness
Related Documentation
Query Analyzer Overview
Feature overview, analysis modes, and what gets analyzed.
StarTree Cloud Security
Platform-wide security controls and compliance certifications.