List all catalog configuration settings

GET 
/v1/config

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.

For example, a default configuration property might set the size of the client pool, which can be replaced with a client-specific setting. An override might be used to set the warehouse location, which is stored on the server rather than in client configuration.

Common catalog configuration settings are documented at https://iceberg.apache.org/docs/latest/configuration/#catalog-properties

The catalog configuration also holds an optional endpoints field that contains information about the endpoints supported by the server. If a server does not send the endpoints field, a default set of endpoints is assumed:

• GET /v1/{prefix}/namespaces
• POST /v1/{prefix}/namespaces
• GET /v1/{prefix}/namespaces/{namespace}
• DELETE /v1/{prefix}/namespaces/{namespace}
• POST /v1/{prefix}/namespaces/{namespace}/properties
• GET /v1/{prefix}/namespaces/{namespace}/tables
• POST /v1/{prefix}/namespaces/{namespace}/tables
• GET /v1/{prefix}/namespaces/{namespace}/tables/{table}
• POST /v1/{prefix}/namespaces/{namespace}/tables/{table}
• DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}
• POST /v1/{prefix}/namespaces/{namespace}/register
• POST /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics
• POST /v1/{prefix}/tables/rename
• POST /v1/{prefix}/transactions/commit

Request

Query Parameters

warehouse string

Warehouse location or identifier to request from the service

Responses

200

Server specified configuration values.

application/json

Schema

Schema

overrides

object

required

Properties that should be used to override client configuration; applied after defaults and client configuration.

property name* string

defaults

object

required

Properties that should be used as default configuration; applied before client configuration.

property name* string
endpoints string[]

A list of endpoints that the server supports. The format of each endpoint must be " ". The HTTP verb and the resource path must be separated by a space character.

idempotency-key-lifetime duration

Client reuse window for an Idempotency-Key (ISO-8601 duration, e.g., PT30M, PT24H). Interpreted as the maximum time from the first submission using a key to the last retry during which a client may reuse that key. Servers SHOULD accept retries for at least this duration and MAY include a grace period to account for delays/clock skew. Clients SHOULD NOT reuse an Idempotency-Key after this window elapses; they SHOULD generate a new key for any subsequent attempt. Presence of this field indicates the server supports Idempotency-Key semantics for mutation endpoints. If absent, clients MUST assume idempotency is not supported.

Example (from schema)

{
  "overrides": {},
  "defaults": {},
  "endpoints": [
    "GET /v1/{prefix}/namespaces/{namespace}",
    "GET /v1/{prefix}/namespaces",
    "POST /v1/{prefix}/namespaces",
    "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "GET /v1/{prefix}/namespaces/{namespace}/views/{view}"
  ],
  "idempotency-key-lifetime": "PT30M"
}

Example

{
  "overrides": {
    "warehouse": "s3://bucket/warehouse/"
  },
  "defaults": {
    "clients": "4"
  },
  "idempotency-key-lifetime": "PT30M",
  "endpoints": [
    "GET /v1/{prefix}/namespaces/{namespace}",
    "GET /v1/{prefix}/namespaces",
    "POST /v1/{prefix}/namespaces",
    "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "GET /v1/{prefix}/namespaces/{namespace}/views/{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.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}

401

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

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}

403

Forbidden. Authenticated user does not have the necessary permissions.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}

404

Not Found - Warehouse provided in the warehouse query parameter is not found.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

NoSuchWarehouseExample

The requested warehouse does not exist

{
  "error": {
    "message": "The given warehouse does not exist",
    "type": "NoSuchWarehouseException",
    "code": 404
  }
}

419

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

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}

503

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

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}

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.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Loading...