Cost Endpoints

The cost estimation endpoints provide query cost analysis, engine comparison, cost breakdowns, and table statistics management. These endpoints help users understand the resource implications of their queries before execution. Served by QueryCostController at /v1/queries/cost.

Endpoints

Method	Endpoint	Description
POST	`/v1/queries/cost/estimate`	Estimate query cost
POST	`/v1/queries/cost/compare`	Compare costs across engines
POST	`/v1/queries/cost/breakdown`	Get detailed cost breakdown
GET	`/v1/queries/cost/statistics/:tableName`	Get table statistics
PUT	`/v1/queries/cost/statistics`	Update table statistics
GET	`/v1/queries/cost/statistics`	Get all cached statistics
DELETE	`/v1/queries/cost/statistics/:tableName`	Invalidate statistics

POST /v1/queries/cost/estimate

Estimates the cost of executing a query on a specific engine.

{
  "sql": "SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id WHERE orders.date > '2026-01-01'",
  "engineType": "TRINO"
}

Returns a CostEstimate with estimated bytes scanned, execution time, memory usage, and relative cost score.

POST /v1/queries/cost/compare

Compares query costs across all available engines to recommend the most efficient option.

{
  "sql": "SELECT region, COUNT(*) FROM events GROUP BY region"
}

Returns a list of EngineCostComparison objects, one per engine, with estimated cost, execution time, and a recommendation flag for the optimal engine.

POST /v1/queries/cost/breakdown

Returns a detailed cost breakdown showing the contribution of each query operation.

The breakdown includes:

Component	Description
Scan cost	Data reading from storage
Compute cost	CPU time for joins, aggregations, filters
Network cost	Data transfer between nodes
Memory cost	Peak memory allocation

Table Statistics

Cost estimation relies on table statistics (row counts, column cardinality, data size). These statistics can be queried and managed:

Get statistics:

GET /v1/queries/cost/statistics/orders

Update statistics:

PUT /v1/queries/cost/statistics

{
  "tableName": "orders",
  "rowCount": 5000000,
  "sizeBytes": 2147483648,
  "columnStats": {
    "customer_id": { "cardinality": 50000, "nullPercent": 0.0 },
    "amount": { "min": 0.01, "max": 99999.99, "nullPercent": 0.1 }
  }
}

Invalidate cached statistics:

DELETE /v1/queries/cost/statistics/orders

Schedule Endpoints Data Masking