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 specify bbox
and control how the UDF will be executed. Any additional arguments are passed to the function. The UDF runs as Tile if a bbox
is specified.
Ways to run a UDF
You can specify the UDF to run in the first udf
parameter of fused.run
by name, tokens, or a UDF object.
Name
UDF name. Use this to run UDFs in your account. This requires authentication.
fused.run("My_Udf")
Tokens
Public token. Reference UDFs in the public repo by prefixing their name with UDF_
. This does not require authentication.
fused.run('UDF_Get_Isochrone')
Shared token. Shared tokens, prefixed with fsh_
, allow anyone to run a UDF from anywhere. It does not require authentication and runs on the execution environment of account that created the token.
fused.run('fsh_aJHN0awSfHLpYYinPSLYC')
UDF object
You may also pass a UDF object to fused.run
. Define a UDF in the local process, or load one with fused.load
from GitHub or your account.
Local UDF object. Define a UDF and pass the function object.
@fused.udf
def local_udf():
import pandas as pd
return pd.DataFrame({})
fused.run(local_udf)
Load from GitHub. Loading the UDF requires read access to the repo.
gh_udf = fused.load("https://github.com/fusedio/udfs/tree/main/public/REM_with_HyRiver/")
fused.run(gh_udf)
Load from your account. Specify the name of the UDF in your account.
my_udf = fused.load("My_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.realtime
: Run in the serverless Fused cloud engine.batch
: Run a long-running job in a Fused server. This must first be enabled for the account.
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
, andxml
. - For raster array:
png
,gif
,jpg
,jpeg
,webp
,tif
, andtiff
.
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.