Skip to main content

Connection

View as Markdown

ConnectionInfo object​

namestring

Name of the connection.

connection_typestring

The type of external data source or service that the connection reaches. The connection type determines which keys are required in options and cannot be changed after creation.

Values:

Show 33 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
  • TIKTOK_ADS Public Preview
  • HUBSPOT
  • ZENDESK
  • AWS_SECRETS_MANAGER Beta
  • AZURE_KEY_VAULT Beta
  • GITHUB Beta
  • OUTLOOK Beta
  • SMARTSHEET
ownerstring

Username of the current owner of the connection. The creator becomes the owner at creation, and ownership can be transferred on update.

read_onlyboolean

Whether the connection is read only. All connections are currently read only, so a value set on create or update is ignored.

commentstring

User-provided free-form text description.

environment_settingsobjectPublic Preview

Environment settings for the connection, such as the Java libraries that it needs and the environment version.

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. The server derives it from the host, port and path options.

credential_typestring

The type of credential that is used to authenticate to the external data source. The server derives it from the connection type and the keys present in options.

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. This is always CONNECTION.

Default: CONNECTION

Values:

Show 24 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
  • MODEL_SERVICE
  • MCP_SERVICE
  • MODEL_PROVIDER_SERVICE
  • AGENT_SERVICE Beta
  • SKILL Beta
  • FEATURE
provisioning_infoobject

Provisioning status of the connection.

Show child attributesHide child attributes
statestring

The provisioning state of the resource.

Values:

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

Get a connection GA​

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

Gets a connection from its name.

API scopes: unity-catalog

Parameters​

name_argstringRequiredpath

Name of the connection.

Response​

Returns the ConnectionInfo object.

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.

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 external data source or service that the connection reaches. The connection type determines which keys are required in options and cannot be changed after creation.

Values:

Show 33 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
  • TIKTOK_ADS Public Preview
  • HUBSPOT
  • ZENDESK
  • AWS_SECRETS_MANAGER Beta
  • AZURE_KEY_VAULT Beta
  • GITHUB Beta
  • OUTLOOK Beta
  • SMARTSHEET
ownerstring

Username of the current owner of the connection. The creator becomes the owner at creation, and ownership can be transferred on update.

read_onlyboolean

Whether the connection is read only. All connections are currently read only, so a value set on create or update is ignored.

commentstring

User-provided free-form text description.

environment_settingsobjectPublic Preview

Environment settings for the connection, such as the Java libraries that it needs and the environment version.

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. The server derives it from the host, port and path options.

credential_typestring

The type of credential that is used to authenticate to the external data source. The server derives it from the connection type and the keys present in options.

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. This is always CONNECTION.

Default: CONNECTION

Values:

Show 24 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
  • MODEL_SERVICE
  • MCP_SERVICE
  • MODEL_PROVIDER_SERVICE
  • AGENT_SERVICE Beta
  • SKILL Beta
  • FEATURE
provisioning_infoobject

Provisioning status of the connection.

Show child attributesHide child attributes
statestring

The provisioning state of the resource.

Values:

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

Update a connection GA​

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

Updates the connection that matches the supplied name. When options are provided, they replace the existing options of the connection, so include every key that the connection type requires.

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 external data source or service that the connection reaches. The connection type determines which keys are required in options and cannot be changed after creation.

Values:

Show 33 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
  • TIKTOK_ADS Public Preview
  • HUBSPOT
  • ZENDESK
  • AWS_SECRETS_MANAGER Beta
  • AZURE_KEY_VAULT Beta
  • GITHUB Beta
  • OUTLOOK Beta
  • SMARTSHEET
ownerstring

Username of the current owner of the connection. The creator becomes the owner at creation, and ownership can be transferred on update.

read_onlyboolean

Whether the connection is read only. All connections are currently read only, so a value set on create or update is ignored.

commentstring

User-provided free-form text description.

environment_settingsobjectPublic Preview

Environment settings for the connection, such as the Java libraries that it needs and the environment version.

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. The server derives it from the host, port and path options.

credential_typestring

The type of credential that is used to authenticate to the external data source. The server derives it from the connection type and the keys present in options.

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. This is always CONNECTION.

Default: CONNECTION

Values:

Show 24 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
  • MODEL_SERVICE
  • MCP_SERVICE
  • MODEL_PROVIDER_SERVICE
  • AGENT_SERVICE Beta
  • SKILL Beta
  • FEATURE
provisioning_infoobject

Provisioning status of the connection.

Show child attributesHide child attributes
statestring

The provisioning state of the resource.

Values:

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

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.