Skip to main content

Run UDFs

All UDFs have a secure HTTP endpoint callable via a web request or fused.run that is authorized with a shared or private token. The endpoint's response may be cached and have its type specified.

fused.run​

The first argument of fused.run specifies the UDF. Reserved parameters control how the UDF will be executed, and any additional arguments are passed to the UDF itself. The UDF can be specified with a string identifier, shared token, or a UDF object. The UDF object can be defined in the code or loaded with fused.load. The UDF runs as Tile if a bbox is specified.

Ways to run a UDF​

With a public id. Use this to run UDFs in the public repo. This does not require authentication.

fused.run('fsh_PC_File_Example')

With a shared token. Use this for you or others to run your shared UDFs, or to run UDFs that others shared with you. This does not require authentication and runs on the account that owns the token.

fused.run('fsh_aJHN0awSfHLpYYinPSLYC')

With a name and a private token. Use this for you or your organization to run your private UDFs. This requires authentication and access to the UDF.

fused.run("user@fused.io", "Overture_Maps")

With GitHub and a private token. Use this to load and run UDFs from a GitHub repo. This requires authentication.

udf = fused.load("https://github.com/fusedio/udfs/tree/main/public/REM_with_HyRiver/")
fused.run(udf)

With a UDF object. Declare or load a UDF then pass it to fused.run. Loading the UDF may require authentication. Execution requires authentication unless the UDF runs with the local execution engine.

@fused.udf
def my_udf():
    return ...

The UDF object can also be loaded from a user account using fused.load.

my_udf = fused.load("username@fused.io/REM_with_HyRiver")

Pass the UDF object to fused.run to execute the UDF.

fused.run(my_udf)

Execution engines​

fused.run can run the UDF in various execution modes, as specified by the engine parameter either local, realtime, or batch mode.

  • local: Run in the current process. This is set by default.
  • realtime: Run in the serverless Fused cloud engine.
  • batch: Run in a server in the Fused cloud. Best for long-running jobs.
fused.run(my_udf, engine="realtime")

Set sync=False to run a UDF asynchronously.

HTTP requests​

In the UDF Builder, you can create an HTTP endpoint for a UDF in the "Snippets" section. This generates a unique URL to call the UDF via HTTP requests. The URL is scoped to that UDF only and it can be revoked to disable access. The same can be done with the Fused Python SDK.

Shared token​

To run a UDF via HTTP request, create a shared token then modify the provided URL. Manage your account's shared tokens in fused.io/profile#tokens.

Structure the URL with the file path parameter to run as a single batch operation.

https://www.fused.io/server/v1/realtime-shared/******/run/file?dtype_out_raster=png

To integrate with a tiling service, structure the URL with the tiles path parameter, followed by templated /{z}/{x}/{y} path parameters. See Lonboard for an example.

https://www.fused.io/server/v1/realtime-shared/******/run/tiles/{z}/{x}/{y}?dtype_out_raster=png

Private token​

Calling UDFs with Bearer authentication requires an account's private token. The URL structure to run UDFs with the private token varies slightly, as the URL specifies the UDF's name and the owner's user account.

curl -XGET "https://app.fused.io/server/v1/realtime/fused/api/v1/run/udf/saved/user@fused.io/caltrain_live_location?dtype_out_raster=png" -H "Authorization: Bearer $ACCESS_TOKEN"

Specify parameters​

When UDF endpoints are called via HTTP requests argument values are specified with query parameters, which require input parameters to be serializable. As such, the UDF should specify the types to cast them to. Read more about supported types for UDF parameters.

Response data types​

The dtype_out_vector and dtype_out_raster parameters define the output data type for vector tables and raster arrays, respectively.

  • The supported types for vector tables are parquet, geojson, json, feather, csv, mvt, html, excel, and xml.
  • For raster array: png, gif, jpg, jpeg, webp, tif, and tiff.
https://www.fused.io/server/v1/realtime-shared/****/run/file?dtype_out_raster=png

Read how to structure HTTP endpoints to call the UDF as a Map Tile & File.

Caching responses​

If a UDF's cache is enabled, its endpoints cache outputs for each combination of code and parameters. The first call runs and caches the UDF, and subsequent calls return cached data.