Test an existing catalog connection

POST 
/metalakes/:metalake/catalogs/:catalog/testConnection

Runs the provider's smallest meaningful, read-only catalog-level operation using the catalog's stored configuration and effective credentials. Optional proposed catalog changes are applied to a temporary effective configuration for this probe and are not persisted. This fail-fast preflight surfaces configuration and connectivity failures before regular catalog operations, but does not guarantee that every object-level or mutating operation will succeed. Fileset catalogs test all catalog-level location and location-* targets. Model and Generic catalogs do not support connection testing. Expected test failures are returned as application error codes in an HTTP 200 response. When authorization is enabled, testing with the stored configuration requires the same access as loading the catalog, and testing with proposed changes requires owning the metalake or the catalog, the same as altering it. Callers without that access receive an HTTP 403 response.

Request

Path Parameters

metalake stringrequired

The name of the metalake

catalog stringrequired

The name of the catalog

application/json

Body

Optional catalog changes to apply only to this connection test

updates

object[]

required

Array [

oneOf

RenameCatalogRequest

@type stringrequired

Possible values: [rename]

newName stringrequired

The new name of the catalog

UpdateCatalogCommentRequest

@type stringrequired

Possible values: [updateComment]

newComment stringrequired

The new comment of the catalog

SetCatalogPropertyRequest

@type stringrequired

Possible values: [setProperty]

property stringrequired

The property to set

value stringrequired

The value to set

RemoveCatalogPropertyRequest

@type stringrequired

Possible values: [removeProperty]

property stringrequired

The property to remove

]

Responses

200

Connection test completed, including expected test failures

application/vnd.gravitino.v1+json

Schema

Schema

code int32required

Application status code; 0 indicates success

type string

Internal exception type when the test fails

message string

Sanitized failure message

Example (from schema)

{
  "code": 0,
  "type": "string",
  "message": "string"
}

TestConnectionSuccess

{
  "code": 0
}

TestConnectionFailed

{
  "code": 1007,
  "type": "ConnectionFailedException",
  "message": "Failed to test Fileset catalog connection: location (access denied)"
}

InvalidProbeTarget

{
  "code": 1001,
  "type": "IllegalArgumentException",
  "message": "Fileset catalog has no catalog-level location to test"
}

TestConnectionNotSupported

{
  "code": 1006,
  "type": "UnsupportedOperationException",
  "message": "Model catalogs do not define an external catalog-level connection probe"
}

CatalogNotFound

{
  "code": 1003,
  "type": "NoSuchCatalogException",
  "message": "Catalog my_metalake.my_catalog does not exist"
}

CatalogDisabled

{
  "code": 1009,
  "type": "CatalogNotInUseException",
  "message": "Catalog my_metalake.my_catalog is not in use"
}

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/vnd.gravitino.v1+json

Schema

Schema

code integerrequired

Possible values: >= 1000 and <= 1100

HTTP response code

type stringrequired

Internal type definition of the error

message stringrequired

A human-readable message

stack string[]

Example (from schema)

{
  "code": 1002,
  "type": "string",
  "message": "string",
  "stack": [
    "string"
  ]
}

Example

{
  "code": 1003,
  "type": "BadRequestException",
  "message": "Malformed request"
}

403

Forbidden - The caller cannot load the catalog, or tests proposed changes without owning the metalake or the catalog

application/vnd.gravitino.v1+json

Schema

Schema

code integerrequired

Possible values: >= 1000 and <= 1100

HTTP response code

type stringrequired

Internal type definition of the error

message stringrequired

A human-readable message

stack string[]

Example (from schema)

{
  "code": 1002,
  "type": "string",
  "message": "string",
  "stack": [
    "string"
  ]
}

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/vnd.gravitino.v1+json

Schema

Schema

code integerrequired

Possible values: >= 1000 and <= 1100

HTTP response code

type stringrequired

Internal type definition of the error

message stringrequired

A human-readable message

stack string[]

Example (from schema)

{
  "code": 1002,
  "type": "string",
  "message": "string",
  "stack": [
    "string"
  ]
}

Example

{
  "code": 1002,
  "type": "RuntimeException",
  "message": "Internal Server Error",
  "stack": [
    "java.lang.RuntimeException: Internal Server Error"
  ]
}

Loading...