Hex 101

tip

If you're an Admin setting up your Hex workspace for the first time, check out the Workspace admin 101.

What you'll learn

By the end of this 15 minute quickstart tutorial, you'll understand the basic building blocks of a Hex project, and how they come together. You'll have gone from zero to publishing an actual data application available to anyone!

We'll cover how to:

1. Create your Hex account and first new project.
2. Connect to data
3. Add your first Python cell
4. Run cells
5. Use SQL Cells
6. Add Input parameters
7. Visualize project organization & execution
8. Build an app
9. Publish and share an app

1. Create your Hex account and first project

Create a new account at https://app.hex.tech/signup. If you already have a Hex account, you can go to https://app.hex.tech/ to access it.

The Projects home is where you can quickly find all the projects you've created, as well as projects that other users in your workspace have shared with you.

To start a new Hex project, click the New project button from the projects home.

Once you click the New project button, you will be brought to the Notebook view of your project. Here you can rename your project before you get started!

2. Connect to data

Let's start by getting some data into our project. We recommend setting up a data connection using Hex-supported connection templates. Navigate to the project sidebar's Data sources tab to begin.

Fill in the relevant connection details and make sure that Hex is allowed to connect to your data source. If your workspace has data connections configured, you'll see them here too.

To query your new data connection, simply hover over the data connection you'd like to query and select the Query option. Voila, now you have a SQL cell whose source has been automatically set to your data connection!

3. Adding your first Python cell

The Notebook view of a Hex project is broken up into cells. In a new Hex project, you'll be prompted to begin with a SQL cell, a Python cell, a component, or upload a CSV. These are the building blocks of your project. Hex can seamlessly transition between SQL and Python cells as often as you'd like.

After adding a new Python cell, you'll see that cell appear at the top of the Notebook view. If you've used code notebooks before, you might be feeling a twinge of recognition — this environment is very similar to a Jupyter notebook, but with many added features.

The seaborn Python package provides some sample datasets, so let's load one in:

#Import the seaborn package and aliases as sns, which is shorter
import seaborn as sns
#Use the sns.load_dataset function to import the `penguins` dataset
penguin_data = sns.load_dataset('penguins')

Copy this Python code into the first cell, and hit cmd + enter or click the run icon to run it. Right off the bat, it won't feel like too much has happened.

But look a little closer, and you'll notice a few things have changed...

4. Running the first cell

Running the first cell in a new project "wakes up" the kernel that powers the project. In the bottom right corner, now you'll see a green heartbeat indicating that the kernel is running — you can hover over it to see how long it will stay active for.

Important note: This means that you can start running a very long process in a Hex project, close your laptop, head out for a walk, and the process will continue to run as long as the kernel doesn't expire. You don't need to be in the project for it to work.

You'll also notice that there are two little chips at the bottom of your first cell, one for each variable assigned. You'll see this helpful output on every cell, to help keep track of what's being created.

In this Python cell, you can write any Python you want and any variables assigned in one cell will be available to other cells in the Notebook view to reference.

Hot tip: You can change the label of any cell! In that screenshot, where it says "Cell 0", you can click and write your own text. In an app (getting to that later) this text will show up as a heading, but it can also just be useful for organizing your logic.

5. Use SQL cells

Hex supports both Python and SQL cells, and they can seamlessly communicate between each other. A great example of this that doesn't require you to set up a database connection is Dataframe SQL.

Dataframe SQL lets you write SQL queries against any dataframe in your project, returning the result of the query as another dataframe that can, of course, be queried with SQL. This allows for easy and ergonomic access to pandas dataframes, as well as complex chained SQL queries.

As you hover over the penguin_data dataframe output, you'll be presented with a tooltip detailing the variable and its usage. You also have several options: Query with SQL, Pivot dataframe, Filter dataframe, View as a table display, and Visualize in chart. Pivot and Filter cells are helpful for exploring and transforming your dataframe. Table Display cells are a great way to display tabular data, and we'll get to that shortly. Chart cells visualize your dataframe in a variety of chart options, more on these in the docs.

For now, select Query with SQL. This adds a second cell to the notebook — a SQL cell!

You'll notice that the Source for this SQL query is "Dataframes", which means that all dataframes in the project are available as tables to query. You can even join multiple dataframes together.

Let's add a filter to this query by adding WHERE species = 'Adelie' and run it by hitting cmd + enter or clicking the Run button. The updated query should be:

select * from penguin_data
WHERE species = 'Adelie'

