IBM Cloud API Docs

Introduction

Last updated: 2024-12-05

The Iceberg REST Catalog is a metadata management solution for Apache Iceberg, a high-performance table format for managing large-scale datasets. The REST Catalog provides a unified, API-driven approach to interact with Iceberg metadata, enabling dynamic and scalable metadata management across distributed environments.

The api are in beta state and expected to change.

Endpoint URLs

The base URL for Iceberg Rest catalog, https://{host}/mds/iceberg,

Authentication

Required Purpose: To work with the API, you must use an IBM Cloud Pak for Data API key (platform API key or instance API key), or IBM Cloud Pak for Data authorization token (platform token or instance token). The API key or token is used to determine the actions that a user or service ID has access to when they use the API.

You can generate an API key or authorization token for an authenticated user by using the Cloud Pak for Data APIs. For more information, see Generating an authorization token or API key.

To use the API, add a valid API key or token to the HTTP Authorization request header. For token, -H 'Authorization: Bearer {TOKEN}'. For API key, you need to firstly encode username together with API key: echo "<username>:<api_key>" | base64. Then, you can use the ZenApiKey header to authenticate to an endpoint: -H "Authorization: ZenApiKey <encoded value>".

To retrieve your access token:

For most Cloud Pak for Data endpoints, you can use the generated API key in the authorization header of subsequent API calls.

curl -H "Authorization: ZenApiKey <token>" "https://<cpd_instance_route>/<endpoint>"

If the ZenApiKey token is not supported, use a generated Bearer token in the authorization header of subsequent API calls.

curl -H "Authorization: Bearer <token>" "https://<cpd_instance_route>/<endpoint>"

Security scheme

Authentication to this API's methods uses one of the following security schemes.

BearerAuth

Attribute

Value
  • Type
    HTTP
  • Scheme
    Bearer

BasicAuth

Attribute

Value
  • Type
    HTTP
  • Scheme
    Basic

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
204 No Content The server successfully processed the request and is not returning any content.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{namespace}'.
404 Not Found The requested resource could not be found.
409 Conflict The entity is already in the requested state.
500 Internal Server Error Your request could not be processed. Wait a few minutes and try again.

Methods

List all catalog configuration settings

All REST clients should first call this route to get catalog configuration properties from the server to configure the catalog and its HTTP client. Configuration from the server consists of two sets of key/value pairs.

  • defaults - properties that should be used as default configuration; applied before client configuration
  • overrides - properties that should be used to override client configuration; applied after defaults and client configuration

Catalog configuration is constructed by setting the defaults, then client- provided configuration, and finally overrides. The final property set is then used to configure the catalog.

GET /v1/config

Request

Query Parameters

  • warehouse
    string

    Warehouse should be passsed as wxd iceberg catalog_name from spark/presto engine to configure default wxd iceberg catalog

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/config?warehouse={catalog_name}"

Response

Response Body

CatalogConfig

Server-provided configuration for the catalog.

Status Code

  • 200

    Server specified configuration values.

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "overrides": {
    "warehouse": "s3://bucket/warehouse/"
  }
}
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

List namespaces

List all namespace

GET /v1/{prefix}/namespaces

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

Query Parameters

  • pageToken
    string

    A token used to retrieve the next page of results in a paginated response

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 -]*$, allows empty value

  • pageSize
    integer

    For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated pageSize.

    Possible values: 0 ≤ value ≤ 1000000000000000

  • curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/{catalog_name}/namespaces"

Response

Response Body

ListNamespacesResponse

Status Code

  • 200

    A list of namespaces

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - Namespace provided in the parent query parameter is not found.

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "namespaces": [
    [
      "namespace1"
    ],
    [
      "namespace2"
    ]
  ]
}
  • {
  "namespaces": []
}
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Create a namespace

Create a namespace, with an optional set of properties. The server might also add properties, such as last_modified_time etc.

POST /v1/{prefix}/namespaces

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

Request Body

