assets

client.assets

An Asset is an item in the TileDB Catalog.

An Asset may represent an Array, a Group of Arrays, a Folder, or a File.

When a Folder is created, it becomes an asset and a corresponded Asset is created in the Catalog. When a file is uploaded, it becomes an asset. Similarly, creation or registration of arrays and groups produces new assets in the Catalog.

Classes

Name	Description
AssetCreatorError	Raised when _AssetCreator fails to create.
AssetsError	Raised when assets can not be accessed.

AssetCreatorError

client.assets.AssetCreatorError()

Raised when _AssetCreator fails to create.

AssetsError

client.assets.AssetsError()

Raised when assets can not be accessed.

Functions

Name	Description
delete_asset	Remove an asset and its sub-assets from the TileDB catalog.
delete_metadata	Delete asset metadata.
get_asset	Retrieve the representation of an asset by object, path, or id.
get_metadata	Retrieve asset metadata.
list_assets	List the assets of a folder or teamspace.
move_assets	Move one or more assets to a folder.
register_asset	Register a cloud storage object like an array or group.
rename_asset	Rename an asset.
search_assets	Search the catalog for assets.
update_asset	Update the description and/or type of an asset.
update_metadata	Update asset metadata.

delete_asset

client.assets.delete_asset(asset, *, teamspace=None, delete_storage=False)

Remove an asset and its sub-assets from the TileDB catalog.

The corresponding objects in cloud storage may be optionally deleted as well.

The primary asset may be identified by its object representation, path relative to a teamspace, or asset id.

Parameters

Name	Type	Description	Default
asset	AssetLike	The target asset, specified by object, path, or id.	required
teamspace	Teamspace or str	The teamspace to search within, specified by object or id. If not provided, the asset parameter is queried for a teamspace id.	None
delete_storage	bool	If True, this function will also delete backing objects from storage (e.g., S3). The default is False.	False

Raises

Name	Type	Description
	AssetsError	Raised when an asset cannot be deleted.

Examples

>>> delete_asset(
...     "path/to/asset",
...     teamspace="teamspace_id",
... )

delete_metadata

client.assets.delete_metadata(asset, keys, *, teamspace=None)

Delete asset metadata.

Metadata are represented as a Python dict with string keys and values that can be any builtin Python type or Numpy scalar.

Parameters

Name	Type	Description	Default
asset	obj or str	The target asset, specified by object or id.	required
keys	Sequence	A sequence of keys to delete along with their values.	required
teamspace	Teamspace or str	The teamspace to search within, specified by object or id. If not provided, the asset parameter is queried for a teamspace id.	None

Returns

Name	Type	Description
	None

Raises

Name	Type	Description
	AssetsError	Raised when metadata can not be created and saved.

Examples

>>> delete_metadata(
...     "asset_id",
...     ["field1"],
...     teamspace="teamspace_id",
... )

get_asset

client.assets.get_asset(asset, *, teamspace=None)

Retrieve the representation of an asset by object, path, or id.

The catalog representation of a Folder, File, Array, or Group may be identified by its object representation, path relative to a teamspace, or asset id.

Parameters

Name	Type	Description	Default
asset	Asset or str	The target asset, specified by object, path, or id.	required
teamspace	Teamspace or str	The teamspace to search within, specified by object or id. If not provided, the asset parameter is queried for a teamspace id.	None

Returns

Name	Type	Description
	Asset

Raises

Name	Type	Description
	AssetsError	Raised when an asset representation cannot be retrieved.

Examples

>>> obj = get_asset(
...     "path/to/asset",
...     teamspace="teamspace_id",
... )

>>> obj = get_asset("tiledb://workspace/teamspace/path/to/asset")

get_metadata

client.assets.get_metadata(asset, *, teamspace=None)

Retrieve asset metadata.

Metadata are represented as a Python dict with string keys and values that can be any builtin Python type or Numpy scalar.

Parameters

Name	Type	Description	Default
asset	obj or str	The target asset, specified by object or id.	required
teamspace	Teamspace or str	The teamspace to search within, specified by object or id. If not provided, the asset parameter is queried for a teamspace id.	None

Returns

Name	Type	Description
	dict

Raises

Name	Type	Description
	AssetsError	Raised when metadata can not be created and saved.

Examples

>>> get_metadata("asset_id", teamspace="teamspace_id")

list_assets

client.assets.list_assets(
    path,
    *,
    teamspace=None,
    type=None,
    created_by=None,
    expand=None,
    page=1,
    per_page=None,
    order_by=None,
)

List the assets of a folder or teamspace.

