diff --git a/docs/integrations/index.mdx b/docs/integrations/index.mdx index dc2c1a2ebcf..372f4460691 100644 --- a/docs/integrations/index.mdx +++ b/docs/integrations/index.mdx @@ -175,6 +175,7 @@ import Hashboardsvg from '@site/static/images/integrations/logos/hashboard.svg'; import luzmo_logo from '@site/static/images/integrations/logos/luzmo.png'; import vs_logo from '@site/static/images/integrations/logos/logo_vs.png'; import chartbrew_logo from '@site/static/images/integrations/logos/logo_chartbrew.png'; +import marimo_logo from '@site/static/images/integrations/logos/logo_marimo.png'; import Image from '@theme/IdealImage'; ClickHouse integrations are organized by their support level: @@ -384,4 +385,5 @@ We are actively compiling this list of ClickHouse integrations below, so it's no |TricksterCache||Data visualization| Open Source HTTP Reverse Proxy Cache and Time Series Dashboard Accelerator |[Website](https://trickstercache.org/)| |Visual Studio Client|VS logo|Language client|Visual studio lightweight client|[Marketplace](https://marketplace.visualstudio.com/items?itemName=fanruten.clickhouse-light)| |VulcanSQL|VulcanSQL logo|Data API Framework|It's a Data API Framework for data applications that helps data folks create and share data APIs faster. It turns your SQL templates into data APIs. No backend skills required.|[Website](https://vulcansql.com/),
[Documentation](https://vulcansql.com/docs/connect/clickhouse)| +|marimo|marimo logo|SQL Client|An open-source reactive notebook for Python with SQL built-in. Create data visualizations, shareable apps or executable scripts.|[Website](https://marimo.io/),
[Documentation](https://docs.marimo.io/guides/working_with_data/sql/?h=sql#clickhouse-support)| diff --git a/docs/integrations/sql-clients/index.md b/docs/integrations/sql-clients/index.md index 03928b943ca..7a6d95d1401 100644 --- a/docs/integrations/sql-clients/index.md +++ b/docs/integrations/sql-clients/index.md @@ -1,7 +1,7 @@ --- slug: /integrations/sql-clients/ description: 'Overview page for ClickHouse SQL clients.' -keywords: ['integrations', 'DataGrip', 'DBeaver', 'DbVisualizer', 'Jupyter Notebooks', 'QStudio', 'TABLUM.IO'] +keywords: ['integrations', 'DataGrip', 'DBeaver', 'DbVisualizer', 'Jupyter Notebooks', 'QStudio', 'TABLUM.IO', 'marimo'] title: 'SQL Client Integrations' --- @@ -11,10 +11,10 @@ This section describes how to integrate ClickHouse with various common database | Tool | Description | |-----------------------------------------------------|-------------------------------------------------------------| -| [DataGrip](/integrations/datagrip) | Powerful database IDE | -| [DBeaver](/integrations/dbeaver) | Database administration and development tool | -| [DbVisualizer](/integrations/dbvisualizer) | Database management tool for developers, DBAs, and analysts | -| [Jupyter Notebooks](/integrations/jupysql) | Interactive notebooks for code, visualizations, and text | -| [QStudio](/integrations/qstudio) | Free, open-source SQL GUI client | -| [TABLUM.IO](/integrations/tablumio) | Cloud-based data visualization platform | - +| [DataGrip](/integrations/datagrip) | Powerful database IDE | +| [DBeaver](/integrations/dbeaver) | Database administration and development tool | +| [DbVisualizer](/integrations/dbvisualizer) | Database management tool for developers, DBAs, and analysts | +| [Jupyter Notebooks](/integrations/jupysql) | Interactive notebooks for code, visualizations, and text | +| [QStudio](/integrations/qstudio) | Free, open-source SQL GUI client | +| [TABLUM.IO](/integrations/tablumio) | Cloud-based data visualization platform | +| [marimo](/integrations/marimo) | Open-source reactive notebook for Python with SQL built-in | diff --git a/docs/integrations/sql-clients/marimo.md b/docs/integrations/sql-clients/marimo.md new file mode 100644 index 00000000000..cff3817d3a8 --- /dev/null +++ b/docs/integrations/sql-clients/marimo.md @@ -0,0 +1,121 @@ +--- +slug: /integrations/marimo +sidebar_label: 'marimo' +description: 'marimo is a next-generation Python notebook for interacting with data' +title: 'Using marimo with ClickHouse' +--- + +import Image from '@theme/IdealImage'; +import marimo_connect from '@site/static/images/integrations/sql-clients/marimo/clickhouse-connect.gif'; +import add_db_panel from '@site/static/images/integrations/sql-clients/marimo/panel-arrow.png'; +import add_db_details from '@site/static/images/integrations/sql-clients/marimo/add-db-details.png'; +import run_cell from '@site/static/images/integrations/sql-clients/marimo/run-cell.png'; +import choose_sql_engine from '@site/static/images/integrations/sql-clients/marimo/choose-sql-engine.png'; +import results from '@site/static/images/integrations/sql-clients/marimo/results.png'; +import dropdown_cell_chart from '@site/static/images/integrations/sql-clients/marimo/dropdown-cell-chart.png'; +import run_app_view from '@site/static/images/integrations/sql-clients/marimo/run-app-view.png'; +import CommunityMaintainedBadge from '@theme/badges/CommunityMaintained'; + +# Using marimo with ClickHouse + + + +[marimo](https://marimo.io/) is an open-source reactive notebook for Python with SQL built-in. When you run a cell or interact with a UI element, marimo automatically runs affected cells (or marks them as stale), keeping code and outputs consistent and preventing bugs before they happen. Every marimo notebook is stored as pure Python, executable as a script, and deployable as an app. + +Connect to ClickHouse + +## 1. Install marimo with SQL support {#install-marimo-sql} + +```shell +pip install "marimo[sql]" clickhouse_connect +marimo edit clickhouse_demo.py +``` +This should open up a web browser running on localhost. + +## 2. Connecting to ClickHouse. {#connect-to-clickhouse} + +Navigate to the datasources panel on the left side of the marimo editor and click on 'Add database'. + +Add a new database + +You will be prompted to fill in the database details. + +Fill in the database details + +You will then have a cell that can be run to establish a connection. + +Run the cell to connect to ClickHouse + +## 3. Run SQL {#run-sql} + +Once you have set up a connection, you can create a new SQL cell and choose the clickhouse engine. + +Choose SQL engine + +For this guide, we will use the New York Taxi dataset. + +```sql +CREATE TABLE trips ( + trip_id UInt32, + pickup_datetime DateTime, + dropoff_datetime DateTime, + pickup_longitude Nullable(Float64), + pickup_latitude Nullable(Float64), + dropoff_longitude Nullable(Float64), + dropoff_latitude Nullable(Float64), + passenger_count UInt8, + trip_distance Float32, + fare_amount Float32, + extra Float32, + tip_amount Float32, + tolls_amount Float32, + total_amount Float32, + payment_type Enum('CSH' = 1, 'CRE' = 2, 'NOC' = 3, 'DIS' = 4, 'UNK' = 5), + pickup_ntaname LowCardinality(String), + dropoff_ntaname LowCardinality(String) +) +ENGINE = MergeTree +PRIMARY KEY (pickup_datetime, dropoff_datetime); +``` + +```sql +INSERT INTO trips +SELECT + trip_id, + pickup_datetime, + dropoff_datetime, + pickup_longitude, + pickup_latitude, + dropoff_longitude, + dropoff_latitude, + passenger_count, + trip_distance, + fare_amount, + extra, + tip_amount, + tolls_amount, + total_amount, + payment_type, + pickup_ntaname, + dropoff_ntaname +FROM gcs( + 'https://storage.googleapis.com/clickhouse-public-datasets/nyc-taxi/trips_0.gz', + 'TabSeparatedWithNames' +); +``` + +```sql +SELECT * FROM trips LIMIT 1000; +``` + +Results in a dataframe + +Now, you are able to view the results in a dataframe. I would like to visualize the most expensive drop-offs from a given pickup location. marimo provides several UI components to help you. I will use a dropdown to select the location and altair for charting. + +Combination of dropdown, table and chart + +marimo's reactive execution model extends into SQL queries, so changes to your SQL will automatically trigger downstream computations for dependent cells (or optionally mark cells as stale for expensive computations). Hence the chart and table changes when the query is updated. + +You can also toggle App View to have a clean interface for exploring your data. + +Run app view diff --git a/scripts/aspell-ignore/en/aspell-dict.txt b/scripts/aspell-ignore/en/aspell-dict.txt index 1914607f201..a8988c8bbd1 100644 --- a/scripts/aspell-ignore/en/aspell-dict.txt +++ b/scripts/aspell-ignore/en/aspell-dict.txt @@ -1371,6 +1371,7 @@ aiochclient alloc allocator alphaTokens +altair amplab analysisOfVariance analytics @@ -1765,12 +1766,14 @@ dashboarding datacenter datacenters datafiles +dataframe datagrip datalens datanode dataset datasets datasource +datasources datatypes dateName dateTime @@ -2372,6 +2375,8 @@ mappedfile marginBottom marginLeft mariadb +marimo +marimo's matcher materializations materializedview diff --git a/sidebars.js b/sidebars.js index fa01620e8fb..153e3666ec7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -960,6 +960,7 @@ const sidebars = { "integrations/sql-clients/jupysql", "integrations/sql-clients/qstudio", "integrations/sql-clients/tablum", + "integrations/sql-clients/marimo", ], }, { diff --git a/static/images/integrations/logos/logo_marimo.png b/static/images/integrations/logos/logo_marimo.png new file mode 100644 index 00000000000..4781a428509 Binary files /dev/null and b/static/images/integrations/logos/logo_marimo.png differ diff --git a/static/images/integrations/sql-clients/marimo/add-db-details.png b/static/images/integrations/sql-clients/marimo/add-db-details.png new file mode 100644 index 00000000000..198547389e9 Binary files /dev/null and b/static/images/integrations/sql-clients/marimo/add-db-details.png differ diff --git a/static/images/integrations/sql-clients/marimo/choose-sql-engine.png b/static/images/integrations/sql-clients/marimo/choose-sql-engine.png new file mode 100644 index 00000000000..7de4cbc1293 Binary files /dev/null and b/static/images/integrations/sql-clients/marimo/choose-sql-engine.png differ diff --git a/static/images/integrations/sql-clients/marimo/clickhouse-connect.gif b/static/images/integrations/sql-clients/marimo/clickhouse-connect.gif new file mode 100644 index 00000000000..d3a8e9d9b70 Binary files /dev/null and b/static/images/integrations/sql-clients/marimo/clickhouse-connect.gif differ diff --git a/static/images/integrations/sql-clients/marimo/dropdown-cell-chart.png b/static/images/integrations/sql-clients/marimo/dropdown-cell-chart.png new file mode 100644 index 00000000000..a717e0a3286 Binary files /dev/null and b/static/images/integrations/sql-clients/marimo/dropdown-cell-chart.png differ diff --git a/static/images/integrations/sql-clients/marimo/panel-arrow.png b/static/images/integrations/sql-clients/marimo/panel-arrow.png new file mode 100644 index 00000000000..84b84fcb8f5 Binary files /dev/null and b/static/images/integrations/sql-clients/marimo/panel-arrow.png differ diff --git a/static/images/integrations/sql-clients/marimo/results.png b/static/images/integrations/sql-clients/marimo/results.png new file mode 100644 index 00000000000..1b5bdc54e67 Binary files /dev/null and b/static/images/integrations/sql-clients/marimo/results.png differ diff --git a/static/images/integrations/sql-clients/marimo/run-app-view.png b/static/images/integrations/sql-clients/marimo/run-app-view.png new file mode 100644 index 00000000000..faf4962fb9f Binary files /dev/null and b/static/images/integrations/sql-clients/marimo/run-app-view.png differ diff --git a/static/images/integrations/sql-clients/marimo/run-cell.png b/static/images/integrations/sql-clients/marimo/run-cell.png new file mode 100644 index 00000000000..cf0caeb47f2 Binary files /dev/null and b/static/images/integrations/sql-clients/marimo/run-cell.png differ