Share

View as Markdown

GetGET /api/2.1/unity-catalog/shares/{name}CreatePOST /api/2.1/unity-catalog/sharesUpdatePATCH /api/2.1/unity-catalog/shares/{name_arg}DeleteDELETE /api/2.1/unity-catalog/shares/{name}

ShareInfo object

namestring

Name of the share.

ownerstring

Username of current owner of share.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for the share.

objectsarray of object

A list of shared data objects within the share.

Show child attributesHide child attributes

namestring

A fully qualified name that uniquely identifies a data object. For example, a table's fully qualified name is in the format of <catalog>.<schema>.<table>,

data_object_typestring

The type of the data object.

added_atint64

The time when this data object is added to the share, in epoch milliseconds.

added_bystring

Username of the sharer.

commentstring

A user-provided comment when adding the data object to the share.

shared_asstring

A user-provided alias name for table-like data objects within the share.

Use this field for table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE). For non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION), use string_shared_as instead.

Important: For non-table objects, this field must be omitted entirely.

Format: Must be a 2-part name <schema_name>.<table_name> (e.g., "sales_schema.orders_table")

• Both schema and table names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part
• Do not include the catalog name (use 2 parts, not 3)

Behavior:

• If not provided, the service automatically generates the alias as <schema>.<table> from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The shared_as name must be unique within the share

Examples:

• Valid: "analytics_schema.customer_view"
• Invalid: "catalog.analytics_schema.customer_view" (3 parts not allowed)
• Invalid: "analytics-schema.customer-view" (hyphens not allowed)

cdf_enabledboolean

Whether to enable cdf or indicate if cdf is enabled on the shared object.

history_data_sharing_statusstring

Whether to enable or disable sharing of data history. If not specified, the default is DISABLED.

Values: DISABLED, ENABLED

start_versionint64

The start version associated with the object. This allows data providers to control the lowest object version that is accessible by clients. If specified, clients can query snapshots or changes for versions >= start_version. If not specified, clients can only query starting from the version of the object at the time it was added to the share.

NOTE: The start_version should be <= the current version of the object.

statusstring

One of: ACTIVE, PERMISSION_DENIED.

Values: ACTIVE, PERMISSION_DENIED

contentstring

The content of the notebook file when the data object type is NOTEBOOK_FILE. This should be base64 encoded. Required for adding a NOTEBOOK_FILE, optional for updating, ignored for other types.

string_shared_asstring

A user-provided alias name for non-table data objects within the share.

Use this field for non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION). For table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE), use shared_as instead.

Important: For table-like objects, this field must be omitted entirely.

Format:

• For VOLUME: Must be a 2-part name <schema_name>.<volume_name> (e.g., "data_schema.ml_models")
• For FUNCTION: Must be a 2-part name <schema_name>.<function_name> (e.g., "udf_schema.calculate_tax")
• For MODEL: Must be a 2-part name <schema_name>.<model_name> (e.g., "models.prediction_model")
• For NOTEBOOK_FILE: Should be the notebook file name (e.g., "analysis_notebook.py")
• All names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part

Behavior:

• If not provided, the service automatically generates the alias from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The string_shared_as name must be unique for objects of the same type within the share

Examples:

• Valid for VOLUME: "data_schema.training_data"
• Valid for FUNCTION: "analytics.calculate_revenue"
• Invalid: "catalog.data_schema.training_data" (3 parts not allowed for volumes)
• Invalid: "data-schema.training-data" (hyphens not allowed)

partitionsarray of object

Array of partitions for the shared data.

Show child attributesHide child attributes

valuesarray of object

An array of partition values.

Show child attributesHide child attributes

namestring

The name of the partition column.

valuestring

The value of the partition column. When this value is not set, it means null value. When this field is set, field recipient_property_key can not be set.

recipient_property_keystring

The key of a Delta Sharing recipient's property. For example "databricks-account-id". When this field is set, field value can not be set.

opstring

The operator to apply for the value.

Values: EQUAL, LIKE

created_atint64

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

created_bystring

Username of share creator.

updated_atint64

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

updated_bystring

