udf

client.udf

Classes

Name	Description
UDFError	Raised when a UDF can not be registered, retrieved, or executed.

UDFError

client.udf.UDFError()

Raised when a UDF can not be registered, retrieved, or executed.

Functions

Name	Description
exec	Run a user defined function, synchronously, returning only the result.
exec_async	Run a user defined function, asynchronously.
exec_base	Execute a user-defined function, returning results and metadata.
get_udf	Retrieve the representation of a registered UDF.
register_udf	Register a user-defined function (UDF).
update_udf	Update a registered UDF.

exec

client.udf.exec(*args, **kwargs)

Run a user defined function, synchronously, returning only the result.

Arguments are exactly as in exec_base.

exec_async

client.udf.exec_async(*args, **kwargs)

Run a user defined function, asynchronously.

Arguments are exactly as in exec_base.

exec_base

client.udf.exec_base(
    func,
    *args,
    teamspace=None,
    image_name='default',
    http_compressor='deflate',
    include_source_lines=True,
    task_name=None,
    result_format='tiledb_json',
    store_results=False,
    stored_param_uuids=(),
    timeout=None,
    resource_class=None,
    _download_results=True,
    _server_graph_uuid=None,
    _client_node_uuid=None,
    access_credentials_name=None,
    **kwargs,
)

Execute a user-defined function, returning results and metadata.

Parameters

Name	Type	Description	Default
func	callable or Asset - like	The function to run. This can be either a callable function, or a registered function asset identified by path, object, or “tiledb” URI.	required
teamspace	TeamspaceLike	The teamspace to execute the UDF under. If the func or arrays parameters specify a teamspace, this parameter may be omitted.	`None`
image_name	str	UDF image name to use, useful for testing beta features.	`'default'`
http_compressor	str	Set http compressor for results.	`'deflate'`
include_source_lines	bool, optional.	True to send the source code of your UDF to the server with your request. (This means it can be shown to you in stack traces if an error occurs.) False to send only compiled Python bytecode.	`True`
task_name	str	Name to assign the task for logging and audit purposes.	`None`
result_format	ResultFormat	Result serialization format.	`'tiledb_json'`
store_results	bool	True to temporarily store results on the server side for later retrieval (in addition to downloading them).	`False`
stored_param_uuids	optional	Currently undocumented.	`()`
timeout	int	Timeout for UDF in seconds.	`None`
resource_class	str	The name of the resource class to use. Resource classes define maximum limits for cpu and memory usage.	`None`
_download_results	bool	True to download and parse results eagerly. False to not download results by default and only do so lazily (e.g. for an intermediate node in a graph).	`True`
_server_graph_uuid	str	If this function is being executed within a DAG, the server-generated ID of the graph’s log. Otherwise, None.	`None`
_client_node_uuid	str	If this function is being executed within a DAG, the ID of this function’s node within the graph. Otherwise, None.	`None`
kwargs	dict	named arguments to pass to function.	`{}`

Returns

Name	Type	Description
	results.RemoteResult	A future containing the results of the UDF.

Raises

Name	Type	Description
	UDFError	When the func can not be executed.

Examples

>>> def add(a, b):
...     return a + b
...
>>> result = exec_base(add, 13, 19)
>>> result.get()
32

get_udf

client.udf.get_udf(udf, *, teamspace=None)

Retrieve the representation of a registered UDF.

The registration does not contain the source code of the user-defined function or any serialization of the function.

Parameters

Name	Type	Description	Default
udf	Asset, object, or str	The registered UDF, 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 `udf` parameter is queried for a teamspace id.	`None`

Returns

Name	Type	Description
	UDFInfo

Raises

Name	Type	Description
	UDFError	When the UDF can not be retrieved.

register_udf

client.udf.register_udf(
    func,
    path,
    *,
    teamspace=None,
    image_name=None,
    type=None,
    include_source_lines=True,
)

Parameters

Name	Type	Description	Default
func	Callable	The function to be registered.	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 name of the function 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`
image_name	str	Image name.	`None`
type	str	Type of udf: generic or single_array.	`None`
include_source_lines	bool	If False, disables sending sources lines of function along with udf.	`True`

Raises

Name	Type	Description
	UDFError:	When a function can not be registered.

Examples

>>> def get_tiledb_version():
...     import tiledb
...     return tiledb.__version__
...
>>> folder = folders.create_folder(
...     "udfs",
...     teamspace="teamspace",
...     exists_ok=True,
... )
>>> register_udf(get_tiledb_version, "udfs", teamspace="teamspace")

This creates a user-defined function asset at path “udfs/get_tiledb_version” in the teamspace named “teamspace”. The function’s name 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_udf(get_tiledb_version, folder)

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

>>> register_udf(
...     get_tiledb_version,
...     "tiledb://workspace/teamspace/udfs/get_tdbpy_version"
... )

update_udf

client.udf.update_udf(
    udf,
    *,
    teamspace,
    func=None,
    image_name=None,
    type=None,
    include_source_lines=True,
    license_id=None,
    license_text=None,
    readme=None,
)

Update a registered UDF.

Parameters

Name	Type	Description	Default
udf	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 name of the function will be appended to form a full asset path.	required
teamspace	Teamspace or str	The teamspace to which the object will be registered.	required
func	Optional[Callable]	The function to register.	`None`
image_name	str	Image name.	`None`
type	str	Type of udf: generic or single_array.	`None`
include_source_lines	str	Disables sending sources lines of function along with udf.	`True`
license_id	str	A new license id.	`None`
license_text	str	A new license text.	`None`
readme	str	A new long description for the UDF.	`None`

Raises

Name	Type	Description
	UDFError	When the UDF can not be updated.