Uc Tables

View as Markdown

Manage governed data and schema-level assets

Create Table ConstraintPOST /api/2.1/unity-catalog/constraintsDelete Table ConstraintDELETE /api/2.1/unity-catalog/constraints/{full_name_arg}List Table SummariesGET /api/2.1/unity-catalog/table-summariesTable ExistsGET /api/2.1/unity-catalog/tables/{full_name_arg}/exists

Create Table Constraint GA

POST /api/2.1/unity-catalog/constraints

Creates a new table constraint.

For the table constraint creation to succeed, the user must satisfy both of these conditions:

• the user must have the USE_CATALOG privilege on the table's parent catalog, the USE_SCHEMA privilege on the table's parent schema, and be the owner of the table.
• if the new constraint is a ForeignKeyConstraint, the user must have the USE_CATALOG privilege on the referenced parent table's catalog, the USE_SCHEMA privilege on the referenced parent table's schema, and be the owner of the referenced parent table.

API scopes: unity-catalog

Request body

full_name_argstring

The full name of the table referenced by the constraint.

constraintobject

Show child attributesHide child attributes

primary_key_constraintobjectRequired

Show child attributesHide child attributes

namestring

The name of the constraint.

child_columnsarray of string

Column names for this constraint.

timeseries_columnsarray of string

Column names that represent a timeseries.

relyboolean

True if the constraint is RELY, false or unset if NORELY.

foreign_key_constraintobjectRequired

Show child attributesHide child attributes

namestring

The name of the constraint.

child_columnsarray of string

Column names for this constraint.

parent_tablestring

The full name of the parent constraint.

parent_columnsarray of string

Column names for this constraint.

relyboolean

True if the constraint is RELY, false or unset if NORELY.

named_table_constraintobjectRequired

Show child attributesHide child attributes

namestring

The name of the constraint.

Response

primary_key_constraintobjectRequired

Show child attributesHide child attributes

namestring

The name of the constraint.

child_columnsarray of string

Column names for this constraint.

timeseries_columnsarray of string

Column names that represent a timeseries.

relyboolean

True if the constraint is RELY, false or unset if NORELY.

foreign_key_constraintobjectRequired

Show child attributesHide child attributes

namestring

The name of the constraint.

child_columnsarray of string

Column names for this constraint.

parent_tablestring

The full name of the parent constraint.

parent_columnsarray of string

Column names for this constraint.

relyboolean

True if the constraint is RELY, false or unset if NORELY.

named_table_constraintobjectRequired

Show child attributesHide child attributes

namestring

The name of the constraint.

View as Markdown

Request

{
  "full_name_arg": "string",
  "constraint": {
    "primary_key_constraint": {},
    "foreign_key_constraint": {},
    "named_table_constraint": {}
  }
}

Response

{
  "primary_key_constraint": {
    "name": "string",
    "child_columns": [
      "string"
    ],
    "timeseries_columns": [
      "string"
    ],
    "rely": true
  },
  "foreign_key_constraint": {
    "name": "string",
    "child_columns": [
      "string"
    ],
    "parent_table": "string",
    "parent_columns": [
      "string"
    ],
    "rely": true
  },
  "named_table_constraint": {
    "name": "string"
  }
}

Delete Table Constraint GA

DELETE /api/2.1/unity-catalog/constraints/{full_name_arg}

Deletes a table constraint.

For the table constraint deletion to succeed, the user must satisfy both of these conditions:

• the user must have the USE_CATALOG privilege on the table's parent catalog, the USE_SCHEMA privilege on the table's parent schema, and be the owner of the table.
• if cascade argument is true, the user must have the following permissions on all of the child tables: the USE_CATALOG privilege on the table's catalog, the USE_SCHEMA privilege on the table's schema, and be the owner of the table.

API scopes: unity-catalog

Parameters

full_name_argstringpath

Full name of the table referenced by the constraint.

constraint_namestringquery

The name of the constraint to delete.

cascadebooleanquery

If true, try deleting all child constraints of the current constraint. If false, reject this operation if the current constraint has any child constraints.

Default: false

View as Markdown

Response

{}

List Table Summaries GA

GET /api/2.1/unity-catalog/table-summaries

Gets an array of summaries for tables for a schema and catalog within the metastore. The table summaries returned are either:

• summaries for tables (within the current metastore and parent catalog and schema), when the user is a metastore admin, or:
• summaries for tables and schemas (within the current metastore and parent catalog) for which the user has ownership or the SELECT privilege on the table and ownership or USE_SCHEMA privilege on the schema, provided that the user also has ownership or the USE_CATALOG privilege on the parent catalog.