Username of share updater.

storage_locationstring

Storage Location URL (full path) for the share.

View as Markdown

The ShareInfo object

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "objects": [
    {
      "name": "string",
      "data_object_type": "string",
      "added_at": 0,
      "added_by": "string",
      "comment": "string",
      "shared_as": "string",
      "cdf_enabled": true,
      "history_data_sharing_status": "string",
      "start_version": 0,
      "status": "string",
      "content": "string",
      "string_shared_as": "string",
      "partitions": [
        {}
      ]
    }
  ],
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string"
}

Get GA

GET /api/2.1/unity-catalog/shares/{name}

Gets a data object share from the metastore. The caller must have the USE_SHARE privilege on the metastore or be the owner of the share.

API scopes: sharing

Parameters

namestringpath

The name of the share.

include_shared_databooleanquery

Query for data to include in the share.

Example: true

Response

Returns the ShareInfo object.

View as Markdown

Response

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "objects": [
    {
      "name": "string",
      "data_object_type": "string",
      "added_at": 0,
      "added_by": "string",
      "comment": "string",
      "shared_as": "string",
      "cdf_enabled": true,
      "history_data_sharing_status": "string",
      "start_version": 0,
      "status": "string",
      "content": "string",
      "string_shared_as": "string",
      "partitions": [
        {}
      ]
    }
  ],
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string"
}

Create GA

POST /api/2.1/unity-catalog/shares

Creates a new share for data objects. Data objects can be added after creation with update. The caller must be a metastore admin or have the CREATE_SHARE privilege on the metastore.

API scopes: sharing

Request body

namestring

Name of the share.

ownerstring

Username of current owner of share.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for the share.

objectsarray of object

A list of shared data objects within the share.

Show child attributesHide child attributes

namestring

A fully qualified name that uniquely identifies a data object. For example, a table's fully qualified name is in the format of <catalog>.<schema>.<table>,

data_object_typestring

The type of the data object.

added_atint64

The time when this data object is added to the share, in epoch milliseconds.

added_bystring

Username of the sharer.

commentstring

A user-provided comment when adding the data object to the share.

shared_asstring

A user-provided alias name for table-like data objects within the share.

Use this field for table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE). For non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION), use string_shared_as instead.

Important: For non-table objects, this field must be omitted entirely.

Format: Must be a 2-part name <schema_name>.<table_name> (e.g., "sales_schema.orders_table")

• Both schema and table names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part
• Do not include the catalog name (use 2 parts, not 3)

Behavior:

• If not provided, the service automatically generates the alias as <schema>.<table> from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The shared_as name must be unique within the share

Examples:

• Valid: "analytics_schema.customer_view"
• Invalid: "catalog.analytics_schema.customer_view" (3 parts not allowed)
• Invalid: "analytics-schema.customer-view" (hyphens not allowed)

cdf_enabledboolean

Whether to enable cdf or indicate if cdf is enabled on the shared object.

history_data_sharing_statusstring

Whether to enable or disable sharing of data history. If not specified, the default is DISABLED.

Values: DISABLED, ENABLED

start_versionint64

The start version associated with the object. This allows data providers to control the lowest object version that is accessible by clients. If specified, clients can query snapshots or changes for versions >= start_version. If not specified, clients can only query starting from the version of the object at the time it was added to the share.

NOTE: The start_version should be <= the current version of the object.

statusstring

One of: ACTIVE, PERMISSION_DENIED.

Values: ACTIVE, PERMISSION_DENIED

contentstring

The content of the notebook file when the data object type is NOTEBOOK_FILE. This should be base64 encoded. Required for adding a NOTEBOOK_FILE, optional for updating, ignored for other types.

string_shared_asstring

A user-provided alias name for non-table data objects within the share.

Use this field for non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION). For table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE), use shared_as instead.

Important: For table-like objects, this field must be omitted entirely.

Format:

