Views and published APIs

A view turns a query you like into data that is kept up to date and, if you wish, served as an API for other systems (dashboards, reports).

1. Save a query as a view

1. In the SQL workspace write and run your query. Name every output column with AS (lowercase letters, digits and _, unique).
2. Click Save as view. Give it a title; the name (view__<name>) is derived. Add a description. Leave auto-refresh on unless you want manual rebuilds only.
3. The view is queued and built. Open Views to watch it.

Allowed column types are text, boolean, whole numbers, real/double/decimal, date and timestamp. Arrays, maps, rows, JSON and binary are refused with a hint.

2. The view page

Section	What it shows
Pipeline	Bronze > Silver > Gold with row counts of the latest run
Run history	Each build, why it ran (created, edited, manual, source data changed), its stage, row counts and any error
Reads	Which datasets and other views it reads (lineage)
Columns and SQL	What it produces and the query. Edit SQL returns to the workspace; Update view saves the change
API	Endpoint, a ready-made curl, and the keys

A failed build keeps serving the last good data. A build is also refused (status blocked) if you lost access to one of its sources.

When is it rebuilt? When you ask (Refresh now), when you edit it, when a file of a dataset it reads reaches processed, or when a view it reads has a newer build. Views can read other views; cycles and self-reads are refused, and a view that others read cannot be deleted.

3. Publish it as an API

On the view page, switch API on and choose the sort order (fixed for all callers). The endpoint is:

GET /api/v1/data/<view name>
GET /api/v1/data/<view name>/schema

Every request reads the gold table live from Trino. Nothing is cached or copied elsewhere. Switching the API off, an expired or revoked key, or a blocked view makes it refuse requests; a view that is merely building or failed keeps serving.

Call it

curl -H "Authorization: Bearer chdc_<your key>" \
     "https://lake.example.com/api/v1/data/hospital_summary?limit=50&city=Pune"

The key may also be sent as X-API-Key: chdc_....

Parameter	Meaning
limit	1 to 1000, default 100
offset	Rows to skip
<column>=<value>	Equality filter on a real column of the view (text comparison). Repeat it for several values (means “any of”)

The callers cannot send SQL. Column names come from the registry and values are escaped.

{
  "data": [ { "city": "Pune", "beds": 120 } ],
  "meta": { "limit": 50, "offset": 0, "returned": 1, "hasMore": false,
            "refreshedAt": "2026-10-27T05:12:09Z", "columns": ["city", "beds"] }
}

The header X-Data-Refreshed-At repeats refreshedAt.

Status	Meaning
401	No key, or a wrong, expired or revoked key
403	The key is valid but does not cover this API
429	Over 60 requests per minute for this key, or too many in flight (8)
503	The view is paused (blocked or switched off)

Other limits: a query may run 30 seconds, and a response is capped at 10 MB. Every call, including refused ones, is logged without key material.

4. Keys

Two kinds of keys open published APIs. Both are shown once; only a hash is stored. Both can be revoked and last 1-365 days (default 90).

• Per-view key. Made on the view page. Opens that one API.
• Reusable access key. Made on API keys. Its scope decides what it opens:

Scope	Opens
owner	all of your published APIs, including ones you make later
vendor	your published APIs whose data comes only from one vendor’s datasets
project	the same, for one project
global (admin)	every published API

An analyst’s key is always tied to that analyst and can never open someone else’s views. A view that reads other views is opened only by owner or global keys.

5. Sharing and ownership

A view is private to its author and admins. Others get “not found”. Sharing a view with another analyst is not built yet.