Skip to main content

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.

Create UDF to read your data​

Option 1: Use the Fused Workbench​

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 + 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 Stdout tab of 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

Edit a UDF​

The power of Fused Workbench is the ability to easily edit your code and it executes instantly without you having to hit "Run"

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 6 to 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

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 stdout 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:

  1. The map view only shows 2 states now
  2. The stdout only has 2 rows

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 stdout 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
  • Go to the ⚙ Settings Tab
  • Under Share click Sharing to see all the sharing operations

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 [Beta]​

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

note

Fused Apps are still in Beta. To enable them you need to go to the bottom left of Workbench -> ⚙️ (Preferences) -> Under "Experimental Features", tick "Enable apps builder (Beta)"

You can use Streamlit components to create an app in the App Builder, found on the sidebar, after you've enabled it. 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_31xNwyPRtpOIM2Jq1x6dy4"))

It should look like this:

Your first Fused App!

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
  • Look into the UDF Catalog to find UDFs from the community you could leverage
  • Browse through some of the Use Cases examples we have
  • 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! 🚢