Required*
CreateNamespaceRequest

Request to create Namespace

  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"namespace":["namespace_name"],"properties":{"owner":"string","storage_location":"s3a://bucket_name/namespace_name"}}' "https://{region}/mds/iceberg/v1/catalog_name/namespaces"

Response

Response Body

CreateNamespaceResponse

Status Code

  • 200

    Represents a successful call to create a namespace. Returns the namespace created, as well as any properties that were stored for the namespace, including those the server might have added. Implementations are not required to support namespace properties.

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 406

    Not Acceptable / Unsupported Operation. The server does not support this operation.

  • 409

    Conflict - The namespace already exists

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "namespace": [
    "namespace_name"
  ],
  "properties": {
    "owner": "string",
    "created_at": "0"
  }
}
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}
  • {
  "error": {
    "message": "The given namespace already exists",
    "type": "AlreadyExistsException",
    "code": 409
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Load the metadata properties for a namespace

Return all stored metadata properties for a given namespace

GET /v1/{prefix}/namespaces/{namespace}

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/{catalog_name}/namespaces/{namespace_name}'"

Response

Response Body

GetNamespaceResponse

Status Code

  • 200

    Returns a namespace, as well as any properties stored on the namespace if namespace properties are supported by the server.

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - Namespace not found

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Check if a namespace exists

Check if a namespace exists. The response does not contain a body.

HEAD /v1/{prefix}/namespaces/{namespace}

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • curl -X HEAD -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/{catalog_name}/namespaces/{namespace_name}'"

Response

Status Code

  • 204

    Success, no content

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - Namespace not found

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Drop a namsespace from the catalog

Drop a namespace from the catalog. Namespace must be empty.

DELETE /v1/{prefix}/namespaces/{namespace}

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • curl -X DELETE -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/{catalog_name}/namespaces/{namespace_name}'"

Response

Status Code

  • 200

    Success, no content

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - Namespace to delete does not exist.

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Set or remove properties on a namespace

Set and/or remove properties on a namespace. The request body specifies a list of properties to remove and a map of key value pairs to update. Properties that are not in the request are not modified or removed by this call. Server implementations are not required to support namespace properties.

POST /v1/{prefix}/namespaces/{namespace}/properties

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

Request Body

Required*
UpdateNamespacePropertiesRequest
Examples:

An update namespace properties request with both properties to remove and properties to upsert.

{
  "removals": [
    "foo",
    "bar"
  ],
  "updates": {
    "owner": "Raoul"
  }
}
  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"removals":["foo","bar"],"updates":{"owner":"Raoul"}}' "https://{region}/mds/iceberg/v1/{catalog_name}/namespaces/{namespace_name}/properties'"

Response

Response Body

UpdateNamespacePropertiesResponse

Response for namespace updates request

Status Code

  • 200

    JSON data response for a synchronous update properties request.

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - Namespace not found

  • 406

    Not Acceptable / Unsupported Operation. The server does not support this operation.

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 422

    Unprocessable Entity - A property key was included in both removals and updates

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "updated": [
    "owner"
  ],
  "removed": [
    "foo"
  ],
  "missing": [
    "bar"
  ]
}
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "The request cannot be processed as there is a key present multiple times",
    "type": "UnprocessableEntityException",
    "code": 422
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

List all table identifiers underneath a given namespace

Return all table identifiers under this namespace

GET /v1/{prefix}/namespaces/{namespace}/tables

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

Query Parameters

  • pageToken
    string

    A token used to retrieve the next page of results in a paginated response

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 -]*$, allows empty value

  • pageSize
    integer

    For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated pageSize.

    Possible values: 0 ≤ value ≤ 1000000000000000

  • curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/{catalog_name}/namespaces/{namespace_name}/tables"

Response

Response Body

ListTablesResponse

