Get started with Fused! 🚀

Learn the fundamental concepts of working with Fused.

This guide is an introduction to Fused Workbench. It covers the concepts and terminology you will come across as you work with data using the web-based IDE. After reading this page you should have an understanding of the fundamentals to build Fused UDFs and apps.

If you get stuck, please ask for help in the Fused Discord. 😊

Introduction

A Fused User Defined Function (UDF) is a Python function that interacts with your data and can be called via HTTP requests. You can create UDFs from cloud storage files with the File Explorer or clone existing UDFs from the UDF Catalog. You edit UDFs in the UDF Builder and create & share apps that interact with your UDFs in the App Builder.

note

You'll need to be logged in with an account to be able to follow this Quickstart guide

Without having an environment you can still access Workbench, install fused locally and run Public UDFs (in Workbench & locally). You can also run any UDF you want locally with fused.run(my_udf, engine='local').

Create your first UDF

In Workbench
Locally

Workbench is Fused browser-based IDE. We have a whole detailed section about it, but we'll take you through the basics here.

You can start by opening Fused Workbench in another tab.

Choose Add UDF and then + New UDF, which will start creating a new UDF:

Welcome to workbench! 🛠️

You now have access to a full Python development environment directly in your browser, where you can

Edit your UDFs in real time
See the geospatial output in the map view
Debug & explore data in the Results page

info

You can still use Workbench as a read-only user if you aren't signed-up, but to use the full benefit of workbench, login or join our waitlist

You can also do everything from your local machine (or anywhere else!) using fused. To use fused locally you first need to install it:

pip install fused

info

We recommend you use a virtual environment to work with fused and you'll need python >=3.11. Read more in the dedicated Install Fused section

We recommend using jupyter notebooks as these allow you to run cell by cell and see output directly under code blocks. In a new notebook we can define our first UDF. Here's the default "New UDF" in Workbench:

@fused.udf
def udf(message: str = "Hello World!"):
    return message

You can now run this UDF from your notebook:

msg = fused.run(udf)

note

You'll need to be logged in to be able to run a UDF on our Fused server.

If you either don't have an account or only have a free account without any environment you can still run UDF, but locally on your device:

msg = fused.run(udf, engine='local')

By default fused.run() executes your UDFs, allowing you to write code locally and execute it on our server without manually having to deploy anything!

You can make changes in your notebook and directly run your UDF. This is powerful if you want to manipulate data on the cloud directly without having to pull all the data locally!

Edit a UDF

The power of Fused is how quickly you can iterate and execute your code with little thought to deploying it

We'll demo the rest of this section in Workbench but you can follow along in a notebook if you'd like to as well!

Workbench allows you to easily edit your code and it executes instantly without you having to hit "Run". The UDF editor calls fused.run(udf) under the hood for you upon updates to the code.

Let's give it a try, replace the default UDF with this code into the UDF Builder to render subway stations on a map:

@fused.udf
def udf():
    import geopandas as gpd
    DATASET = 'https://raw.githubusercontent.com/python-visualization/folium-example-data/main/subway_stations.geojson'
    gdf = gpd.read_file(DATASET)
    return gdf

You don't need to move your data to a Fused bucket to access it, so we can easily change the input data. Let's do just that: Change line 4 with a completely different dataset:

@fused.udf
def udf():
    import geopandas as gpd
    DATASET = "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json"
    gdf = gpd.read_file(DATASET)
    return gdf

info

The map updates automatically using from the geospatial information returned by udf(). This interaction goes both ways as the map can pass coordinates into the UDF with bounds or XYZ indices, allowing Fused to spatially filter data.

Let's explore this data a bit more, the map shows us we have US states, let's print out some more info about it, just before the return:

@fused.udf
def udf():
    import geopandas as gpd
    DATASET = "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json"
    gdf = gpd.read_file(DATASET)
    print(gdf)
    return gdf

The Results view shows us we have a name column in our GeoDataFrame, so we can leverage geopandas to filter only a few states:

@fused.udf
def udf():
    import geopandas as gpd
    DATASET = "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json"
    gdf = gpd.read_file(DATASET)
    gdf = gdf[gdf['name'].isin(['California', 'Texas'])]
    print(gdf)
    return gdf

You can notice this change in 2 places:

