Connection

View as Markdown

Get a connectionGET /api/2.1/unity-catalog/connections/{name_arg}List connectionsGET /api/2.1/unity-catalog/connectionsCreate a connectionPOST /api/2.1/unity-catalog/connectionsUpdate a connectionPATCH /api/2.1/unity-catalog/connections/{name_arg}Delete a connectionDELETE /api/2.1/unity-catalog/connections/{name_arg}

ConnectionInfo object

namestring

Name of the connection.

connection_typestring

The type of connection.

Values:

Show 32 possible values

• UNKNOWN_CONNECTION_TYPE
• MYSQL
• POSTGRESQL
• SNOWFLAKE
• REDSHIFT
• SQLDW
• SQLSERVER
• DATABRICKS
• SALESFORCE
• BIGQUERY
• NETSUITE
• WORKDAY_RAAS
• HIVE_METASTORE
• GA4_RAW_DATA
• SERVICENOW
• SALESFORCE_DATA_CLOUD
• GLUE
• ORACLE
• TERADATA
• HTTP
• POWER_BI
• DYNAMICS365
• CONFLUENCE
• JDBC Public Preview
• META_MARKETING Beta
• HUBSPOT
• ZENDESK
• AWS_SECRETS_MANAGER Beta
• AZURE_KEY_VAULT Beta
• GITHUB Beta
• OUTLOOK Beta
• SMARTSHEET Beta

ownerstring

Username of current owner of the connection.

read_onlyboolean

If the connection is read only.

commentstring

User-provided free-form text description.

environment_settingsobjectPublic Preview

[Create,Update:OPT] Connection environment settings as EnvironmentSettings object.

Show child attributesHide child attributes

java_dependenciesarray of stringPublic Preview

environment_versionstringPublic Preview

full_namestring

Full name of connection.

urlstring

URL of the remote data source, extracted from options.

credential_typestring

The type of credential.

Values:

Show 16 possible values

• UNKNOWN_CREDENTIAL_TYPE
• USERNAME_PASSWORD
• OAUTH_U2M
• OAUTH_M2M
• OAUTH_REFRESH_TOKEN
• OAUTH_ACCESS_TOKEN
• OAUTH_RESOURCE_OWNER_PASSWORD
• SERVICE_CREDENTIAL
• BEARER_TOKEN
• OIDC_TOKEN
• PEM_PRIVATE_KEY
• OAUTH_U2M_MAPPING
• ANY_STATIC_CREDENTIAL
• OAUTH_MTLS
• SSWS_TOKEN
• EDGEGRID_AKAMAI

connection_idstring

Unique identifier of the Connection.

metastore_idstring

Unique identifier of parent metastore.

created_atint64

Time at which this connection was created, in epoch milliseconds.

created_bystring

Username of connection creator.

updated_atint64

Time at which this connection was updated, in epoch milliseconds.

updated_bystring

Username of user who last modified connection.

securable_typestring

The type of Unity Catalog securable.

Default: CONNECTION

Values:

Show 21 possible values

• CATALOG
• SCHEMA
• TABLE
• STORAGE_CREDENTIAL
• EXTERNAL_LOCATION
• FUNCTION
• SHARE
• PROVIDER
• RECIPIENT
• CLEAN_ROOM
• METASTORE
• PIPELINE
• VOLUME
• CONNECTION
• CREDENTIAL
• EXTERNAL_METADATA
• STAGING_TABLE
• MODEL Beta
• MODEL_SERVICE Beta
• MCP_SERVICE Beta
• MODEL_PROVIDER_SERVICE Beta

provisioning_infoobject

Show child attributesHide child attributes

statestring

The provisioning state of the resource.

Values:

• STATE_UNSPECIFIED
• PROVISIONING
• ACTIVE
• FAILED
• DELETING
• UPDATING
• DEGRADED

optionsobject

A map of key-value properties attached to the securable.

propertiesobject

A map of key-value properties attached to the securable.

View as Markdown

The ConnectionInfo object

{
  "name": "string",
  "connection_type": "UNKNOWN_CONNECTION_TYPE",
  "owner": "string",
  "read_only": true,
  "comment": "string",
  "environment_settings": {
    "java_dependencies": [
      "string"
    ],
    "environment_version": "string"
  },
  "full_name": "string",
  "url": "string",
  "credential_type": "UNKNOWN_CREDENTIAL_TYPE",
  "connection_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "securable_type": "CONNECTION",
  "provisioning_info": {
    "state": "PROVISIONING"
  },
  "options": {},
  "properties": {}
}

