Skip to main content

Write UDFs

File

Follow these steps to write a User Defined Function (UDF).

@fused.udf decorator​

First decorate a Python function with @fused.udf to tell Fused to treat it as a UDF.

Function declaration​

Next, structure the UDF's code. Declare import statements within the function body, express operations to load and transform data, and define a return statement. This UDF is called udf and returns a pd.DataFrame object.

@fused.udf # <- Fused decorator
def udf(bbox: fused.types.Bbox = None, name: str = "Fused"): # <- Function declaration
    import pandas as pd

    @fused.cache # <- Cache decorator
    def structure_output(name):
        return pd.DataFrame({'message': [f'Hello {name}!']})

    df = structure_output(name)
    return df

Use the @fused.cache decorator to persist a function's output across runs so UDFs run faster.

info

Workbench imports the fused module automatically. To write UDFs outside of Workbench, install the Fused Python SDK with pip install fused.

Typed parameters​

UDFs resolve input parameters to the types specified in their function annotations. This ensures parameters serialized in HTTP calls resolve to their intended types at run time.

@fused.udf
def udf(
    bbox: fused.types.Bbox = None, # <- Typed parameters
    name: str = "Fused"
):
tip

To write UDFs that run successfully as both File and Tile, set bbox as the first parameter, with None as its default value. This enables the UDF to be invoked successfully both as File (when bbox isn’t passed) and as Tile. For example:

@fused.udf
def udf(bbox: fused.types.Bbox = None):
    ...
    return ...

Supported types​

Fused supports the native Python types int, float, bool, list, dict, and list. Parameters without a specified type are handled as strings by default.

The UDF Editor runs the UDF as a Map Tile if the first parameter is typed as fused.types.Bbox, fused.types.TileXYZ, or fused.types.TileGDF.

pd.DataFrame as JSON​

Pass tables and geometries as serialized UDF parameters in HTTPS calls. DataFrames passed as JSON strings show up as a pd.DataFrame when typed. GeoJSON strings as a gpd.GeoDataFrame.

@fused.udf
def udf(
    df: pd.DataFrame = None,
    gdf: gpd.GeoDataFrame = None,
):

Reserved parameters​

When running a UDF with fused.run, it's possible to configure the bbox object that Fused will pass to the UDF using reserved parameters. A map tile can be specified with x, y, z, with a bbox GeoDataFrame, or with a bounds array.

utils Module​

Define a UDF's utils Module file in the Workbench "Module" tab and import it in the UDF. Use it to modularize code to make it readable, maintainable, and reusable.

from utils import function

Import utils from other UDFs​

UDFs import the utils Module from other UDFs with fused.load in the UDFs GitHub repo or private GitHub repos. Here the commit SHA 05ba2ab pins utils to specific commit for version control.

utils = fused.load(
    "https://github.com/fusedio/udfs/tree/05ba2ab/public/common/"
)

Modules in the public UDFs repo are imported from fused.utils.

utils = fused.utils.common

utils Module are imported from other UDFs in a user's account.

utils = fused.load("your@email.com/my_udf").utils

return object​

UDFs return either a table or an array.

  • Tables can be: pd.DataFrame, pd.Series, gpd.GeoDataFrame, gpd.GeoSeries, and shapely geometry.
  • Arrays can be: numpy.ndarray, xarray.DataArray, and io.BytesIO. Fused Workbench only supports the rendering of uint8 arrays. Rasters without spatial metadata should indicate their tile bounds.

Save UDFs​

UDFs exported from the UDF Builder or saved locally are formatted as a .zip file containing associated files with the UDFs code, utils Module, metadata, and README.md.

└── Sample_UDF
    ├── README.MD       # Description and metadata
    ├── Sample_UDF.py   # UDF code
    ├── meta.json       # Fused metadata
    └── utils.py        # `utils` Module

When outside of Workbench, save UDF to your local filesystem with my_udf.to_directory('Sample_UDF') and to the Fused cloud with my_udf.to_fused().

Debug UDFs​

UDF builder​

A common approach to debug UDFs is to show intermediate results in the UDF Builder results panel with print statements.

HTTP requests​

When using HTTP requests, any error messages are included in the X-Fused-Metadata response header. These messages can be used to debug. To inspect the header on a browser, open the Developer Tools network tab.

File