Views API

Views provide a way to define named SQL queries that can be referenced like tables.

List Views

List all views in a namespace.

Request

GET /v1/namespaces/{namespace}/views
GET /v1/namespaces/{namespace}/views?pageToken={token}&pageSize={size}

Query Parameters

Parameter	Type	Required	Description
`pageToken`	string	No	Pagination token
`pageSize`	integer	No	Maximum results (default: 100)

Response

{
  "identifiers": [
    {"namespace": ["analytics"], "name": "daily_events"},
    {"namespace": ["analytics"], "name": "user_summary"}
  ],
  "next-page-token": null
}

Example

curl http://localhost:8181/v1/namespaces/analytics/views

Create View

Create a new view.

Request

POST /v1/namespaces/{namespace}/views

Request Body

{
  "name": "daily_events",
  "schema": {
    "type": "struct",
    "schema-id": 0,
    "fields": [
      {"id": 1, "name": "event_date", "required": true, "type": "date"},
      {"id": 2, "name": "event_count", "required": true, "type": "long"},
      {"id": 3, "name": "unique_users", "required": true, "type": "long"}
    ]
  },
  "view-version": {
    "version-id": 1,
    "schema-id": 0,
    "timestamp-ms": 1705312200000,
    "summary": {
      "engine-name": "spark",
      "engine-version": "3.5.0"
    },
    "representations": [
      {
        "type": "sql",
        "sql": "SELECT DATE(event_time) AS event_date, COUNT(*) AS event_count, COUNT(DISTINCT user_id) AS unique_users FROM analytics.user_events GROUP BY DATE(event_time)",
        "dialect": "spark"
      }
    ],
    "default-catalog": "bingsan",
    "default-namespace": ["analytics"]
  },
  "properties": {
    "owner": "data-team"
  }
}

Request Fields

Field	Type	Required	Description
`name`	string	Yes	View name
`location`	string	No	Custom view location
`schema`	object	Yes	Output schema of the view
`view-version`	object	Yes	View version with SQL definition
`properties`	object	No	View properties

View Version Fields

Field	Type	Required	Description
`version-id`	integer	Yes	Version identifier
`schema-id`	integer	Yes	Schema ID for this version
`timestamp-ms`	long	Yes	Creation timestamp
`summary`	object	No	Engine information
`representations`	array	Yes	SQL representations
`default-catalog`	string	No	Default catalog for unqualified names
`default-namespace`	array	No	Default namespace

Example

curl -X POST http://localhost:8181/v1/namespaces/analytics/views \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily_summary",
    "schema": {
      "type": "struct",
      "schema-id": 0,
      "fields": [
        {"id": 1, "name": "day", "required": true, "type": "date"},
        {"id": 2, "name": "total", "required": true, "type": "long"}
      ]
    },
    "view-version": {
      "version-id": 1,
      "schema-id": 0,
      "timestamp-ms": 1705312200000,
      "representations": [
        {
          "type": "sql",
          "sql": "SELECT DATE(ts) as day, COUNT(*) as total FROM events GROUP BY 1",
          "dialect": "spark"
        }
      ]
    }
  }'

Load View

Load a view's current metadata.

Request

GET /v1/namespaces/{namespace}/views/{view}

Response

{
  "metadata-location": "s3://bucket/warehouse/views/daily_events/metadata/00001-uuid.metadata.json",
  "metadata": {
    "view-uuid": "550e8400-e29b-41d4-a716-446655440000",
    "format-version": 1,
    "location": "s3://bucket/warehouse/views/daily_events",
    "current-version-id": 1,
    "versions": [
      {
        "version-id": 1,
        "schema-id": 0,
        "timestamp-ms": 1705312200000,
        "representations": [...]
      }
    ],
    "properties": {
      "owner": "data-team"
    }
  }
}

Example

curl http://localhost:8181/v1/namespaces/analytics/views/daily_events

Check View Exists

Check if a view exists.

Request

HEAD /v1/namespaces/{namespace}/views/{view}

Response

200 OK: View exists
404 Not Found: View does not exist

Example

curl -I http://localhost:8181/v1/namespaces/analytics/views/daily_events

Replace View

Replace a view's definition with a new version.

Request

POST /v1/namespaces/{namespace}/views/{view}

Requirements

Type	Fields	Description
`assert-view-uuid`	`uuid`	Assert view UUID matches

Update Actions

Action	Fields	Description
`assign-uuid`	`uuid`	Assign view UUID
`add-schema`	`schema`	Add new schema
`add-view-version`	`view-version`	Add view version
`set-current-view-version`	`view-version-id`	Set current version
`set-location`	`location`	Set view location
`set-properties`	`updates`	Update properties
`remove-properties`	`removals`	Remove properties

Errors

Code	Error	Description
404	`NoSuchViewException`	View not found
409	`CommitFailedException`	Requirements not met

Drop View

Delete a view.

Request

DELETE /v1/namespaces/{namespace}/views/{view}

Response

204 No Content: View deleted

Example

curl -X DELETE http://localhost:8181/v1/namespaces/analytics/views/daily_events

Rename View

Rename a view or move it to a different namespace.

Request

POST /v1/views/rename

Request Body

{
  "source": {
    "namespace": ["analytics"],
    "name": "old_view"
  },
  "destination": {
    "namespace": ["analytics"],
    "name": "new_view"
  }
}

Example

curl -X POST http://localhost:8181/v1/views/rename \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"namespace": ["analytics"], "name": "daily_summary"},
    "destination": {"namespace": ["analytics"], "name": "daily_aggregates"}
  }'

SQL Dialects

Views support multiple SQL dialects in their representations:

Dialect	Description
`spark`	Apache Spark SQL
`trino`	Trino SQL
`presto`	Presto SQL
`flink`	Apache Flink SQL
`hive`	Apache Hive SQL
`dremio`	Dremio SQL

A view can have multiple representations for different engines:

{
  "representations": [
    {"type": "sql", "sql": "SELECT ...", "dialect": "spark"},
    {"type": "sql", "sql": "SELECT ...", "dialect": "trino"}
  ]
}

Views API

On this page