Get a connection GA

GET /api/2.1/unity-catalog/connections/{name_arg}

Gets a connection from it's name.

API scopes: unity-catalog

Parameters

name_argstringRequiredpath

Name of the connection.

Response

Returns the ConnectionInfo object.

View as Markdown

Response

{
  "name": "string",
  "connection_type": "UNKNOWN_CONNECTION_TYPE",
  "owner": "string",
  "read_only": true,
  "comment": "string",
  "environment_settings": {
    "java_dependencies": [
      "string"
    ],
    "environment_version": "string"
  },
  "full_name": "string",
  "url": "string",
  "credential_type": "UNKNOWN_CREDENTIAL_TYPE",
  "connection_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "securable_type": "CONNECTION",
  "provisioning_info": {
    "state": "PROVISIONING"
  },
  "options": {},
  "properties": {}
}

List connections GA

GET /api/2.1/unity-catalog/connections

List all connections.

NOTE: we recommend using max_results=0 to use the paginated version of this API. Unpaginated calls will be deprecated soon.

PAGINATION BEHAVIOR: When using pagination (max_results >= 0), a page may contain zero results while still providing a next_page_token. Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

API scopes: unity-catalog

Parameters

max_resultsint32<= 1000query

Maximum number of connections to return.

• If not set, all connections are returned (not recommended).
• when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
• when set to 0, the page length is set to a server configured value (recommended);
• when set to a value less than 0, an invalid parameter error is returned;

page_tokenstringquery

Opaque pagination token to go to next page based on previous query.

parentstringquery

Optional. Parent schema filter for listing schema-level connections, in format "schemas/{catalog}.{schema}".

Response

Returns a list of ConnectionInfo objects.

View as Markdown

Response

{
  "connections": [
    {
      "name": "string",
      "connection_type": "UNKNOWN_CONNECTION_TYPE",
      "owner": "string",
      "read_only": true,
      "comment": "string",
      "environment_settings": {},
      "full_name": "string",
      "url": "string",
      "credential_type": "UNKNOWN_CREDENTIAL_TYPE",
      "connection_id": "string",
      "metastore_id": "string",
      "created_at": 0,
      "created_by": "string",
      "updated_at": 0,
      "updated_by": "string",
      "securable_type": "CONNECTION",
      "provisioning_info": {},
      "options": {},
      "properties": {}
    }
  ],
  "next_page_token": "string"
}

Create a connection GA

POST /api/2.1/unity-catalog/connections

Creates a new connection

Creates a new connection to an external data source. It allows users to specify connection details and configurations for interaction with the external server.

API scopes: unity-catalog

AWS

Creates a new connection

Creates a new connection to an external data source. It allows users to specify connection details and configurations for interaction with the external server.

Supported data sources for connections are listed here.

Azure

Creates a new connection

Creates a new connection to an external data source. It allows users to specify connection details and configurations for interaction with the external server.

Supported data sources for connections are listed here.

GCP

Creates a new connection

Creates a new connection to an external data source. It allows users to specify connection details and configurations for interaction with the external server.

Supported data sources for connections are listed here.

Request body

parentstring

Parent schema for schema-level connections, in format "schemas/{catalog}.{schema}". Absent for metastore-level (L1) connections.

namestring

Name of the connection.

connection_typestring

The type of connection.

Values:

Show 32 possible values

• UNKNOWN_CONNECTION_TYPE
• MYSQL
• POSTGRESQL
• SNOWFLAKE
• REDSHIFT
• SQLDW
• SQLSERVER
• DATABRICKS
• SALESFORCE
• BIGQUERY
• NETSUITE
• WORKDAY_RAAS
• HIVE_METASTORE
• GA4_RAW_DATA
• SERVICENOW
• SALESFORCE_DATA_CLOUD
• GLUE
• ORACLE
• TERADATA
• HTTP
• POWER_BI
• DYNAMICS365
• CONFLUENCE
• JDBC Public Preview
• META_MARKETING Beta
• HUBSPOT
• ZENDESK
• AWS_SECRETS_MANAGER Beta
• AZURE_KEY_VAULT Beta
• GITHUB Beta
• OUTLOOK Beta
• SMARTSHEET Beta

ownerstring

Username of current owner of the connection.

read_onlyboolean

If the connection is read only.

commentstring

User-provided free-form text description.

environment_settingsobjectPublic Preview