There is no guarantee of a specific ordering of the elements in the array.

PAGINATION BEHAVIOR: The API is by default paginated, 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

catalog_namestringquery

Name of parent catalog for tables of interest.

schema_name_patternstringquery

A sql LIKE pattern (% and _) for schema names. All schemas will be returned if not set or empty.

table_name_patternstringquery

A sql LIKE pattern (% and _) for table names. All tables will be returned if not set or empty.

max_resultsint32query

Maximum number of summaries for tables to return. If not set, the page length is set to a server configured value (10000, as of 1/5/2024).

• when set to a value greater than 0, the page length is the minimum of this value and a server configured value (10000, as of 1/5/2024);
• when set to 0, the page length is set to a server configured value (10000, as of 1/5/2024) (recommended);
• when set to a value less than 0, an invalid parameter error is returned;

Constraints: <= 10000

page_tokenstringquery

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

include_manifest_capabilitiesbooleanquery

Whether to include a manifest containing table capabilities in the response.

Response

tablesarray of object

List of table summaries.

Show child attributesHide child attributes

full_namestring

The full name of the table.

table_typestring

Values: MANAGED, EXTERNAL, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, MANAGED_SHALLOW_CLONE, FOREIGN, EXTERNAL_SHALLOW_CLONE, METRIC_VIEW

securable_kind_manifestobject

SecurableKindManifest of table, including capabilities the table has.

Show child attributesHide child attributes

securable_typestring

Securable Type of the kind.

Values: CATALOG, SCHEMA, TABLE, STORAGE_CREDENTIAL, EXTERNAL_LOCATION, FUNCTION, SHARE, PROVIDER, RECIPIENT, CLEAN_ROOM, METASTORE, PIPELINE, VOLUME, CONNECTION, CREDENTIAL, EXTERNAL_METADATA, STAGING_TABLE

securable_kindstring

Securable kind to get manifest of.

Values: TABLE_STANDARD, TABLE_EXTERNAL, TABLE_DELTA, TABLE_DELTA_EXTERNAL, TABLE_VIEW, TABLE_METRIC_VIEW, TABLE_DELTASHARING, TABLE_DELTASHARING_MUTABLE, TABLE_VIEW_DELTASHARING, TABLE_METRIC_VIEW_DELTASHARING, TABLE_MATERIALIZED_VIEW_DELTASHARING, TABLE_STREAMING_LIVE_TABLE_DELTASHARING, TABLE_FOREIGN_DELTASHARING, TABLE_DELTA_ICEBERG_DELTASHARING, TABLE_DELTASHARING_OPEN_DIR_BASED, TABLE_FEATURE_STORE, TABLE_FEATURE_STORE_EXTERNAL, TABLE_STREAMING_LIVE_TABLE, TABLE_SYSTEM, TABLE_SYSTEM_DELTASHARING, TABLE_MATERIALIZED_VIEW, TABLE_INTERNAL, TABLE_FOREIGN_BIGQUERY, TABLE_FOREIGN_MYSQL, TABLE_FOREIGN_ORACLE, TABLE_FOREIGN_POSTGRESQL, TABLE_FOREIGN_SQLDW, TABLE_FOREIGN_REDSHIFT, TABLE_FOREIGN_SNOWFLAKE, TABLE_FOREIGN_SQLSERVER, TABLE_FOREIGN_SALESFORCE, TABLE_FOREIGN_SALESFORCE_DATA_CLOUD, TABLE_FOREIGN_SALESFORCE_DATA_CLOUD_FILE_SHARING, TABLE_FOREIGN_SALESFORCE_DATA_CLOUD_FILE_SHARING_VIEW, TABLE_FOREIGN_TERADATA, TABLE_FOREIGN_NETSUITE, TABLE_FOREIGN_DATABRICKS, TABLE_FOREIGN_WORKDAY_RAAS, TABLE_FOREIGN_HIVE_METASTORE, TABLE_FOREIGN_HIVE_METASTORE_MANAGED, TABLE_FOREIGN_HIVE_METASTORE_DBFS_MANAGED, TABLE_FOREIGN_HIVE_METASTORE_EXTERNAL, TABLE_FOREIGN_HIVE_METASTORE_DBFS_EXTERNAL, TABLE_FOREIGN_HIVE_METASTORE_VIEW, TABLE_FOREIGN_HIVE_METASTORE_DBFS_VIEW, TABLE_FOREIGN_HIVE_METASTORE_SHALLOW_CLONE_MANAGED, TABLE_FOREIGN_HIVE_METASTORE_DBFS_SHALLOW_CLONE_MANAGED, TABLE_FOREIGN_HIVE_METASTORE_SHALLOW_CLONE_EXTERNAL, TABLE_FOREIGN_HIVE_METASTORE_DBFS_SHALLOW_CLONE_EXTERNAL, TABLE_FOREIGN_MONGODB, TABLE_DELTA_UNIFORM_HUDI_EXTERNAL, TABLE_DELTA_UNIFORM_ICEBERG_EXTERNAL, TABLE_DELTA_UNIFORM_ICEBERG_FOREIGN_HIVE_METASTORE_EXTERNAL, TABLE_DELTA_UNIFORM_ICEBERG_FOREIGN_HIVE_METASTORE_MANAGED, TABLE_DELTA_UNIFORM_ICEBERG_FOREIGN_SNOWFLAKE, TABLE_DELTA_UNIFORM_ICEBERG_FOREIGN_DELTASHARING, TABLE_DELTA_UNIFORM_ICEBERG_EXTERNAL_DELTASHARING, TABLE_ICEBERG_UNIFORM_MANAGED, TABLE_DELTA_ICEBERG_MANAGED, TABLE_ONLINE_VECTOR_INDEX_REPLICA, TABLE_ONLINE_VECTOR_INDEX_DIRECT, TABLE_ONLINE_VIEW, TABLE_DB_STORAGE, TABLE_MANAGED_POSTGRESQL