The map view only shows 2 states now
The Results section now displays only 2 data rows below the header

All that, without having to ever press "Run"!

note

If you move print(gdf) before gdf = gdf[gdf['name'].isin(['California', 'Texas'])] you will still see 50 lines in Results and 2 in the map view, because the print statement happens before filtering

Keep this in mind when using print to debug

Get your data from a HTTP endpoint

The UDF we now have returns a GeoDataFrame with 2 rows, that's what we see in the map view.

We can edit this UDF as much as we want but for now we're going to get this data out of Fused. You might expect us to hit a "Download" button somewhere and save this as a GeoJSON, but while you can do this, we're going to do something better - Call this UDF from a HTTP endpoint:

Make sure to save your UDF by either clicking 💾 Save or pressing Ctrl + S on Windows / Linux or Cmd + S on MacOS
Click Share
In the Share modal click Share to view all available sharing options.

We've pre-populated a few examples of ways to share these Fused UDFs, but at its core you can call these UDFs as HTTP endpoints

UDFs aren't just Python functions you can run in Workbench, they're fully deployed functions that you can call from anywhere.

To keep it simple to start, we can use the cURL option. Open a terminal and the cURL command, you'll get something like:

curl -L -XGET "https://www.fused.io/server/v1/realtime-shared/<YOUR_UDF_ID>/run/file?dtype_out_raster=png&dtype_out_vector=csv"

Let's break that down:

curl -L XGET -> curl syntax to GET and automatically follow a redirect
https://www.fused.io/server/v1/realtime-shared/ -> When you call a UDF, Fused automatically creates a file from the return of the UDF, this is where we host it
<YOUR_UDF_ID> -> Your unique UDF ID. Fused handles this for you
run/file?dtype_out_raster=png&dtype_out_vector=csv -> Tells Fused we want a file (more about this in future sections) and what data type. Fused can return Rasters or Vectors, we're telling it give us either here, with rasters as PNG files and vector as CSV

So, if you run this, you'll get something like this:

cURL UDF output

That's a CSV, with 2 rows and a lot of coordinates, our geometry!

This is nice, but these geometries are quite verbose in CSV format.

Let's go back to our UDF and remove geometry from our return:

@fused.udf
def udf():
    import geopandas as gpd
    DATASET = "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json"
    gdf = gpd.read_file(DATASET)
    gdf = gdf[gdf['name'].isin(['California', 'Texas'])]
    print(gdf)
    return gdf[['id', 'name']]

Remember to save, and notice how the geometries disappear from our map view: there's nothing to display anymore.

Now, in your terminal, rerun the same curl request:

cURL UDF output without geometry

No more geometry, just 2 rows with id and name, exactly as we had in our UDF return !

That's the real power of Fused: you don't have to deploy anything. Just edit your code, save it and then next time your UDF is called through HTTP, the data created will reflect your UDF!

Create an app

Sometimes we simply want to show the results of our analysis to someone else, which is what Fused Apps are for.

You can use Streamlit components to create an app in the App Builder, found on the sidebar. You can then move from UDF builder to App Builder.

Here's a basic example to show our dataframe:

import fused
import streamlit as st

st.write("# Hello World! 👋")
st.write(fused.run("fsh_2kTEwnRARTd9gdDGUbH6ll"))

As we change our UDF, the output will also change in the app directly, just like we saw with curl

You can then share your Fused app to anyone simply by sharing the link at the top of the App Builder:

These links work without needing a Fused account or the need to install anything, allowing you to share your work easily to anyone!

Next steps

Congratulations, you've touched on all the core features of Fused. 🎉

Now you can dive deeper into more advanced topics:

Learn more about UDFs (We showed how to return static vector files, but we can do a lot more!)
Take a deeper look at Workbench
Play around with the Use Cases to see Fused in action
Look into the UDF Catalog to find UDFs from the community you could leverage
Dive into the fused Python SDK
Learn about how Fused handles caching
Join Discord to connect with the community and discover what's possible

Welcome aboard! 🚢

Introduction​

Create your first UDF​

Edit a UDF​

Get your data from a HTTP endpoint​

Create an app​

Next steps​

Introduction

Create your first UDF

Edit a UDF

Get your data from a HTTP endpoint

Create an app

Next steps