REST API for Oracle AI Data Catalog

List all catalog configuration settings

get

{scheme}://{host}/{basePath}/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

There's no request body for this operation.

Response

Supported Media Types

application/json

200 Response

Server specified configuration values.

Root Schema : CatalogConfig

Type: object

Server-provided configuration for the catalog.

Show Source

defaults(required): object defaults

Additional Properties Allowed: additionalProperties

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

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: string (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: PT30M
overrides(required): object overrides

Additional Properties Allowed: additionalProperties

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

{
    "type":"object",
    "description":"Server-provided configuration for the catalog.",
    "required":[
        "defaults",
        "overrides"
    ],
    "properties":{
        "overrides":{
            "type":"object",
            "additionalProperties":{
                "type":"string"
            },
            "description":"Properties that should be used to override client configuration; applied after defaults and client configuration."
        },
        "defaults":{
            "type":"object",
            "additionalProperties":{
                "type":"string"
            },
            "description":"Properties that should be used as default configuration; applied before client configuration."
        },
        "endpoints":{
            "type":"array",
            "items":{
                "type":"string"
            },
            "description":"A list of endpoints that the server supports. The format of each endpoint must be \"<HTTP verb> <resource path from OpenAPI REST spec>\". The HTTP verb and the resource path must be separated by a space character.",
            "example":[
                "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":{
            "type":"string",
            "format":"duration",
            "description":"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":"PT30M"
        }
    }
}

Nested Schema : defaults

Type: object

Additional Properties Allowed

Show Source

string

{
    "type":"object",
    "additionalProperties":{
        "type":"string"
    },
    "description":"Properties that should be used as default configuration; applied before client configuration."
}

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

Nested Schema : endpoints

Type: array

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.

Show Source

Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    },
    "description":"A list of endpoints that the server supports. The format of each endpoint must be \"<HTTP verb> <resource path from OpenAPI REST spec>\". The HTTP verb and the resource path must be separated by a space character.",
    "example":[
        "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}"
    ]
}

Example:

[
    "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}"
]

Nested Schema : overrides

Type: object

Additional Properties Allowed

Show Source

string

{
    "type":"object",
    "additionalProperties":{
        "type":"string"
    },
    "description":"Properties that should be used to override client configuration; applied after defaults and client configuration."
}

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

400 Response

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.

Root Schema : IcebergErrorResponse

Type: object

JSON wrapper for all error responses (non-2xx)

Show Source

error(required): object ErrorModel

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

{
    "description":"JSON wrapper for all error responses (non-2xx)",
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "$ref":"#/components/schemas/ErrorModel"
        }
    },
    "additionalProperties":false,
    "example":{
        "error":{
            "message":"The server does not support this operation",
            "type":"UnsupportedOperationException",
            "code":406
        }
    }
}

Example:

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

Nested Schema : ErrorModel

Type: object

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

Show Source

code(required): integer

Minimum Value: 400

Maximum Value: 600

HTTP response code

Example: 404
message(required): string

Human-readable error message
stack: array stack
type(required): string

Internal type definition of the error

Example: NoSuchNamespaceException

{
    "type":"object",
    "description":"JSON error payload returned in a response with further details on the error",
    "required":[
        "message",
        "type",
        "code"
    ],
    "properties":{
        "message":{
            "type":"string",
            "description":"Human-readable error message"
        },
        "type":{
            "type":"string",
            "description":"Internal type definition of the error",
            "example":"NoSuchNamespaceException"
        },
        "code":{
            "type":"integer",
            "minimum":400,
            "maximum":600,
            "description":"HTTP response code",
            "example":404
        },
        "stack":{
            "type":"array",
            "items":{
                "type":"string"
            }
        }
    }
}

Nested Schema : stack

Type: array

Show Source

Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    }
}

401 Response

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.

Root Schema : IcebergErrorResponse

Type: object

JSON wrapper for all error responses (non-2xx)

Show Source

error(required): object ErrorModel

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

{
    "description":"JSON wrapper for all error responses (non-2xx)",
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "$ref":"#/components/schemas/ErrorModel"
        }
    },
    "additionalProperties":false,
    "example":{
        "error":{
            "message":"The server does not support this operation",
            "type":"UnsupportedOperationException",
            "code":406
        }
    }
}

Example:

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

Nested Schema : ErrorModel

Type: object

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

Show Source

code(required): integer

Minimum Value: 400

Maximum Value: 600

HTTP response code

Example: 404
message(required): string

Human-readable error message
stack: array stack
type(required): string

Internal type definition of the error

Example: NoSuchNamespaceException

{
    "type":"object",
    "description":"JSON error payload returned in a response with further details on the error",
    "required":[
        "message",
        "type",
        "code"
    ],
    "properties":{
        "message":{
            "type":"string",
            "description":"Human-readable error message"
        },
        "type":{
            "type":"string",
            "description":"Internal type definition of the error",
            "example":"NoSuchNamespaceException"
        },
        "code":{
            "type":"integer",
            "minimum":400,
            "maximum":600,
            "description":"HTTP response code",
            "example":404
        },
        "stack":{
            "type":"array",
            "items":{
                "type":"string"
            }
        }
    }
}

Nested Schema : stack

Type: array

Show Source

Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    }
}

403 Response

Forbidden. Authenticated user does not have the necessary permissions.

Root Schema : IcebergErrorResponse

Type: object

JSON wrapper for all error responses (non-2xx)

Show Source

error(required): object ErrorModel

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