The query returns a preview of the result and, just like that, you've created your first Hex project that interleaves Python and SQL.

You'll note that in the screenshot above we've selected the Display option, which returns your query result as a Table Display cell. With Display cells you can sort, rename columns or change formatting, add conditional color formats, and paginate through the results. For a full list of features for these Table Display cells, see the docs.

You can also add a Table Display cell anywhere in your project by either hovering over a dataframe name (in this case dataframe) to View as Table Display, or by selecting Table Display cell from the "Add Cell" bar that appears between cells on hover.

6. Add Input parameters

Let's add some context to your project by adding a title using a Markdown cell. You can use familiar markdown syntax here to create titles or headings, add explanations, or even write long form articles.

Let's just add a title at the top of the logic: # Penguin Species Data. You'll see the markdown rendered immediately and the cell appear in the Outline as well.

Hot tip: You can parameterize markdown with Python variables, but this is a more advanced technique. See how in the docs.

We'll add one more type of cell, and then call our App complete. Let's add an Input Parameter, a way to make apps interactive to end users. There are several kinds of input parameters but we'll just use a Dropdown for now.

Add a dropdown just above the SQL cell, between cells 1 and 2.

Label this dropdown as "Species", and make the values Dynamic. You can provide a static list of values to any input parameter, but in this case it makes more sense to just feed it from the list of penguin species we already have.

Select the "penguin_data" dataframe and the "species" column.

Click Save, and you'll see the dropdown auto-populate with penguin species.

Now let's actually use this parameter. In your SQL cell (cell 3, now), change the WHERE filter to reference the input parameter instead of a hardcoded species. We do this using jinja syntax.

SELECT * from penguin_data
WHERE species = {{ species }}

Now, try selecting "Chinstrap" from the species dropdown. That reactive execution will kick in since the SQL cell is a dependent on the input parameter, and its entire output should change to reflect entries where the species = "Chinstrap" (or whatever value you chose the dropdown input parameter to be).

7. Visualize project organization and execution

Now that you have three different cells in your project, you'll notice some more things about the way Hex projects work.

First, with the Outline, the first option on the left sidebar, you can see small previews of each cell and easily navigate between cells in larger projects by clicking on a cell in the Outline to jump to that location in the project or filtering by the type of cell using the dropdown.

Second, on the far right side of the Notebook view you can pop open the Graph. The graph visualizes the lineage of your entire project as a DAG so you can see how data flows through the project, and most importantly, see which cells reference other cells.

This powers Hex's reactive execution model, which is very different than any other notebook you may have used. Whenever you run a cell in a Hex project, the dependency graph of the project is computed and all children of that cell are re-run automatically. Cells that don't depend on the newly run cell aren't run, saving compute time and making Hex projects feel snappy.

Let's try it out this reactive execution model by changing the species filter in the penguin SQL query from 'Adelie' to 'Gentoo'. Hit cmd+ enter to re-run that cell, and watch as the SQL cell is automatically refreshed to reflect the new data.

8. Build an App

Now let's turn this project into an App that can be shared with and consumed by your end users. To begin building your App, click over to the App builder using the top menubar (or typing opt + shift + 2)

You can opt for Hex to auto-generate the layout of your app based on the contents of your Notebook view by clicking the Autogenerate layout button. To customize the layout of your app, you can add elements from the Outline panel on the left using drag-and-drop or the Add to app button. To remove elements, hover over the element and select the red 'X' or unclick the Added to app button in the Outline panel.

9. Publish and share an app

All that's left to do is publish this so that the world (or your colleagues) can see it!

Click Publish in the top right corner and you'll get one last publish preview before it goes live. This also saves a checkpoint, so you can always restore your app to this point in time if you make any future changes. Clicking Publish Version makes the app live for anyone who has access.

If you're curious about what your end users are seeing, you can always view your App from the View live version button.

In the Share dialog, you can choose who to share the project with and control what level of access they have — whether it's the ability to edit or view the entire project, or just to interact with the published app.

Summary

Congratulations! You've published your first Hex app. This whole process is more fun with collaborators, so make sure to invite some coworkers and share your projects with them. You can leave comments, share multiplayer sessions, and more — see the docs if you're curious.

Hex is a powerful tool and there are certainly topics we didn't cover in this 101 tutorial: Chart cells, other input parameters, dynamic markdown, scheduled runs, and much, much more. We recommend checking out our docs and use case gallery to explore further.