• For VOLUME: Must be a 2-part name <schema_name>.<volume_name> (e.g., "data_schema.ml_models")
• For FUNCTION: Must be a 2-part name <schema_name>.<function_name> (e.g., "udf_schema.calculate_tax")
• For MODEL: Must be a 2-part name <schema_name>.<model_name> (e.g., "models.prediction_model")
• For NOTEBOOK_FILE: Should be the notebook file name (e.g., "analysis_notebook.py")
• All names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part

Behavior:

• If not provided, the service automatically generates the alias from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The string_shared_as name must be unique for objects of the same type within the share

Examples:

• Valid for VOLUME: "data_schema.training_data"
• Valid for FUNCTION: "analytics.calculate_revenue"
• Invalid: "catalog.data_schema.training_data" (3 parts not allowed for volumes)
• Invalid: "data-schema.training-data" (hyphens not allowed)

partitionsarray of object

Array of partitions for the shared data.

Show child attributesHide child attributes

valuesarray of object

An array of partition values.

Show child attributesHide child attributes

namestring

The name of the partition column.

valuestring

The value of the partition column. When this value is not set, it means null value. When this field is set, field recipient_property_key can not be set.

recipient_property_keystring

The key of a Delta Sharing recipient's property. For example "databricks-account-id". When this field is set, field value can not be set.

opstring

The operator to apply for the value.

Values: EQUAL, LIKE

created_atint64

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

created_bystring

Username of share creator.

updated_atint64

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

updated_bystring

Username of share updater.

storage_locationstring

Storage Location URL (full path) for the share.

Response

Returns the ShareInfo object.

View as Markdown

Request

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "objects": [
    {
      "name": "string",
      "data_object_type": "string",
      "added_at": 0,
      "added_by": "string",
      "comment": "string",
      "shared_as": "string",
      "cdf_enabled": true,
      "history_data_sharing_status": "string",
      "start_version": 0,
      "status": "string",
      "content": "string",
      "string_shared_as": "string",
      "partitions": [
        {}
      ]
    }
  ],
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string"
}

Response

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "objects": [
    {
      "name": "string",
      "data_object_type": "string",
      "added_at": 0,
      "added_by": "string",
      "comment": "string",
      "shared_as": "string",
      "cdf_enabled": true,
      "history_data_sharing_status": "string",
      "start_version": 0,
      "status": "string",
      "content": "string",
      "string_shared_as": "string",
      "partitions": [
        {}
      ]
    }
  ],
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string"
}

Update GA

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

Updates the share with the changes and data objects in the request. The caller must be the owner of the share or a metastore admin.

When the caller is a metastore admin, only the owner field can be updated.

In the case the share name is changed, updateShare requires that the caller is the owner of the share and has the CREATE_SHARE privilege.

If there are notebook files in the share, the storage_root field cannot be updated.

For each table that is added through this method, the share owner must also have SELECT privilege on the table. This privilege must be maintained indefinitely for recipients to be able to access the table. Typically, you should use a group as the share owner.

Table removals through update do not require additional privileges.

API scopes: sharing

Parameters

name_argstringpath

The name of the share.

Request body

new_namestring

New name for the share.

updatesarray of object

Array of shared data object updates.

Show child attributesHide child attributes

actionstring

One of: ADD, REMOVE, UPDATE.

Values: ADD, REMOVE, UPDATE

data_objectobject

The data object that is being added, removed, or updated. The maximum number update data objects allowed is a 100.

Show child attributesHide child attributes

namestring

A fully qualified name that uniquely identifies a data object. For example, a table's fully qualified name is in the format of <catalog>.<schema>.<table>,

data_object_typestring

The type of the data object.

added_atint64

The time when this data object is added to the share, in epoch milliseconds.

added_bystring

Username of the sharer.

commentstring

A user-provided comment when adding the data object to the share.

shared_asstring

A user-provided alias name for table-like data objects within the share.

Use this field for table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE). For non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION), use string_shared_as instead.

Important: For non-table objects, this field must be omitted entirely.

Format: Must be a 2-part name <schema_name>.<table_name> (e.g., "sales_schema.orders_table")

• Both schema and table names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part
• Do not include the catalog name (use 2 parts, not 3)

Behavior:

• If not provided, the service automatically generates the alias as <schema>.<table> from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The shared_as name must be unique within the share