Status Code

  • 200

    A list of table identifiers

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - The namespace specified does not exist

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "identifiers": [
    {
      "namespace": [
        "namespace_name"
      ],
      "name": "table_name"
    },
    {
      "namespace": [
        "namespace_name"
      ],
      "name": "table_name"
    }
  ]
}
  • {
  "identifiers": []
}
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Create a table in the given namespace

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.

POST /v1/{prefix}/namespaces/{namespace}/tables

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

Request Body

Required*
CreateTableRequest

Request for create Table

  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"name":"string","location":"string","schema":{"type":"struct","fields":[{"id":0,"name":"string","type":["long","string","fixed[16]","decimal(10,2)"],"required":true,"doc":"string"}],"identifier-field-ids":[0]},"partition-spec":{"fields":[{"field-id":0,"source-id":0,"name":"string","transform":["identity","year","month","day","hour","bucket[256]","truncate[16]"]}]},"write-order":{"fields":[{"source-id":0,"transform":["identity","year","month","day","hour","bucket[256]","truncate[16]"],"direction":"asc","null-order":"nulls-first"}]},"stage-create":true,"properties":{"additionalProp1":"string","additionalProp2":"string","additionalProp3":"string"}}' "https://{region}/mds/iceberg/v1/{catalog_name}/namespaces/{namespace_name}/tables"

Response

Response Body

LoadTableResult

Result used when a table is successfully loaded.

The table metadata JSON is returned in the metadata field. The corresponding file location of table metadata should be returned in the metadata-location field, unless the metadata is not yet committed. For example, a create transaction may return metadata that is staged but not committed. Clients can check whether metadata has changed by comparing metadata locations after the table has been created.

The config map returns table-specific configuration for the table's resources, including its HTTP client and FileIO. For example, config may contain a specific FileIO implementation class for the table depending on its underlying storage.

The following configurations should be respected by clients:

General Configurations

  • token: Authorization bearer token to use for table requests if OAuth2 security is enabled

AWS Configurations

The following configurations should be respected when working with tables stored in AWS S3

  • client.region: region to configure client for making requests to AWS
  • s3.access-key-id: id for for credentials that provide access to the data in S3
  • s3.secret-access-key: secret for credentials that provide access to data in S3
  • s3.session-token: if present, this value should be used for as the session token
  • s3.remote-signing-enabled: if true remote signing should be performed as described in the s3-signer-open-api.yaml specification

Status Code

  • 200

    Table metadata result after creating a table

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - The namespace specified does not exist

  • 409

    Conflict - The table already exists

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The given table already exists",
    "type": "AlreadyExistsException",
    "code": 409
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Register a table in the given namespace using given metadata file location

Register a table using given metadata file location.

POST /v1/{prefix}/namespaces/{namespace}/register

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

Request Body

Required*
RegisterTableRequest

Request to Register Table

  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"name":"string","metadataLocation":"string"}' "https://{region}/mds/iceberg/v1/catalog_name/namespaces/namespace_name/register"

Response

Response Body

LoadTableResult

Result used when a table is successfully loaded.

The table metadata JSON is returned in the metadata field. The corresponding file location of table metadata should be returned in the metadata-location field, unless the metadata is not yet committed. For example, a create transaction may return metadata that is staged but not committed. Clients can check whether metadata has changed by comparing metadata locations after the table has been created.

The config map returns table-specific configuration for the table's resources, including its HTTP client and FileIO. For example, config may contain a specific FileIO implementation class for the table depending on its underlying storage.

The following configurations should be respected by clients:

General Configurations

  • token: Authorization bearer token to use for table requests if OAuth2 security is enabled

AWS Configurations

The following configurations should be respected when working with tables stored in AWS S3

  • client.region: region to configure client for making requests to AWS
  • s3.access-key-id: id for for credentials that provide access to the data in S3
  • s3.secret-access-key: secret for credentials that provide access to data in S3
  • s3.session-token: if present, this value should be used for as the session token
  • s3.remote-signing-enabled: if true remote signing should be performed as described in the s3-signer-open-api.yaml specification