[Create,Update:OPT] Connection environment settings as EnvironmentSettings object.

Show child attributesHide child attributes

java_dependenciesarray of stringPublic Preview

environment_versionstringPublic Preview

full_namestring

Full name of connection.

urlstring

URL of the remote data source, extracted from options.

credential_typestring

The type of credential.

Values:

Show 16 possible values

• UNKNOWN_CREDENTIAL_TYPE
• USERNAME_PASSWORD
• OAUTH_U2M
• OAUTH_M2M
• OAUTH_REFRESH_TOKEN
• OAUTH_ACCESS_TOKEN
• OAUTH_RESOURCE_OWNER_PASSWORD
• SERVICE_CREDENTIAL
• BEARER_TOKEN
• OIDC_TOKEN
• PEM_PRIVATE_KEY
• OAUTH_U2M_MAPPING
• ANY_STATIC_CREDENTIAL
• OAUTH_MTLS
• SSWS_TOKEN
• EDGEGRID_AKAMAI

connection_idstring

Unique identifier of the Connection.

metastore_idstring

Unique identifier of parent metastore.

created_atint64

Time at which this connection was created, in epoch milliseconds.

created_bystring

Username of connection creator.

updated_atint64

Time at which this connection was updated, in epoch milliseconds.

updated_bystring

Username of user who last modified connection.

securable_typestring

The type of Unity Catalog securable.

Default: CONNECTION

Values:

Show 21 possible values

• CATALOG
• SCHEMA
• TABLE
• STORAGE_CREDENTIAL
• EXTERNAL_LOCATION
• FUNCTION
• SHARE
• PROVIDER
• RECIPIENT
• CLEAN_ROOM
• METASTORE
• PIPELINE
• VOLUME
• CONNECTION
• CREDENTIAL
• EXTERNAL_METADATA
• STAGING_TABLE
• MODEL Beta
• MODEL_SERVICE Beta
• MCP_SERVICE Beta
• MODEL_PROVIDER_SERVICE Beta

provisioning_infoobject

Show child attributesHide child attributes

statestring

The provisioning state of the resource.

Values:

• STATE_UNSPECIFIED
• PROVISIONING
• ACTIVE
• FAILED
• DELETING
• UPDATING
• DEGRADED

optionsobject

A map of key-value properties attached to the securable.

propertiesobjectRequired

A map of key-value properties attached to the securable.

Response

Returns the ConnectionInfo object.

View as Markdown

Request

{
  "parent": "string",
  "name": "string",
  "connection_type": "UNKNOWN_CONNECTION_TYPE",
  "owner": "string",
  "read_only": true,
  "comment": "string",
  "environment_settings": {
    "java_dependencies": [
      "string"
    ],
    "environment_version": "string"
  },
  "full_name": "string",
  "url": "string",
  "credential_type": "UNKNOWN_CREDENTIAL_TYPE",
  "connection_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "securable_type": "CONNECTION",
  "provisioning_info": {
    "state": "PROVISIONING"
  },
  "options": {},
  "properties": {}
}

Response

{
  "name": "string",
  "connection_type": "UNKNOWN_CONNECTION_TYPE",
  "owner": "string",
  "read_only": true,
  "comment": "string",
  "environment_settings": {
    "java_dependencies": [
      "string"
    ],
    "environment_version": "string"
  },
  "full_name": "string",
  "url": "string",
  "credential_type": "UNKNOWN_CREDENTIAL_TYPE",
  "connection_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "securable_type": "CONNECTION",
  "provisioning_info": {
    "state": "PROVISIONING"
  },
  "options": {},
  "properties": {}
}

Update a connection GA

PATCH /api/2.1/unity-catalog/connections/{name_arg}

Updates the connection that matches the supplied name.

API scopes: unity-catalog

Parameters

name_argstringRequiredpath

Name of the connection.

Request body

new_namestring

New name for the connection.

namestring

Name of the connection.

connection_typestring

The type of connection.

Values:

Show 32 possible values

• UNKNOWN_CONNECTION_TYPE
• MYSQL
• POSTGRESQL
• SNOWFLAKE
• REDSHIFT
• SQLDW
• SQLSERVER
• DATABRICKS
• SALESFORCE
• BIGQUERY
• NETSUITE
• WORKDAY_RAAS
• HIVE_METASTORE
• GA4_RAW_DATA
• SERVICENOW
• SALESFORCE_DATA_CLOUD
• GLUE
• ORACLE
• TERADATA
• HTTP
• POWER_BI
• DYNAMICS365
• CONFLUENCE
• JDBC Public Preview
• META_MARKETING Beta
• HUBSPOT
• ZENDESK
• AWS_SECRETS_MANAGER Beta
• AZURE_KEY_VAULT Beta
• GITHUB Beta
• OUTLOOK Beta
• SMARTSHEET Beta

