docs · sql · materialized views

Materialized views.

A materialized view is a precomputed query result that you can read like a table. OriginChain ships on-demand refresh: you install a view with a SQL definition, refresh it when you want the numbers updated, and read it like any other table. Incremental refresh stays on the roadmap.

Three endpoints.

POST :name/install Define the view + compute the initial materialization in one call.
POST :name/refresh Re-run the definition and atomically overwrite the materialization.
GET :name Read the materialization. Constant-time vs the underlying GROUP BY.

Install.

POST /v1/tenants/:t/sql/materialized_views/:name/install

curl -X POST "https://acme.db.originchain.ai/v1/tenants/$T/sql/materialized_views/customer_revenue/install" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT customer_id, SUM(qty * price) AS revenue FROM line_items GROUP BY customer_id"
  }'

Refresh.

The refresh atomically overwrites the existing materialization. Readers see either the previous version or the new one — never a half-written state.

POST /v1/tenants/:t/sql/materialized_views/:name/refresh

curl -X POST "https://acme.db.originchain.ai/v1/tenants/$T/sql/materialized_views/customer_revenue/refresh" \
  -H "Authorization: Bearer $OC_TOKEN"

Read.

GET /v1/tenants/:t/sql/materialized_views/:name

curl "https://acme.db.originchain.ai/v1/tenants/$T/sql/materialized_views/customer_revenue" \
  -H "Authorization: Bearer $OC_TOKEN"

Cost considerations.

Refresh re-runs the full definition. Cost scales with the underlying query; pick refresh cadence to match how stale your readers can tolerate. For hot rollups (BI dashboards, leaderboards) refresh on a fixed cron — for cold rollups, refresh on demand. Incremental refresh (delta-only) is on the roadmap; until then, a full refresh is the only path.