{
    "description":"JSON wrapper for all error responses (non-2xx)",
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "$ref":"#/components/schemas/ErrorModel"
        }
    },
    "additionalProperties":false,
    "example":{
        "error":{
            "message":"The server does not support this operation",
            "type":"UnsupportedOperationException",
            "code":406
        }
    }
}

Example:

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

Nested Schema : ErrorModel

Type: object

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

Show Source

code(required): integer

Minimum Value: 400

Maximum Value: 600

HTTP response code

Example: 404
message(required): string

Human-readable error message
stack: array stack
type(required): string

Internal type definition of the error

Example: NoSuchNamespaceException

{
    "type":"object",
    "description":"JSON error payload returned in a response with further details on the error",
    "required":[
        "message",
        "type",
        "code"
    ],
    "properties":{
        "message":{
            "type":"string",
            "description":"Human-readable error message"
        },
        "type":{
            "type":"string",
            "description":"Internal type definition of the error",
            "example":"NoSuchNamespaceException"
        },
        "code":{
            "type":"integer",
            "minimum":400,
            "maximum":600,
            "description":"HTTP response code",
            "example":404
        },
        "stack":{
            "type":"array",
            "items":{
                "type":"string"
            }
        }
    }
}

Nested Schema : stack

Type: array

Show Source

Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    }
}

419 Response

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.

Root Schema : IcebergErrorResponse

Type: object

JSON wrapper for all error responses (non-2xx)

Show Source

error(required): object ErrorModel

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

{
    "description":"JSON wrapper for all error responses (non-2xx)",
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "$ref":"#/components/schemas/ErrorModel"
        }
    },
    "additionalProperties":false,
    "example":{
        "error":{
            "message":"The server does not support this operation",
            "type":"UnsupportedOperationException",
            "code":406
        }
    }
}

Example:

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

Nested Schema : ErrorModel

Type: object

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

Show Source

code(required): integer

Minimum Value: 400

Maximum Value: 600

HTTP response code

Example: 404
message(required): string

Human-readable error message
stack: array stack
type(required): string

Internal type definition of the error

Example: NoSuchNamespaceException

{
    "type":"object",
    "description":"JSON error payload returned in a response with further details on the error",
    "required":[
        "message",
        "type",
        "code"
    ],
    "properties":{
        "message":{
            "type":"string",
            "description":"Human-readable error message"
        },
        "type":{
            "type":"string",
            "description":"Internal type definition of the error",
            "example":"NoSuchNamespaceException"
        },
        "code":{
            "type":"integer",
            "minimum":400,
            "maximum":600,
            "description":"HTTP response code",
            "example":404
        },
        "stack":{
            "type":"array",
            "items":{
                "type":"string"
            }
        }
    }
}

Nested Schema : stack

Type: array

Show Source

Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    }
}

503 Response

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.

Root Schema : IcebergErrorResponse

Type: object

JSON wrapper for all error responses (non-2xx)

Show Source

error(required): object ErrorModel

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

{
    "description":"JSON wrapper for all error responses (non-2xx)",
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "$ref":"#/components/schemas/ErrorModel"
        }
    },
    "additionalProperties":false,
    "example":{
        "error":{
            "message":"The server does not support this operation",
            "type":"UnsupportedOperationException",
            "code":406
        }
    }
}

Example:

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

Nested Schema : ErrorModel

Type: object

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

Show Source

code(required): integer

Minimum Value: 400

Maximum Value: 600

HTTP response code

Example: 404
message(required): string

Human-readable error message
stack: array stack
type(required): string

Internal type definition of the error

Example: NoSuchNamespaceException

{
    "type":"object",
    "description":"JSON error payload returned in a response with further details on the error",
    "required":[
        "message",
        "type",
        "code"
    ],
    "properties":{
        "message":{
            "type":"string",
            "description":"Human-readable error message"
        },
        "type":{
            "type":"string",
            "description":"Internal type definition of the error",
            "example":"NoSuchNamespaceException"
        },
        "code":{
            "type":"integer",
            "minimum":400,
            "maximum":600,
            "description":"HTTP response code",
            "example":404
        },
        "stack":{
            "type":"array",
            "items":{
                "type":"string"
            }
        }
    }
}

Nested Schema : stack

Type: array

Show Source

Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    }
}

5XX Response

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.

Root Schema : IcebergErrorResponse

Type: object

JSON wrapper for all error responses (non-2xx)

Show Source

error(required): object ErrorModel

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

{
    "description":"JSON wrapper for all error responses (non-2xx)",
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "$ref":"#/components/schemas/ErrorModel"
        }
    },
    "additionalProperties":false,
    "example":{
        "error":{
            "message":"The server does not support this operation",
            "type":"UnsupportedOperationException",
            "code":406
        }
    }
}

Example:

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

Nested Schema : ErrorModel

Type: object

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

Show Source

code(required): integer

Minimum Value: 400

Maximum Value: 600

HTTP response code

Example: 404
message(required): string

Human-readable error message
stack: array stack
type(required): string

Internal type definition of the error

Example: NoSuchNamespaceException

{
    "type":"object",
    "description":"JSON error payload returned in a response with further details on the error",
    "required":[
        "message",
        "type",
        "code"
    ],
    "properties":{
        "message":{
            "type":"string",
            "description":"Human-readable error message"
        },
        "type":{
            "type":"string",
            "description":"Internal type definition of the error",
            "example":"NoSuchNamespaceException"
        },
        "code":{
            "type":"integer",
            "minimum":400,
            "maximum":600,
            "description":"HTTP response code",
            "example":404
        },
        "stack":{
            "type":"array",
            "items":{
                "type":"string"
            }
        }
    }
}

Nested Schema : stack

Type: array

Show Source

Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    }
}