Skip to main content

run

run(
    udf: Union[str, None, UdfJobStepConfig, Udf, UdfAccessToken] = None,
    *,
    x: Optional[int] = None,
    y: Optional[int] = None,
    z: Optional[int] = None,
    sync: bool = True,
    engine: Optional[Literal["remote", "local"]] = None,
    instance_type: Optional[InstanceType] = None,
    type: Optional[Literal["tile", "file"]] = None,
    max_retry: int = 0,
    cache_max_age: Optional[str] = None,
    cache: bool = True,
    parameters: Optional[Dict[str, Any]] = None,
    disk_size_gb: Optional[int] = None,
    **kw_parameters
) -> Union[ResultType, Coroutine[ResultType, None, None]]

Executes a user-defined function (UDF) with various execution and input options.

This function supports executing UDFs in different environments (local or remote), with different types of inputs (tile coordinates, geographical bounding boxes, etc.), and allows for both synchronous and asynchronous execution.

Parameters​

  • udf (str, Udf or UdfJobStepConfig) – The UDF to execute. Can be specified as:
    • A string representing a UDF name or UDF shared token.
    • A UDF object.
    • A UdfJobStepConfig object for detailed execution configuration.
  • x, y, z (int) – Tile coordinates for tile-based UDF execution.
  • sync (bool) – If True, execute the UDF synchronously. If False, execute asynchronously.
  • engine (Optional[Literal['remote', 'local']]) – The execution engine to use ('remote' or 'local').
  • instance_type (Optional[InstanceType]) – The type of instance to use for remote execution ('realtime', or 'small', 'medium', 'large' or one of the whitelisted instance types). If not specified, gets the default from the UDF or defaults to 'realtime'.
  • disk_size_gb (Optional[int]) – The size of the disk in GB to use for remote execution (only supported for a batch instance type).
  • type (Optional[Literal['tile', 'file']]) – The type of UDF execution ('tile' or 'file').
  • max_retry (int) – The maximum number of retries to attempt if the UDF fails. By default does not retry.
  • cache_max_age (Optional[str]) – The maximum age when returning a result from the cache. Supported units are seconds (s), minutes (m), hours (h), and days (d) (e.g. "48h", "10s", etc.). Default is None so a UDF run with fused.run() will follow cache_max_age defined in @fused.udf() unless this value is changed.
  • cache (bool) – Set to False as a shortcut for cache_max_age='0s' to disable caching.
  • parameters (Optional[Dict[str, Any]]) – Additional parameters to pass to the UDF.
  • **kw_parameters – Additional parameters to pass to the UDF.

Raises​

  • ValueError – If the UDF is not specified or is specified in more than one way.
  • TypeError – If the first parameter is not of an expected type.

Returns​

The result of the UDF execution, which varies based on the UDF and execution path.

Examples​

Run a UDF saved in the Fused system:

fused.run("username@fused.io/my_udf_name")

Run a UDF saved in GitHub:

loaded_udf = fused.load("https://github.com/fusedio/udfs/tree/main/public/Building_Tile_Example")
fused.run(loaded_udf, bbox=bbox)

Run a UDF saved in a local directory:

loaded_udf = fused.load("/Users/local/dir/Building_Tile_Example")
fused.run(loaded_udf, bbox=bbox)
note

This function dynamically determines the execution path and parameters based on the inputs. It is designed to be flexible and support various UDF execution scenarios.