264 lines
9.1 KiB
Markdown
264 lines
9.1 KiB
Markdown
Use [Apache Superset](https://superset.apache.org/) to query and visualize data
|
|
in {{< product-name >}}.
|
|
|
|
> Apache Superset is a modern, enterprise-ready business intelligence web application.
|
|
> It is fast, lightweight, intuitive, and loaded with options that make it easy for
|
|
> users of all skill sets to explore and visualize their data, from simple pie
|
|
> charts to highly detailed deck.gl geospatial charts.
|
|
>
|
|
> {{% cite %}}-- [Apache Superset documentation](https://superset.apache.org/docs/intro){{% /cite %}}
|
|
|
|
> [!Important]
|
|
> **Apache Superset only supports SQL**. You can not use Superset to query
|
|
> {{< product-name >}} with InfluxQL.
|
|
|
|
<!-- TOC -->
|
|
|
|
- [Set up Docker for Superset and Flight SQL](#set-up-docker-for-superset-and-flight-sql)
|
|
- [Install prerequisites](#install-prerequisites)
|
|
- [Set up Docker for Superset](#set-up-docker-for-superset)
|
|
- [Start the Superset Docker containers](#start-the-superset-docker-containers)
|
|
- [Log in to Superset](#log-in-to-superset)
|
|
- [Create a database connection for InfluxDB](#create-a-database-connection-for-influxdb)
|
|
- [Query InfluxDB with Superset](#query-influxdb-with-superset)
|
|
- [Build visualizations with Superset](#build-visualizations-with-superset)
|
|
|
|
<!-- /TOC -->
|
|
|
|
## Set up Docker for Superset and Flight SQL
|
|
|
|
### Install prerequisites
|
|
|
|
We recommend using **Docker and docker-compose** to run Superset.
|
|
To set up Superset to run in Docker containers with Flight SQL, follow these steps:
|
|
|
|
> [!Warning]
|
|
> **Superset** is not officially supported on Windows. For more information about
|
|
> running Superset with Windows and Docker, see the
|
|
> [Superset documentation](https://superset.apache.org/docs/installation/installing-superset-using-docker-compose#1-install-a-docker-engine-and-docker-compose).
|
|
|
|
1. Follow the instructions to download and install Docker and docker-compose for your system:
|
|
|
|
- **macOS**: [Install Docker for macOS](https://docs.docker.com/desktop/install/mac-install/)
|
|
- **Linux**: [Install Docker for Linux](https://docs.docker.com/desktop/install/linux-install/)
|
|
|
|
2. Follow the [Python.org Downloading Python](https://wiki.python.org/moin/BeginnersGuide/Download)
|
|
instructions for your system.
|
|
|
|
3. Once you've installed Python, check that you can run Python and Pip.
|
|
Depending on your system, you may need to use the Python version 3 (`python3` and `pip3`) commands.
|
|
Enter the following commands into your terminal:
|
|
|
|
{{< code-tabs-wrapper >}}
|
|
{{% code-tabs %}}
|
|
[python](#)
|
|
[python3](#)
|
|
{{% /code-tabs %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
python --version
|
|
```
|
|
```sh
|
|
pip --version
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
python3 --version
|
|
```
|
|
```sh
|
|
pip3 --version
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{< /code-tabs-wrapper >}}
|
|
|
|
If neither `pip` nor `pip3` works, follow one of the
|
|
[Pypa.io Pip Installation](https://pip.pypa.io/en/stable/installation/)
|
|
methods for your system.
|
|
|
|
3. Use Pip to install the `flightsql-dbapi` library.
|
|
|
|
{{< code-tabs-wrapper >}}
|
|
{{% code-tabs %}}
|
|
[pip](#)
|
|
[pip3](#)
|
|
{{% /code-tabs %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
pip install flightsql-dbapi
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{% code-tab-content %}}
|
|
```sh
|
|
pip3 install flightsql-dbapi
|
|
```
|
|
{{% /code-tab-content %}}
|
|
{{< /code-tabs-wrapper >}}
|
|
|
|
The `flightsql-dbapi` library for Python provides a
|
|
[DB API 2](https://peps.python.org/pep-0249/) interface and
|
|
[SQLAlchemy](https://www.sqlalchemy.org/) dialect for
|
|
[Flight SQL](https://arrow.apache.org/docs/format/FlightSql.html).
|
|
Later, you'll add `flightsql-dbapi` to Superset's Docker configuration.
|
|
|
|
> [!Warning]
|
|
> The `flightsql-dbapi` library is experimental and under active development.
|
|
> The APIs it provides could change at any time.
|
|
|
|
4. Use Git to clone the Apache Superset repository:
|
|
|
|
```sh
|
|
git clone https://github.com/apache/superset.git
|
|
```
|
|
|
|
The repository contains Superset code and configuration files for running
|
|
Superset in Docker containers.
|
|
|
|
### Set up Docker for Superset
|
|
|
|
1. Change to your **superset** repository directory:
|
|
|
|
```sh
|
|
cd ./superset
|
|
```
|
|
|
|
2. In your text editor or terminal, create the file `./docker/requirements-local.txt`
|
|
and append the line `flightsql-dbapi`--for example:
|
|
|
|
```sh
|
|
cat <<EOF >./docker/requirements-local.txt
|
|
flightsql-dbapi
|
|
EOF
|
|
```
|
|
|
|
The `./docker/requirements-local.txt` file is used to specify additional
|
|
Python packages that Docker should include for Superset.
|
|
For more information about Superset's Docker configuration, see
|
|
[Getting Started with Superset using Docker](https://github.com/apache/superset/tree/master/docker#readme).
|
|
|
|
3. Use the `docker-compose pull` command to fetch dependencies for the Docker
|
|
containers.
|
|
|
|
```sh
|
|
docker-compose -f docker-compose-non-dev.yml pull
|
|
```
|
|
|
|
The process might take several seconds to complete.
|
|
After it completes, you're ready to [Start the Superset Docker containers](#start-the-superset-docker-containers).
|
|
|
|
## Start the Superset Docker containers
|
|
|
|
To start the containers and run Superset, enter the `docker-compose up` command
|
|
and pass the `-f` flag with the setup file name:
|
|
|
|
```sh
|
|
docker-compose -f docker-compose-non-dev.yml up
|
|
```
|
|
|
|
This might take several seconds to complete.
|
|
|
|
If successful, the terminal contains output similar to the following:
|
|
|
|
```sh
|
|
superset_init | Init Step 4/4 [Complete] -- Loading examples
|
|
superset_init |
|
|
superset_init |
|
|
superset_init | ######################################################################
|
|
superset_init |
|
|
superset_init exited with code 0
|
|
superset_app | 127.0.0.1 - - [15/Jan/2025:15:14:11 +0000] "GET /health HTTP/1.1" 200 2 "-" "curl/7.74.0"
|
|
```
|
|
|
|
With Superset running, you're ready to [log in](#log-in-to-superset) and set up
|
|
a database connection.
|
|
|
|
## Log in to Superset
|
|
|
|
1. In a browser, visit [localhost:8088](http://localhost:8088) to log in to the
|
|
Superset user interface (UI). If you configured Superset to use a custom
|
|
domain, navigate to your custom domain.
|
|
|
|
2. If this is your first time logging into Superset, use the following username
|
|
and password:
|
|
|
|
- **Username**: admin
|
|
- **Password**: admin
|
|
|
|
3. Optional: Create a new admin user with a unique password.
|
|
|
|
1. In the Superset UI, click **Settings** and select **List Users**.
|
|
2. Click **{{< icon "plus" >}}**.
|
|
3. Select the **Admin** role and provide the remaining credentials for the
|
|
new user.
|
|
4. Click **Save**.
|
|
5. Delete the default **admin** users.
|
|
|
|
## Create a database connection for InfluxDB
|
|
|
|
1. In the Superset UI, click **Settings** and select **Database Connections**.
|
|
2. Click **+ Database** .
|
|
3. In the **Connect a Database** window, click on the **Supported Databases**
|
|
drop-down menu and select **Other**.
|
|
|
|
{{< img-hd src="/img/influxdb3/cloud-serverless-superset-connect.png" alt="Configure InfluxDB connection in Superset" />}}
|
|
|
|
4. Enter a **Display Name** (for example, _{{< product-name >}}_) for the database connection.
|
|
5. Enter your **SQL Alchemy URI** comprised of the following:
|
|
|
|
- **Protocol**: `datafusion+flightsql`
|
|
- **Domain**: {{< product-name >}} host (default is `localhost`)
|
|
- **Port**: {{< product-name >}} port (default is `8181`)
|
|
|
|
**Query parameters**
|
|
|
|
- **`?database`**: URL-encoded InfluxDB database name
|
|
- **`?token`**: InfluxDB authorization token
|
|
|
|
> [!Note]
|
|
> While in beta, {{< product-name >}} does not require an authorization token.
|
|
|
|
{{< code-callout "<(domain|port|database-name|token)>" >}}
|
|
{{< code-callout "localhost|8181|example-database|example-token" >}}
|
|
```sh
|
|
# Syntax
|
|
datafusion+flightsql://<domain>:<port>?database=<database-name>&token=<token>
|
|
|
|
# Example
|
|
datafusion+flightsql://{{< influxdb/host >}}?database=example-database&token=example-token
|
|
```
|
|
{{< /code-callout >}}
|
|
{{< /code-callout >}}
|
|
|
|
6. Click **Test Connection** to ensure the connection works.
|
|
7. Click **Connect** to save the database connection.
|
|
|
|
## Query InfluxDB with Superset
|
|
|
|
With a connection to {{< product-name >}} established, you can begin to query
|
|
and visualize data.
|
|
|
|
1. In the Superset UI, click **SQL ▾** in the top navigation bar and select **SQL Lab**.
|
|
2. In the left pane:
|
|
|
|
1. Under **Database**, select your {{< product-name >}} connection.
|
|
2. Under **Schema**, select **iox**.
|
|
3. Under **See table schema**, select the table to query.
|
|
|
|
The table schema appears in the left pane:
|
|
|
|
{{< img-hd src="/img/influxdb3/cloud-serverless-superset-schema.png" alt="Select your InfluxDB schema in Superset" />}}
|
|
|
|
3. Use the **query editor** to write an SQL query that queries data in your
|
|
InfluxDB database.
|
|
4. Click **Run** to execute the query.
|
|
|
|
Query results appear below the query editor.
|
|
|
|
## Build visualizations with Superset
|
|
|
|
Use Superset to create visualizations and dashboards for InfluxDB queries.
|
|
For a comprehensive walk-through of creating visualizations with
|
|
Superset, see the [Creating Charts and Dashboards in Superset documentation](https://superset.apache.org/docs/creating-charts-dashboards/creating-your-first-dashboard).
|
|
|
|
{{< img-hd src="/img/influxdb3/cloud-serverless-superset-dashboard.png" alt="Build InfluxDB dashboards in Apache Superset" />}}
|