An asset listing consists of a sequence of “pages”, or batches, of lists of assets. This function returns a Pager object that represents one page of the listing. The object also serves as an iterator over all assets from that page to the last page, and it can be indexed to get all or a subset of assets from that page to the last page.

Parameters

Name	Type	Description	Default
path	str or object	The TileDB path of a folder. May be a path relative to a teamspace, a Folder or Asset instance, or an absolute “tiledb” URI. To list the assets of a teamspace, pass an empty string.	required
teamspace	Teamspace or str	The teamspace to which the path belongs, specified by object or id. If not provided, the path parameter is queried for a teamspace id.	None
type	str	Filters for assets of the specified type. Allowed types are enumerated by the AssetType class.	None
created_by	str	Filters for assets created by a named user.	None
expand	str	Specifies profiles of additional information to include in the response.	None
page	int	Which page of results to retrieve. 1-based.	1
per_page	int	How many results to include on each page.	None
order_by	str, optional.	The order to return assets, by default “created_at desc”. Supported keys are “created_at”, “name”, and “asset_type”. They can be used alone or with “asc” or “desc” separated by a space (e.g. “created_at”, “asset_type asc”).	None

Returns

Name	Type	Description
	Pager for Assets

Raises

Name	Type	Description
	AssetsError	Raised when assets can not be accessed.

Examples

>>> for asset in list_assets(
...     "folder1/folder2",
...     teamspace="teamspace"
... ):
...     print(asset)

Prints all of the assets found directly under the path “folder1/folder2”.

move_assets

client.assets.move_assets(assets, folder, *, teamspace=None)

Move one or more assets to a folder.

This function can not be used to rename assets. For that, see rename_assets().

Note that moving a folder will recursively update the paths of its contents. This operation may take a non-negligible amount of time to complete. move_assets() assumes that the folders it walks are not modified during execution.

Assets may be identified by asset id, path relative to a teamspace, or object representation (Asset instance).

Parameters

Name	Type	Description	Default
assets	AssetLike or list of AssetLike	The representation or string identifier(s) of an existing asset(s).	required
folder	AssetLike	The representation or string identifier of an existing folder.	required
teamspace	Teamspace or str	The representation or string identifier of the assets’ teamspace. If the folder parameter is an Asset instance, the teamspace will be obtained from it.	None

Returns

Name	Type	Description
	None

Raises

Name	Type	Description
	AssetsError	If the assets cannot be moved.

Examples

>>> assets.move_assets(
...     "/asset1",
...     "/folder",
...     teamspace="teamspace",
... )

register_asset

client.assets.register_asset(uri, path, *, teamspace=None, acn=None)

Register a cloud storage object like an array or group.

Parameters

Name	Type	Description	Default
uri	str	Object identifier. For example: “s3://bucket/prefix/file”.	required
path	str or object	The TileDB path at which the object is to be registered. May be a path relative to a teamspace, a Folder or Asset instance, or an absolute “tiledb” URI. If the path to a folder is provided, the basename or stem of the uri will be appended to form a full asset path.	required
teamspace	Teamspace or str	The teamspace to which the object will be registered, specified by object or id. If not provided, the path parameter is queried for a teamspace id.	None
acn	str	The name of a stored credential for accessing the object.	None

Raises

Name	Type	Description
	AssetsError:	If the registration failed.

Examples

>>> folder = folders.create_folder(
...     "objects",
...     teamspace="teamspace",
...     exists_ok=True,
... )
>>> assets.register_asset(
...     "s3://bucket/prefix/example1",
...     "objects",
...     teamspace="teamspace",
...     acn="bucket-credentials",
... )

This creates an asset at path “objects/example1” in the teamspace named “teamspace”. The object’s basename has been used to construct the full path.

If you like, you can pass a Folder or Asset object instead of a path string and get the same result.

>>> register_asset(
...     "s3://bucket/prefix/example1",
...     folder,
...     acn="bucket-credentials",
... )

An object can also be registered to a specific absolute “tiledb” URI that specifies a different name.

>>> register_udf(
...     "s3://bucket/prefix/example1",
...     "tiledb://workspace/teamspace/objects/new_asset",
...     acn="bucket-credentials",
... )

rename_asset

client.assets.rename_asset(asset, name, *, teamspace=None)

Rename an asset.

This method cannot be used to move an asset to a different folder.

Note that renaming a folder will recursively update the paths of its contents. This operation may take a non-negligible amount of time to complete. rename_asset() assumes that the folders it walks are not modified during execution.

The asset may be identified by asset id, path relative to a teamspace, or object representation (Asset instance).

Parameters