Status Code

  • 200

    Table metadata result when loading a table

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - The namespace specified does not exist

  • 409

    Conflict - The table already exists

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The given table already exists",
    "type": "AlreadyExistsException",
    "code": 409
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Load a table from the catalog

Load a table from the catalog.

The response contains table metadata.

The response also contains the table's full metadata, matching the table metadata JSON file.

GET /v1/{prefix}/namespaces/{namespace}/tables/{table}

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • table
    Required*
    string

    A table name

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: sales

  • curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/catalog_name/namespaces/namespace_name/tables/table_name"

Response

Response Body

LoadTableResult

Result used when a table is successfully loaded.

The table metadata JSON is returned in the metadata field. The corresponding file location of table metadata should be returned in the metadata-location field, unless the metadata is not yet committed. For example, a create transaction may return metadata that is staged but not committed. Clients can check whether metadata has changed by comparing metadata locations after the table has been created.

The config map returns table-specific configuration for the table's resources, including its HTTP client and FileIO. For example, config may contain a specific FileIO implementation class for the table depending on its underlying storage.

The following configurations should be respected by clients:

General Configurations

  • token: Authorization bearer token to use for table requests if OAuth2 security is enabled

AWS Configurations

The following configurations should be respected when working with tables stored in AWS S3

  • client.region: region to configure client for making requests to AWS
  • s3.access-key-id: id for for credentials that provide access to the data in S3
  • s3.secret-access-key: secret for credentials that provide access to data in S3
  • s3.session-token: if present, this value should be used for as the session token
  • s3.remote-signing-enabled: if true remote signing should be performed as described in the s3-signer-open-api.yaml specification

Status Code

  • 200

    Table metadata result when loading a table

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchTableException, table to load does not exist

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given table does not exist",
    "type": "NoSuchTableException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Commit updates to a table

Commit updates to a table.

Commits have two parts, requirements and updates. Requirements are assertions that will be validated before attempting to make and commit changes. For example, assert-ref-snapshot-id will check that a named ref's snapshot ID has a certain value.

Updates are changes to make to table metadata. For example, after asserting that the current main ref is at the expected snapshot, a commit may add a new child snapshot and set the ref to the new snapshot id.

Create table transactions that are started by createTable with stage-create set to true are committed using this route. Transactions should include all changes to the table, including table initialization, like AddSchemaUpdate and SetCurrentSchemaUpdate. The assert-create requirement is used to ensure that the table was not created concurrently.

POST /v1/{prefix}/namespaces/{namespace}/tables/{table}

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • table
    Required*
    string

    A table name

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: sales

Request Body

Required*
CommitTableRequest

Commit updates to a table

  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"namespace":["accounting"],"properties":{"owner":"Hank Bendickson","storage_location":"s3a://bucket_name/accounting"}}' "https://{region}/mds/iceberg/v1/catalog_name/namespaces"

Response

Response Body

CommitTableResponse

CommitTableResponse

Status Code

  • 200

    Response used when a table is successfully updated. The table metadata JSON is returned in the metadata field. The corresponding file location of table metadata must be returned in the metadata-location field. Clients can check whether metadata has changed by comparing metadata locations.

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchTableException, table to load does not exist

  • 409

    Conflict - CommitFailedException, one or more requirements failed. The client may retry.

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 500

    An unknown server-side problem occurred; the commit state is unknown.

  • 502

    A gateway or proxy received an invalid response from the upstream server; the commit state is unknown.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 504

    A server-side gateway timeout occurred; the commit state is unknown.

  • 5XX

    A server-side problem that might not be addressable on the client.

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given table does not exist",
    "type": "NoSuchTableException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "CommitStateUnknownException",
    "code": 500
  }
}
  • {
  "error": {
    "message": "Invalid response from the upstream server",
    "type": "CommitStateUnknownException",
    "code": 502
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Gateway timed out during commit",
    "type": "CommitStateUnknownException",
    "code": 504
  }
}
  • {
  "error": {
    "message": "Bad Gateway",
    "type": "InternalServerError",
    "code": 502
  }
}