ownerstring

Username of current owner of the connection.

read_onlyboolean

If the connection is read only.

commentstring

User-provided free-form text description.

environment_settingsobjectPublic Preview

[Create,Update:OPT] Connection environment settings as EnvironmentSettings object.

Show child attributesHide child attributes

java_dependenciesarray of stringPublic Preview

environment_versionstringPublic Preview

full_namestring

Full name of connection.

urlstring

URL of the remote data source, extracted from options.

credential_typestring

The type of credential.

Values:

Show 16 possible values

• UNKNOWN_CREDENTIAL_TYPE
• USERNAME_PASSWORD
• OAUTH_U2M
• OAUTH_M2M
• OAUTH_REFRESH_TOKEN
• OAUTH_ACCESS_TOKEN
• OAUTH_RESOURCE_OWNER_PASSWORD
• SERVICE_CREDENTIAL
• BEARER_TOKEN
• OIDC_TOKEN
• PEM_PRIVATE_KEY
• OAUTH_U2M_MAPPING
• ANY_STATIC_CREDENTIAL
• OAUTH_MTLS
• SSWS_TOKEN
• EDGEGRID_AKAMAI

connection_idstring

Unique identifier of the Connection.

metastore_idstring

Unique identifier of parent metastore.

created_atint64

Time at which this connection was created, in epoch milliseconds.

created_bystring

Username of connection creator.

updated_atint64

Time at which this connection was updated, in epoch milliseconds.

updated_bystring

Username of user who last modified connection.

securable_typestring

The type of Unity Catalog securable.

Default: CONNECTION

Values:

Show 21 possible values

• CATALOG
• SCHEMA
• TABLE
• STORAGE_CREDENTIAL
• EXTERNAL_LOCATION
• FUNCTION
• SHARE
• PROVIDER
• RECIPIENT
• CLEAN_ROOM
• METASTORE
• PIPELINE
• VOLUME
• CONNECTION
• CREDENTIAL
• EXTERNAL_METADATA
• STAGING_TABLE
• MODEL Beta
• MODEL_SERVICE Beta
• MCP_SERVICE Beta
• MODEL_PROVIDER_SERVICE Beta

provisioning_infoobject

Show child attributesHide child attributes

statestring

The provisioning state of the resource.

Values:

• STATE_UNSPECIFIED
• PROVISIONING
• ACTIVE
• FAILED
• DELETING
• UPDATING
• DEGRADED

optionsobject

A map of key-value properties attached to the securable.

propertiesobjectRequired

A map of key-value properties attached to the securable.

Response

Returns the ConnectionInfo object.

View as Markdown

Request

{
  "new_name": "string",
  "name": "string",
  "connection_type": "UNKNOWN_CONNECTION_TYPE",
  "owner": "string",
  "read_only": true,
  "comment": "string",
  "environment_settings": {
    "java_dependencies": [
      "string"
    ],
    "environment_version": "string"
  },
  "full_name": "string",
  "url": "string",
  "credential_type": "UNKNOWN_CREDENTIAL_TYPE",
  "connection_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "securable_type": "CONNECTION",
  "provisioning_info": {
    "state": "PROVISIONING"
  },
  "options": {},
  "properties": {}
}

Response

{
  "name": "string",
  "connection_type": "UNKNOWN_CONNECTION_TYPE",
  "owner": "string",
  "read_only": true,
  "comment": "string",
  "environment_settings": {
    "java_dependencies": [
      "string"
    ],
    "environment_version": "string"
  },
  "full_name": "string",
  "url": "string",
  "credential_type": "UNKNOWN_CREDENTIAL_TYPE",
  "connection_id": "string",
  "metastore_id": "string",
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "securable_type": "CONNECTION",
  "provisioning_info": {
    "state": "PROVISIONING"
  },
  "options": {},
  "properties": {}
}

Delete a connection GA

DELETE /api/2.1/unity-catalog/connections/{name_arg}

Deletes the connection that matches the supplied name.

API scopes: unity-catalog

Parameters

name_argstringRequiredpath

The name of the connection to be deleted.

View as Markdown

Response

{}