---
title: "Create Workspace Table"
method: POST
path: "/v1/workspaces/{workspace_id}:createTable"
tags: ["workspace"]
---

# Create Workspace Table

`POST /v1/workspaces/{workspace_id}:createTable`

## Path parameters

- `workspace_id` string, required

## Request body

- BodyCreateWorkspaceTableV1WorkspacesWorkspaceIdCreateTablePost
  - `catalogId` string, required
  - `schemaId` string, required
  - `tableId` string, required
  - `table` TableInput, required — A SQL-visible table owned by its parent schema.
    - `name` string — Resource name in the form `workspaces/{workspace}/catalogs/{catalog}/schemas/{schema}/tables/{table}`. The terminal resource ID is the SQL-visible table name.
    - `spec` TableSpecInput, required — A strongly typed table definition.
      - `relational` RelationalTableSpec — One relation queried through a relational connector.
        - `connector` string, required — Connector used to query the source table.
        - `sourceCatalog` string, required — Source catalog containing the table.
        - `sourceSchema` string, required — Source schema containing the table.
        - `sourceTable` string, required — Source table selected through the connector.
        - `snapshot` RelationalTableSnapshot — Constructor snapshot for one relational table.
          - `schema` ArrowIpcSchema, required — An Arrow schema encoded as one canonical Arrow IPC schema message. The bytes contain only schema metadata, not an IPC stream, file, dictionary, record batch, or continuation marker. Consumers must reject any other IPC payload kind.
            - `ipcMessage` string, binary, required
      - `listing` ListingTableSpecInput — One table inferred from one or more absolute object-store URLs.
        - `connector` string, required — Object-store connector used to discover and read the table.
        - `tablePaths` string[], required — Paths must all resolve to the same object-store registration identity.
        - `snapshot` ListingTableSnapshotInput — Optional constructor snapshot for a DataFusion listing table.
          - `fileSchema` ArrowIpcSchema — An Arrow schema encoded as one canonical Arrow IPC schema message. The bytes contain only schema metadata, not an IPC stream, file, dictionary, record batch, or continuation marker. Consumers must reject any other IPC payload kind.
            - `ipcMessage` string, binary, required
          - `options` ListingTableOptionsInput — Serializable subset of DataFusion ListingOptions.
            - `fileType` string, required — Session file-format factory name, such as `parquet`, `csv`, or `json`.
            - `formatOptions` object — Options passed to the selected file-format factory.
            - `fileExtension` string — Suffix used to select files beneath each table path.
            - `tablePartitionSchema` ArrowIpcSchema — An Arrow schema encoded as one canonical Arrow IPC schema message. The bytes contain only schema metadata, not an IPC stream, file, dictionary, record batch, or continuation marker. Consumers must reject any other IPC payload kind.
              - …
            - `collectStat` boolean, nullable — Whether DataFusion should collect file statistics while listing.
            - `targetPartitions` integer, nullable — Target number of file-scan partitions.
    - `createTime` string, date-time, nullable — Time at which the table was created.
    - `updateTime` string, date-time, nullable — Time at which the table was most recently updated.
    - `revision` integer — Monotonically increasing revision of this table definition.
    - `revisionHash` string — Lowercase SHA-256 hash of the canonical stored table definition.

## Response `201`

Successful Response

- TableOutput — A SQL-visible table owned by its parent schema.
  - `name` string, required — Resource name in the form `workspaces/{workspace}/catalogs/{catalog}/schemas/{schema}/tables/{table}`. The terminal resource ID is the SQL-visible table name.
  - `spec` TableSpecOutput, required — A strongly typed table definition.
    - `relational` RelationalTableSpec — One relation queried through a relational connector.
      - `connector` string, required — Connector used to query the source table.
      - `sourceCatalog` string, required — Source catalog containing the table.
      - `sourceSchema` string, required — Source schema containing the table.
      - `sourceTable` string, required — Source table selected through the connector.
      - `snapshot` RelationalTableSnapshot — Constructor snapshot for one relational table.
        - `schema` ArrowIpcSchema, required — An Arrow schema encoded as one canonical Arrow IPC schema message. The bytes contain only schema metadata, not an IPC stream, file, dictionary, record batch, or continuation marker. Consumers must reject any other IPC payload kind.
          - `ipcMessage` string, binary, required
    - `listing` ListingTableSpecOutput — One table inferred from one or more absolute object-store URLs.
      - `connector` string, required — Object-store connector used to discover and read the table.
      - `tablePaths` string[], required — Paths must all resolve to the same object-store registration identity.
      - `snapshot` ListingTableSnapshotOutput — Optional constructor snapshot for a DataFusion listing table.
        - `fileSchema` ArrowIpcSchema — An Arrow schema encoded as one canonical Arrow IPC schema message. The bytes contain only schema metadata, not an IPC stream, file, dictionary, record batch, or continuation marker. Consumers must reject any other IPC payload kind.
          - `ipcMessage` string, binary, required
        - `options` ListingTableOptionsOutput — Serializable subset of DataFusion ListingOptions.
          - `fileType` string, required — Session file-format factory name, such as `parquet`, `csv`, or `json`.
          - `formatOptions` object — Options passed to the selected file-format factory.
          - `fileExtension` string — Suffix used to select files beneath each table path.
          - `tablePartitionSchema` ArrowIpcSchema — An Arrow schema encoded as one canonical Arrow IPC schema message. The bytes contain only schema metadata, not an IPC stream, file, dictionary, record batch, or continuation marker. Consumers must reject any other IPC payload kind.
            - `ipcMessage` string, binary, required
          - `collectStat` boolean, nullable — Whether DataFusion should collect file statistics while listing.
          - `targetPartitions` string, nullable — Target number of file-scan partitions.
  - `createTime` string, nullable — Time at which the table was created.
  - `updateTime` string, nullable — Time at which the table was most recently updated.
  - `revision` string — Monotonically increasing revision of this table definition.
  - `revisionHash` string — Lowercase SHA-256 hash of the canonical stored table definition.

## Other responses

- `422` — Validation Error

## Changes

- **2026-07-31** `6c6e81fb3282` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/outerproduct/apis/outerproduct-api/changes/v1/workspaces/:workspace_id:createTable/post.md)

---

[API](https://skmtc.dev/outerproduct/apis/outerproduct-api.md) · [All operations](https://skmtc.dev/outerproduct/apis/outerproduct-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/outerproduct/outerproduct-api/revisions/6c6e81fb3282/schema)