Create a table in the given namespace

post

{scheme}://{host}/{basePath}/v1/{prefix}/namespaces/{namespace}/tables

Create a table or start a create transaction, like atomic CTAS.

If stage-create is false, the table is created immediately.

If stage-create is true, the table is not created, but table metadata is initialized and returned. The service should prepare as needed for a commit to the table commit endpoint to complete the create transaction. The client uses the returned metadata to begin a transaction. To commit the transaction, the client sends all create and subsequent changes to the table commit route. Changes from the table create operation include changes like AddSchemaUpdate and SetCurrentSchemaUpdate that set the initial table state.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

prefix

string

required

An optional prefix in the path

namespace

string

required

A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

Body Params

name

string

required

location

string

schema

object

required

partition-spec

object

write-order

object

stage-create

boolean

properties

object

Headers

X-Iceberg-Access-Delegation

string

enum

Optional signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms.

Specific properties and handling for vended-credentials is documented in the LoadTableResult schema section of this spec document.

The protocol and specification for remote-signing is documented in the s3-signer-open-api.yaml OpenApi spec in the aws module.

Allowed:

Responses

Language

Credentials

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Table metadata result after creating a table

400Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure, such as invalid json. Usually serves application/json content, although in some cases simple text/plain content might be returned by the server's middleware.

401Unauthorized. The REST Catalog SHOULD respond with the 401 UnauthorizedResponse when the access token provided is expired, revoked, malformed, or invalid for other reasons. The client MAY request a new access token and retry the request.

403Forbidden. Authenticated user does not have the necessary permissions.

404Not Found - The namespace specified does not exist

409Conflict - The table already exists

419This is an optional status response type that the REST Catalog can issue when the token has expired. The client MAY request a new access token and retry the request. 401 UnauthorizedResponse SHOULD be preferred over this response type on token expiry.

503The service is not ready to handle the request, request could have been partially processed. The service may additionally send a Retry-After header to indicate when to retry, a non idempotent request should only be retried by the client when the Retry-After header is present.

5XXA server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.