Drop a table from the catalog

Remove a table from the catalog

DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • table
    Required*
    string

    A table name

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: sales

Query Parameters

  • purgeRequested
    boolean

    Whether the user requested to purge the underlying table's data and metadata

    Default: false

  • curl -X DELETE -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/catalog_name/namespaces/namespace_name/tables/table_name"

Response

Status Code

  • 204

    Success, no content

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchTableException, Table to drop does not exist

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given table does not exist",
    "type": "NoSuchTableException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Check if a table exists

Check if a table exists within a given namespace. The response does not contain a body.

HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • table
    Required*
    string

    A table name

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: sales

  • curl -X HEAD -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/catalog_name/namespaces/namespace_name/tables/table_name"

Response

Status Code

  • 204

    Success, no content

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchTableException, Table not found

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Rename a table from its current name to a new name

Rename a table from one identifier to another. It's valid to move a table across namespaces

POST /v1/{prefix}/tables/rename

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

Request Body

Required*
RenameTableRequest

Current table identifier to rename and new table identifier to rename to

Examples:

Rename a table in the same namespace

{
  "source": {
    "namespace": [
      "accounting"
    ],
    "name": "paid"
  },
  "destination": {
    "namespace": [
      "accounting"
    ],
    "name": "owed"
  }
}
  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"source":{"namespace":["accounting"],"name":"paid"},"destination":{"namespace":["accounting"],"name":"owed"}}' "https://{region}/mds/iceberg/v1/unity_test_catalog/tables/rename

Response

Status Code

  • 204

    Success, no content

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchTableException, Table to rename does not exist - NoSuchNamespaceException, The target namespace of the new table identifier does not exist

  • 406

    Not Acceptable / Unsupported Operation. The server does not support this operation.

  • 409

    Conflict - The target identifier to rename to already exists as a table or view

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given table does not exist",
    "type": "NoSuchTableException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}
  • {
  "$ref": "#/components/examples/TableAlreadyExistsError"
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Commit updates to multiple tables in an atomic operation

Commit updates to multiple tables in an atomic operation

POST /v1/{prefix}/transactions/commit

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

Request Body

Required*
CommitTransactionRequest

Commit updates to multiple tables in an atomic operation

A commit for a single table consists of a table identifier with requirements and updates. Requirements are assertions that will be validated before attempting to make and commit changes. For example, assert-ref-snapshot-id will check that a named ref's snapshot ID has a certain value.

Updates are changes to make to table metadata. For example, after asserting that the current main ref is at the expected snapshot, a commit may add a new child snapshot and set the ref to the new snapshot id.

  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"table-changes":[{"requirements":[{"type":"assert-create"},{"type":"assert-create"}],"updates":[{"action":"<string>","uuid":"<string>"},{"action":"<string>","uuid":"<string>"}],"identifier":{"name":"<string>","namespace":["<string>","<string>"]}},{"requirements":[{"type":"assert-create"},{"type":"assert-create"}],"updates":[{"action":"<string>","uuid":"<string>"},{"action":"<string>","uuid":"<string>"}],"identifier":{"name":"<string>","namespace":["<string>","<string>"]}}]}' "https://{region}/mds/iceberg/v1/catalog_name/namespaces"

Response

Status Code

  • 204

    Success, no content

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchTableException, table to load does not exist

  • 409

    Conflict - CommitFailedException, one or more requirements failed. The client may retry.

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 500

    An unknown server-side problem occurred; the commit state is unknown.

  • 502

    A gateway or proxy received an invalid response from the upstream server; the commit state is unknown.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 504

    A server-side gateway timeout occurred; the commit state is unknown.

  • 5XX

    A server-side problem that might not be addressable on the client.

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given table does not exist",
    "type": "NoSuchTableException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "CommitStateUnknownException",
    "code": 500
  }
}
  • {
  "error": {
    "message": "Invalid response from the upstream server",
    "type": "CommitStateUnknownException",
    "code": 502
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Gateway timed out during commit",
    "type": "CommitStateUnknownException",
    "code": 504
  }
}
  • {
  "error": {
    "message": "Bad Gateway",
    "type": "InternalServerError",
    "code": 502
  }
}