assignable_privilegesarray of string

Privileges that can be assigned to the securable.

optionsarray of object

Detailed specs of allowed options.

Show child attributesHide child attributes

namestring

The unique name of the option.

typestring

The type of the option.

Values: OPTION_TYPE_UNSPECIFIED, OPTION_BOOLEAN, OPTION_NUMBER, OPTION_BIGINT, OPTION_STRING, OPTION_ENUM, OPTION_SERVICE_CREDENTIAL, OPTION_MULTILINE_STRING

default_valuestring

The default value of the option, for example, value '443' for 'port' option.

allowed_valuesarray of string

For drop down / radio button selections, UI will want to know the possible input values, it can also be used by other option types to limit input selections.

hintstring

The hint is used on the UI to suggest what the input value can possibly be like, for example: example.com for 'host' option. Unlike default value, it will not be applied automatically without user input.

descriptionstring

A concise user facing description of what the input value of this option should look like.

is_requiredboolean

Is the option required.

is_secretboolean

Is the option value considered secret and thus redacted on the UI.

is_hiddenboolean

Is the option value not user settable and is thus not shown on the UI.

is_updatableboolean

Is the option updatable by users.

oauth_stagestring

Specifies when the option value is displayed on the UI within the OAuth flow.

Values: OAUTH_STAGE_UNSPECIFIED, BEFORE_AUTHORIZATION_CODE, BEFORE_ACCESS_TOKEN

is_loggableboolean

Specifies whether this option is safe to log, i.e. no sensitive information.

is_creatableboolean

Indicates whether an option can be provided by users in the create/update path of an entity.

is_copiableboolean

Indicates whether an option should be displayed with copy button on the UI.

capabilitiesarray of string

A list of capabilities in the securable kind.

next_page_tokenstring

Opaque token to retrieve the next page of results. Absent if there are no more pages. page_token should be set to this value for the next request (for the next page of results).

View as Markdown

Response

{
  "tables": [
    {
      "full_name": "string",
      "table_type": "string",
      "securable_kind_manifest": {}
    }
  ],
  "next_page_token": "string"
}

Table Exists GA

GET /api/2.1/unity-catalog/tables/{full_name_arg}/exists

Gets if a table exists in the metastore for a specific catalog and schema. The caller must satisfy one of the following requirements:

• Be a metastore admin
• Be the owner of the parent catalog
• Be the owner of the parent schema and have the USE_CATALOG privilege on the parent catalog
• Have the USE_CATALOG privilege on the parent catalog and the USE_SCHEMA privilege on the parent schema, and either be the table owner or have the SELECT privilege on the table.
• Have BROWSE privilege on the parent catalog
• Have BROWSE privilege on the parent schema

API scopes: unity-catalog

Parameters

full_name_argstringpath

Full name of the table.

Response

table_existsboolean

Whether the table exists or not.

View as Markdown

Response

{
  "table_exists": true
}