Materialized Views

The MaterializedViewController manages pre-computed query results that accelerate frequently-executed analytical patterns. Materialized views store the results of expensive queries and serve them directly, bypassing the underlying data processing.

Base Path

/v1/materialized-views

Create a Materialized View

curl -X POST http://query-engine:8080/v1/materialized-views \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "name": "daily_revenue_by_region",
    "description": "Pre-aggregated daily revenue by region",
    "query": "SELECT date_trunc('\''day'\'', order_date) as day, region, SUM(revenue) as total_revenue, COUNT(*) as order_count FROM orders GROUP BY 1, 2",
    "refreshSchedule": "0 0 * * * ?",
    "enabled": true
  }'

List Materialized Views

curl http://query-engine:8080/v1/materialized-views \
  -H "Authorization: Bearer $JWT_TOKEN"

Refresh a View

curl -X POST http://query-engine:8080/v1/materialized-views/{viewId}/refresh \
  -H "Authorization: Bearer $JWT_TOKEN"

Find Matching Views for a Query

curl -X POST http://query-engine:8080/v1/materialized-views/match \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{"query": "SELECT region, SUM(revenue) FROM orders WHERE order_date >= '\''2026-01-01'\'' GROUP BY region"}'

Get Suggestions

The service analyzes query patterns and suggests materialized views that could improve performance:

curl http://query-engine:8080/v1/materialized-views/suggestions \
  -H "Authorization: Bearer $JWT_TOKEN"

[
  {
    "suggestedName": "mv_region_revenue",
    "query": "SELECT region, date_trunc('day', order_date) as day, SUM(revenue), COUNT(*) FROM orders GROUP BY 1, 2",
    "estimatedSpeedup": 15.0,
    "matchingPatternCount": 450,
    "estimatedStorageBytes": 10485760,
    "reason": "This aggregation pattern is executed 450 times per week with avg latency of 3.2s"
  }
]

View Statistics

curl http://query-engine:8080/v1/materialized-views/{viewId}/statistics \
  -H "Authorization: Bearer $JWT_TOKEN"

Enable/Disable

# Disable a view (keeps data but stops serving)
curl -X POST http://query-engine:8080/v1/materialized-views/{viewId}/disable \
  -H "Authorization: Bearer $JWT_TOKEN"
 
# Re-enable
curl -X POST http://query-engine:8080/v1/materialized-views/{viewId}/enable \
  -H "Authorization: Bearer $JWT_TOKEN"

Required Role

Creating, updating, deleting, refreshing, enabling, and disabling materialized views requires ADMIN or QUERY_ADMIN role. Reading and matching are available to all authenticated users.

Cost Estimation Workload Management