List all view identifiers underneath a given namespace

Return all view identifiers under this namespace

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

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

Query Parameters

  • pageToken
    string

    A token used to retrieve the next page of results in a paginated response

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 -]*$, allows empty value

  • pageSize
    integer

    For servers that support pagination, this signals an upper bound of the number of results that a client will receive. For servers that do not support pagination, clients may receive results larger than the indicated pageSize.

    Possible values: 0 ≤ value ≤ 1000000000000000

  • curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/catalog_name/namespaces/namespace_name/views"

Response

Response Body

ListTablesResponse

Status Code

  • 200

    A list of table identifiers

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - The namespace specified does not exist

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "identifiers": [
    {
      "namespace": [
        "namespace_name"
      ],
      "name": "table_name"
    },
    {
      "namespace": [
        "namespace_name"
      ],
      "name": "table_name"
    }
  ]
}
  • {
  "identifiers": []
}
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Create a view in the given namespace

Create a view in the given namespace.

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

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

Request Body

Required*
CreateViewRequest

Request for creating view

  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"name":"restv3postman","view-version":{"version-id":1,"timestamp-ms":1727092678042,"schema-id":0,"summary":{"engine-version":"3.4.2","app-id":"local-1727085978831","engine-name":"spark","iceberg-version":"Apache Iceberg 1.5.2 (commit cbb853073e681b4075d7c8707610dceecbee3a82)"},"default-namespace":["rest_iceberg1"],"representations":[{"type":"sql","sql":"select id,age from spark_iceberg_table1view_rest007","dialect":"spark"}]},"schema":{"type":"struct","schema-id":0,"fields":[{"id":0,"name":"id","required":false,"type":"int"},{"id":1,"name":"age","required":false,"type":"int"}]},"properties":{"engine_version":"Spark 3.4.2","create_engine_version":"Spark 3.4.2","spark.query-column-names":"id,age"}}' "https://{region}/mds/iceberg/v1/catalog_name/namespaces/namespace_name/views"

Response

Response Body

LoadViewResult

Result used when a view is successfully loaded.

The view metadata JSON is returned in the metadata field. The corresponding file location of view metadata is returned in the metadata-location field. Clients can check whether metadata has changed by comparing metadata locations after the view has been created.

The config map returns view-specific configuration for the view's resources.

The following configurations should be respected by clients:

General Configurations

  • token: Authorization bearer token to use for view requests if OAuth2 security is enabled

Status Code

  • 200

    View metadata result when loading a view

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - The namespace specified does not exist

  • 409

    Conflict - The view already exists

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "metadata-location": "string",
  "metadata": {
    "view-uuid": "string",
    "format-version": 1,
    "location": "string",
    "current-version-id": 0,
    "versions": [
      {
        "version-id": 0,
        "timestamp-ms": 0,
        "schema-id": 0,
        "summary": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "representations": [
          {
            "type": "string",
            "sql": "string",
            "dialect": "string"
          }
        ],
        "default-catalog": "string",
        "default-namespace": [
          "accounting",
          "tax"
        ]
      }
    ],
    "version-log": [
      {
        "version-id": 0,
        "timestamp-ms": 0
      }
    ],
    "schemas": [
      {
        "type": "struct",
        "fields": [
          {
            "id": 0,
            "name": "string",
            "type": [
              "long",
              "string",
              "fixed[16]",
              "decimal(10,2)"
            ],
            "required": true,
            "doc": "string"
          }
        ],
        "schema-id": 0,
        "identifier-field-ids": [
          0
        ]
      }
    ],
    "properties": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "config": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The given view already exists",
    "type": "AlreadyExistsException",
    "code": 409
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Load a view from the catalog

Load a view from the catalog.

The response contains both view metadata.

The response also contains the view's full metadata, matching the view metadata JSON file.

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

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • view
    Required*
    string

    A view name

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 -]*$

    Example: sales

  • curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/catalog_name/namespaces/namespace_name/views/view_name"