Examples:

• Valid: "analytics_schema.customer_view"
• Invalid: "catalog.analytics_schema.customer_view" (3 parts not allowed)
• Invalid: "analytics-schema.customer-view" (hyphens not allowed)

cdf_enabledboolean

Whether to enable cdf or indicate if cdf is enabled on the shared object.

history_data_sharing_statusstring

Whether to enable or disable sharing of data history. If not specified, the default is DISABLED.

Values: DISABLED, ENABLED

start_versionint64

The start version associated with the object. This allows data providers to control the lowest object version that is accessible by clients. If specified, clients can query snapshots or changes for versions >= start_version. If not specified, clients can only query starting from the version of the object at the time it was added to the share.

NOTE: The start_version should be <= the current version of the object.

statusstring

One of: ACTIVE, PERMISSION_DENIED.

Values: ACTIVE, PERMISSION_DENIED

contentstring

The content of the notebook file when the data object type is NOTEBOOK_FILE. This should be base64 encoded. Required for adding a NOTEBOOK_FILE, optional for updating, ignored for other types.

string_shared_asstring

A user-provided alias name for non-table data objects within the share.

Use this field for non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION). For table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE), use shared_as instead.

Important: For table-like objects, this field must be omitted entirely.

Format:

• For VOLUME: Must be a 2-part name <schema_name>.<volume_name> (e.g., "data_schema.ml_models")
• For FUNCTION: Must be a 2-part name <schema_name>.<function_name> (e.g., "udf_schema.calculate_tax")
• For MODEL: Must be a 2-part name <schema_name>.<model_name> (e.g., "models.prediction_model")
• For NOTEBOOK_FILE: Should be the notebook file name (e.g., "analysis_notebook.py")
• All names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part

Behavior:

• If not provided, the service automatically generates the alias from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The string_shared_as name must be unique for objects of the same type within the share

Examples:

• Valid for VOLUME: "data_schema.training_data"
• Valid for FUNCTION: "analytics.calculate_revenue"
• Invalid: "catalog.data_schema.training_data" (3 parts not allowed for volumes)
• Invalid: "data-schema.training-data" (hyphens not allowed)

partitionsarray of object

Array of partitions for the shared data.

Show child attributesHide child attributes

valuesarray of object

An array of partition values.

namestring

Name of the share.

ownerstring

Username of current owner of share.

commentstring

User-provided free-form text description.

storage_rootstring

Storage root URL for the share.

objectsarray of object

A list of shared data objects within the share.

Show child attributesHide child attributes

namestring

A fully qualified name that uniquely identifies a data object. For example, a table's fully qualified name is in the format of <catalog>.<schema>.<table>,

data_object_typestring

The type of the data object.

added_atint64

The time when this data object is added to the share, in epoch milliseconds.

added_bystring

Username of the sharer.

commentstring

A user-provided comment when adding the data object to the share.

shared_asstring

A user-provided alias name for table-like data objects within the share.

Use this field for table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE). For non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION), use string_shared_as instead.

Important: For non-table objects, this field must be omitted entirely.

Format: Must be a 2-part name <schema_name>.<table_name> (e.g., "sales_schema.orders_table")

• Both schema and table names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part
• Do not include the catalog name (use 2 parts, not 3)

Behavior:

• If not provided, the service automatically generates the alias as <schema>.<table> from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The shared_as name must be unique within the share

Examples:

• Valid: "analytics_schema.customer_view"
• Invalid: "catalog.analytics_schema.customer_view" (3 parts not allowed)
• Invalid: "analytics-schema.customer-view" (hyphens not allowed)

cdf_enabledboolean

Whether to enable cdf or indicate if cdf is enabled on the shared object.

history_data_sharing_statusstring

Whether to enable or disable sharing of data history. If not specified, the default is DISABLED.

Values: DISABLED, ENABLED

start_versionint64

The start version associated with the object. This allows data providers to control the lowest object version that is accessible by clients. If specified, clients can query snapshots or changes for versions >= start_version. If not specified, clients can only query starting from the version of the object at the time it was added to the share.

