# Hex
> Connect Hex notebooks to MotherDuck using SQL data connections or Python cells for interactive analytics.
[Hex](https://hex.tech/) is a software platform for collaborative data science and analytics using Python, SQL and no-code.

You have two ways to connect to MotherDuck using Hex:
- **Using SQL cells with a data connection**: MotherDuck is a supported [data connection in Hex](https://learn.hex.tech/docs/connect-to-data/data-connections/data-connections-introduction#supported-data-sources).
- **Using Python cells**: You can use Python cells to connect to MotherDuck and query data using DuckDB.

## Using SQL cells with a data connection

:::tip
When many human users query through the same MotherDuck data connection, consider using a [read scaling token](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/).
Hex will then route the queries to a dedicated Duckling per Hex kernel, up to the maximum pool size determined by your organization admin.
What this means in practice:
* Each workbook will get a stable backend for each unique data connection.
  Multiple users collaborating on the same workbook will share the Duckling to query faster on warm data caches.
* In a published app, each user will get a stable backend for each data connection to power their own unique exploration.
:::

To add a new data connection, head over the Data browser in a new notebook and click on `Add data connection`.

![hex_data_browser](../img/hex_data_browser.png)

Select `MotherDuck` as the data source and fill in the required fields. The most important is the MotherDuck token, which you can find in the [MotherDuck UI](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#creating-an-access-token).

![hex_configuration](../img/hex_configuration.png)

Once done, you can use the data browser to explore the tables and columns and directly specify your data connection in your SQL cell.

![hex_data_browser](../img/hex_data_browser_2.png)

![hex_sql_cell](../img/hex_sql_cell.png)

### Query some data

Add another cell and run the same query we ran in a Python cell :

```sql
SELECT dayname(tpep_pickup_datetime) AS day_of_week, strftime('%H', tpep_pickup_datetime) AS hour_of_day, COUNT(*) AS trip_count
FROM sample_data.nyc.taxi
GROUP BY day_of_week, hour_of_day
ORDER BY day_of_week, hour_of_day;
```

This produces both a table and a Dataframe, which you can utilize in the same manner as we previously demonstrated with Python to generate data visualizations.

![hex_sql_result](../img/hex_sql_result.png)

## Using Python cells

:::tip Use Python 3.12 or later
When using Python cells in your environment to connect to MotherDuck, set your Hex project's Python version to 3.12 or later to ensure you have a compatible version of DuckDB pre-installed in your Hex environment.

To change your Python version, go to **Settings** --> **Environment** and select **Python 3.12** or **Latest**.
:::

If you prefer programming in Python, you can use Python cells to connect to MotherDuck and start query data. You can jump directly on the [Hex notebook](https://app.hex.tech/c0083b53-a04f-47b1-bff7-a9ff12590a9f/hex/5c85b3e2-3df7-4011-87a0-1fff63787d03/draft/logic) for a quickstart.

The notebook highlight how you can query data using Python or SQL cells and display charts!

### Storing your MotherDuck token

The first step is to safely store your MotherDuck token. You can do this by [creating a new secret in Hex.](https://learn.hex.tech/docs/environment-configuration/environment-views#secrets)

![Hex secrets](../img/hex_secrets.png)

Let's add your [MotherDuck access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/authenticating-to-motherduck.md#authentication-using-an-access-token) under the name `motherduck_token`.

![Hex secrets2](../img/hex_secrets_2.png)

Once done, add the next Python cell to export as environment variable your `motherduck_token`. This will be detected by SQL/Python processes when authenticating to MotherDuck.

```python
# Passing the secrets as environment variable for Python/SQL cell auth
# Fill in your token as a Hex project secret https://learn.hex.tech/docs/environment-configuration/environment-views#secret
import os
os.environ["motherduck_token"] = motherduck_token
```

### Connecting to MotherDuck

DuckDB is already pre-installed in the Hex environment, so you can connect to MotherDuck directly.

Add a Python cell and run the following code:

![Hex add cell](../img/hex_add_cell.png)

```python
import duckdb

# Connect to MotherDuck using Python
conn = duckdb.connect(f'md:')
```

### Query some data and display a chart

You can query data from the [sample_data database](/getting-started/sample-data-queries/datasets.mdx). The following example runs a query and returns the result as a pandas dataframe to display as a chart.
This database is auto-attached to any MotherDuck user, so you can query it directly.

Add another Python cell and run the following code:

```python
# Query sample_data database and convert it to a pandas dataframe for dataviz
peak_hours = conn.sql("""
SELECT dayname(tpep_pickup_datetime) AS day_of_week, strftime('%H', tpep_pickup_datetime) AS hour_of_day, COUNT(*) AS trip_count
FROM sample_data.nyc.taxi
GROUP BY day_of_week, hour_of_day
ORDER BY day_of_week, hour_of_day;""").to_df()
```

Now we can display the chart using the Visualization cell. Add a new Visualization cell, type `Chart` and select the dataframe we just created `peak_hours`.

![Hex chart](../img/hex_chart_df.png)

Finally, play with the parameters to obtain the following chart which gives you a weekly view of the peak hours in New York City for the yellow cabs.

![Hex chart peak hours](../img/hex_chart_peak_hours.png)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `POST https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

Payload:

```json
{
  "page_path": "/integrations/bi-tools/hex/",
  "page_title": "Hex",
  "text": "<the user's feedback, max 2000 characters>",
  "source": "<optional identifier for your interface, for example 'claude.ai' or 'chatgpt'>"
}
```

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed payloads, and `429` when rate-limited.