Response

Response Body

LoadViewResult

Result used when a view is successfully loaded.

The view metadata JSON is returned in the metadata field. The corresponding file location of view metadata is returned in the metadata-location field. Clients can check whether metadata has changed by comparing metadata locations after the view has been created.

The config map returns view-specific configuration for the view's resources.

The following configurations should be respected by clients:

General Configurations

  • token: Authorization bearer token to use for view requests if OAuth2 security is enabled

Status Code

  • 200

    View metadata result when loading a view

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchViewException, view to load does not exist

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "metadata-location": "string",
  "metadata": {
    "view-uuid": "string",
    "format-version": 1,
    "location": "string",
    "current-version-id": 0,
    "versions": [
      {
        "version-id": 0,
        "timestamp-ms": 0,
        "schema-id": 0,
        "summary": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "representations": [
          {
            "type": "string",
            "sql": "string",
            "dialect": "string"
          }
        ],
        "default-catalog": "string",
        "default-namespace": [
          "accounting",
          "tax"
        ]
      }
    ],
    "version-log": [
      {
        "version-id": 0,
        "timestamp-ms": 0
      }
    ],
    "schemas": [
      {
        "type": "struct",
        "fields": [
          {
            "id": 0,
            "name": "string",
            "type": [
              "long",
              "string",
              "fixed[16]",
              "decimal(10,2)"
            ],
            "required": true,
            "doc": "string"
          }
        ],
        "schema-id": 0,
        "identifier-field-ids": [
          0
        ]
      }
    ],
    "properties": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "config": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given view does not exist",
    "type": "NoSuchViewException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Replace a view

Commit updates to a view.

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

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • view
    Required*
    string

    A view name

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 -]*$

    Example: sales

Request Body

Required*
CommitViewRequest

Request for commit views

  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"namespace":["accounting"],"properties":{"owner":"Hank Bendickson","storage_location":"s3a://bucket_name/accounting"}}' "https://{region}/mds/iceberg/v1/catalog_name/namespaces"

Response

Response Body

LoadViewResult

Result used when a view is successfully loaded.

The view metadata JSON is returned in the metadata field. The corresponding file location of view metadata is returned in the metadata-location field. Clients can check whether metadata has changed by comparing metadata locations after the view has been created.

The config map returns view-specific configuration for the view's resources.

The following configurations should be respected by clients:

General Configurations

  • token: Authorization bearer token to use for view requests if OAuth2 security is enabled

Status Code

  • 200

    View metadata result when loading a view

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchViewException, view to load does not exist

  • 409

    Conflict - CommitFailedException. The client may retry.

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 500

    An unknown server-side problem occurred; the commit state is unknown.

  • 502

    A gateway or proxy received an invalid response from the upstream server; the commit state is unknown.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 504

    A server-side gateway timeout occurred; the commit state is unknown.

  • 5XX

    A server-side problem that might not be addressable on the client.