Name	Type	Description	Default
asset	Asset or str	The representation or string identifier of an existing asset.	required
name	str	New name for the asset.	required
teamspace	Teamspace or str	The representation or string identifier of the asset’s teamspace. If the asset parameter is an Asset instance, the teamspace will be obtained from it.	None

Returns

Name	Type	Description
	str	The updated path of the asset.

Raises

Name	Type	Description
	AssetsError	If the asset cannot be renamed.

Examples

>>> assets.rename_asset(
...     "folder1/asset1",
...     "asset-one",
...     teamspace="teamspace",
... )
"/folder1/asset-one"

search_assets

client.assets.search_assets(
    query=None,
    fields=None,
    metadata=None,
    path=None,
    teamspace=None,
    teamspace_exclude=None,
    public=None,
    sort=None,
    sort_dir=None,
    page=1,
    per_page=None,
)

Search the catalog for assets.

A search result consists of a sequence of “pages”, or batches, of lists of assets. This function returns a Pager object that represents one page of the listing. The object also serves as an iterator over all assets from that page to the last page, and it can be indexed to get all or a subset of assets from that page to the last page.

Without parameters, this function will query all accessible assets, public or in private teamspaces that the user is a member of.

Assets may be filtered using simple expressions. The expression syntax is {key}{op}{value}, where key is one of an asset’s fields (“created_by”, “backing_type”, etc.) and op is one of: “<”, “>”, “<=”, “>=”, “=”, “!=”, or “:”. The op “:” sets up a range where two valid values {lo}..{hi}, equivalent to {lo} <= x <= {hi}, Date values (“created_at”, “updated_at”) can be relative times in the past (“today”, “yesterday”, “week”, “month”, “year”), or a RFC 3339 value like “2006-01-02T15:04:05Z07:00”.

User-defined metadata fields may be used in filters with the same expression syntax.

Parameters

Name	Type	Description	Default
query	str	Query keywords.	None
fields	list[str]	A list of expressions involving standard asset fields.	None
metadata	list[str]	A list of expressions involving user-defined metadata fields.	None
path	str	The path to search within. Default is all paths.	None
teamspace	list[Teamspace or str]	The teamspaces to search within, specified by object or id.	None
teamspace_exclude	list[Teamspace or str]	The teamspaces to exclude from search, specified by object or id.	None
public	bool	Whether to include assets of public teamspaces in result, or not. Default is True.	None
sort	str	Sort order for results. Valid values are “relevance”, “recency”, or “name”. The default is relevance.	None
sort_dir	str	Sort direction for results. Valid values are “asc” (ascending) or “desc” (descending). The default is “desc”.	None
page	int	Which page of results to retrieve. 1-based.	1
per_page	int	How many results to include on each page.	None

Returns

Name	Type	Description
	Pager for Assets

Raises

Name	Type	Description
	AssetsError	Raised when assets can not be accessed.

Examples

>>> for asset in search_assets(
...     fields=["created_by=user1"],
...     path="folder1/folder2",
...     teamspace="teamspace"
... ):
...     print(asset)

Prints the assets under path “folder1/folder2” that were created by the user named “user1”.

update_asset

client.assets.update_asset(
    asset,
    *,
    teamspace=None,
    description=None,
    type=None,
)

Update the description and/or type of an asset.

The asset may be identified by asset id, path relative to a teamspace, or object representation (Asset instance).

Parameters

Name	Type	Description	Default
asset	Asset or str	The representation or string identifier of an existing asset.	required
description	str	New description for the asset.	None
type	AssetType	New type for the asset.	None
teamspace	Teamspace or str	The representation or string identifier of the asset’s teamspace. If the asset parameter is an Asset instance, the teamspace will be obtained from it.	None

Returns

Name	Type	Description
	None

Raises

Name	Type	Description
	AssetsError	If the asset cannot be updated.

Examples

>>> assets.update_asset(
...     "asset1",
...     teamspace="teamspace",
...     description="An updated description for asset one."
... )

update_metadata

client.assets.update_metadata(asset, items, *, teamspace=None)

Update asset metadata.

Metadata are represented as a Python dict with string keys and values that can be any builtin Python type or Numpy scalar.

Parameters

Name	Type	Description	Default
asset	obj or str	The target asset, specified by object or id.	required
items	Mapping	A mapping of metadata keys and values.	required
teamspace	Teamspace or str	The teamspace to search within, specified by object or id. If not provided, the asset parameter is queried for a teamspace id.	None

Returns

Name	Type	Description
	None

Raises

Name	Type	Description
	AssetsError	Raised when metadata can not be created and saved.

Examples

>>> update_metadata(
...     "asset_id",
...     {"field1": "another string", "field2": numpy.float64(4.2)},
...     teamspace="teamspace_id",
... )