NOTE: The start_version should be <= the current version of the object.

statusstring

One of: ACTIVE, PERMISSION_DENIED.

Values: ACTIVE, PERMISSION_DENIED

contentstring

The content of the notebook file when the data object type is NOTEBOOK_FILE. This should be base64 encoded. Required for adding a NOTEBOOK_FILE, optional for updating, ignored for other types.

string_shared_asstring

A user-provided alias name for non-table data objects within the share.

Use this field for non-table objects (for example: VOLUME, MODEL, NOTEBOOK_FILE, FUNCTION). For table-like objects (for example: TABLE, VIEW, MATERIALIZED_VIEW, STREAMING_TABLE, FOREIGN_TABLE), use shared_as instead.

Important: For table-like objects, this field must be omitted entirely.

Format:

• For VOLUME: Must be a 2-part name <schema_name>.<volume_name> (e.g., "data_schema.ml_models")
• For FUNCTION: Must be a 2-part name <schema_name>.<function_name> (e.g., "udf_schema.calculate_tax")
• For MODEL: Must be a 2-part name <schema_name>.<model_name> (e.g., "models.prediction_model")
• For NOTEBOOK_FILE: Should be the notebook file name (e.g., "analysis_notebook.py")
• All names must contain only alphanumeric characters and underscores
• No periods, spaces, forward slashes, or control characters are allowed within each part

Behavior:

• If not provided, the service automatically generates the alias from the object's original name
• If you don't want to specify this field, omit it entirely from the request (do not pass an empty string)
• The string_shared_as name must be unique for objects of the same type within the share

Examples:

• Valid for VOLUME: "data_schema.training_data"
• Valid for FUNCTION: "analytics.calculate_revenue"
• Invalid: "catalog.data_schema.training_data" (3 parts not allowed for volumes)
• Invalid: "data-schema.training-data" (hyphens not allowed)

partitionsarray of object

Array of partitions for the shared data.

Show child attributesHide child attributes

valuesarray of object

An array of partition values.

Show child attributesHide child attributes

namestring

The name of the partition column.

valuestring

The value of the partition column. When this value is not set, it means null value. When this field is set, field recipient_property_key can not be set.

recipient_property_keystring

The key of a Delta Sharing recipient's property. For example "databricks-account-id". When this field is set, field value can not be set.

opstring

The operator to apply for the value.

Values: EQUAL, LIKE

created_atint64

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

created_bystring

Username of share creator.

updated_atint64

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

updated_bystring

Username of share updater.

storage_locationstring

Storage Location URL (full path) for the share.

Response

Returns the ShareInfo object.

View as Markdown

Request

{
  "new_name": "string",
  "updates": [
    {
      "action": "string",
      "data_object": {}
    }
  ],
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "objects": [
    {
      "name": "string",
      "data_object_type": "string",
      "added_at": 0,
      "added_by": "string",
      "comment": "string",
      "shared_as": "string",
      "cdf_enabled": true,
      "history_data_sharing_status": "string",
      "start_version": 0,
      "status": "string",
      "content": "string",
      "string_shared_as": "string",
      "partitions": [
        {}
      ]
    }
  ],
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string"
}

Response

{
  "name": "string",
  "owner": "string",
  "comment": "string",
  "storage_root": "string",
  "objects": [
    {
      "name": "string",
      "data_object_type": "string",
      "added_at": 0,
      "added_by": "string",
      "comment": "string",
      "shared_as": "string",
      "cdf_enabled": true,
      "history_data_sharing_status": "string",
      "start_version": 0,
      "status": "string",
      "content": "string",
      "string_shared_as": "string",
      "partitions": [
        {}
      ]
    }
  ],
  "created_at": 0,
  "created_by": "string",
  "updated_at": 0,
  "updated_by": "string",
  "storage_location": "string"
}

Delete GA

DELETE /api/2.1/unity-catalog/shares/{name}

Deletes a data object share from the metastore. The caller must be an owner of the share.

API scopes: sharing

Parameters

namestringpath

The name of the share.

View as Markdown

Response

{}