Example responses
  • {
  "metadata-location": "string",
  "metadata": {
    "view-uuid": "string",
    "format-version": 1,
    "location": "string",
    "current-version-id": 0,
    "versions": [
      {
        "version-id": 0,
        "timestamp-ms": 0,
        "schema-id": 0,
        "summary": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "representations": [
          {
            "type": "string",
            "sql": "string",
            "dialect": "string"
          }
        ],
        "default-catalog": "string",
        "default-namespace": [
          "accounting",
          "tax"
        ]
      }
    ],
    "version-log": [
      {
        "version-id": 0,
        "timestamp-ms": 0
      }
    ],
    "schemas": [
      {
        "type": "struct",
        "fields": [
          {
            "id": 0,
            "name": "string",
            "type": [
              "long",
              "string",
              "fixed[16]",
              "decimal(10,2)"
            ],
            "required": true,
            "doc": "string"
          }
        ],
        "schema-id": 0,
        "identifier-field-ids": [
          0
        ]
      }
    ],
    "properties": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "config": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given view does not exist",
    "type": "NoSuchViewException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "CommitStateUnknownException",
    "code": 500
  }
}
  • {
  "error": {
    "message": "Invalid response from the upstream server",
    "type": "CommitStateUnknownException",
    "code": 502
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Gateway timed out during commit",
    "type": "CommitStateUnknownException",
    "code": 504
  }
}
  • {
  "error": {
    "message": "Bad Gateway",
    "type": "InternalServerError",
    "code": 502
  }
}

Drop a view from the catalog

Remove a view from the catalog

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

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • view
    Required*
    string

    A view name

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 -]*$

    Example: sales

  • curl -X DELETE -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/catalog_name/namespaces/namespace_name/views/view_name"

Response

Status Code

  • 204

    Success, no content

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchViewException, view to drop does not exist

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given view does not exist",
    "type": "NoSuchViewException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Check if a view exists

Check if a view exists within a given namespace. This request does not return a response body.

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

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

  • namespace
    Required*
    string

    A namespace identifier as a single string. Multipart namespace not supported.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

    Example: accounting

  • view
    Required*
    string

    A view name

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 -]*$

    Example: sales

  • curl -X HEAD -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://{region}/mds/iceberg/v1/catalog_name/namespaces/namespace_name/views/view_name"

Response

Status Code

  • 204

    Success, no content

  • 400

    Bad Request

  • 401

    Unauthorized

  • 404

    Not Found

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Rename a view from its current name to a new name

Rename a view from one identifier to another. It's valid to move a view across namespaces

POST /v1/{prefix}/views/rename

Request

Path Parameters

  • prefix
    Required*
    string

    A prefix should be passs as wxd iceberg type catalog_name in the path

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z0-9 ]*$

Request Body

Required*
RenameTableRequest

Current view identifier to rename and new view identifier to rename to

Examples:

Rename a view in the same namespace

{
  "source": {
    "namespace": [
      "accounting"
    ],
    "name": "paid-view"
  },
  "destination": {
    "namespace": [
      "accounting"
    ],
    "name": "owed-view"
  }
}
  • curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"destination":{"name":"restv2renamedinpostman","namespace":["accounting"]},"source":{"name":"restv3postman","namespace":["accounting"]}}' "https://{region}/mds/iceberg/v1/catalog_name/views/rename"

Response

Status Code

  • 204

    Success, no content

  • 400

    Indicates 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.

  • 401

    Unauthorized. Authentication is required and has failed or has not yet been provided.

  • 403

    Forbidden. Authenticated user does not have the necessary permissions.

  • 404

    Not Found - NoSuchViewException, view to rename does not exist - NoSuchNamespaceException, The target namespace of the new identifier does not exist

  • 406

    Not Acceptable / Unsupported Operation. The server does not support this operation.

  • 409

    Conflict - The target identifier to rename to already exists as a table or view

  • 419

    Credentials have timed out. If possible, the client should refresh credentials and retry.

  • 503

    The service is not ready to handle the request. The client should wait and retry.

    The service may additionally send a Retry-After header to indicate when to retry.

  • 5XX

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

Example responses
  • {
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}
  • {
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}
  • {
  "error": {
    "message": "The given view does not exist",
    "type": "NoSuchViewException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The given namespace does not exist",
    "type": "NoSuchNamespaceException",
    "code": 404
  }
}
  • {
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}
  • {
  "$ref": "#/components/examples/ViewAlreadyExistsError"
}
  • {
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}
  • {
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}
  • {
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}
id=curlclassName=tab-item-selected