diff --git a/docs/en/chdb/guides/clickhouse-local.md b/docs/en/chdb/guides/clickhouse-local.md new file mode 100644 index 00000000000..058e8ae10cf --- /dev/null +++ b/docs/en/chdb/guides/clickhouse-local.md @@ -0,0 +1,132 @@ +--- +title: Using a clickhouse-local database +sidebar_label: Use clickhouse-local database +slug: /en/chdb/guides/clickhouse-local +description: Learn how to use a clickhouse-local database with chDB +keywords: [chdb, clickhouse-local] +--- + +[clickhouse-local](/en/operations/utilities/clickhouse-local) is a CLI with an embedded version of ClickHouse. +It gives users the power of ClickHouse without having to install a server. +In this guide, we will learn how to use a clickhouse-local database from chDB. + +## Setup + +Let's first create a virtual environment: + +```bash +python -m venv .venv +source .venv/bin/activate +``` + +And now we'll install chDB. +Make sure you have version 2.0.2 or higher: + +```bash +pip install "chdb>=2.0.2" +``` + +And now we're going to install [ipython](https://ipython.org/): + +```bash +pip install ipython +``` + +We're going to use `ipython` to run the commands in the rest of the guide, which you can launch by running: + +```bash +ipython +``` + +## Installing clickhouse-local + +Downloading and installing clickhouse-local is the same as [downloading and installing ClickHouse](https://clickhouse.com/docs/en/install). +We can do this by running the following command: + +```bash +curl https://clickhouse.com/ | sh +``` + +To launch clickhouse-local with the data being persisted to a directory, we need to pass in a `--path`: + +```bash +./clickhouse -m --path demo.chdb +``` + +## Ingesting data into clickhouse-local + +The default database only stores data in memory, so we'll need to create a named database to make sure any data we ingest is persisted to disk. + +```sql +CREATE DATABASE foo; +``` + +Let's create a table and insert some random numbers: + +```sql +CREATE TABLE foo.randomNumbers +ORDER BY number AS +SELECT rand() AS number +FROM numbers(10_000_000); +``` + +Let's write a query to see what data we've got: + +```sql +SELECT quantilesExact(0, 0.5, 0.75, 0.99)(number) AS quants +FROM foo.randomNumbers + +┌─quants────────────────────────────────┐ +│ [69,2147776478,3221525118,4252096960] │ +└───────────────────────────────────────┘ +``` + +Once you've done that, make sure you `exit;` from the CLI as only one process can hold a lock on this directory. +If we don't do that, we'll get the following error when we try to connect to the database from chDB: + +```text +ChdbError: Code: 76. DB::Exception: Cannot lock file demo.chdb/status. Another server instance in same directory is already running. (CANNOT_OPEN_FILE) +``` + +## Connecting to a clickhouse-local database + +Go back to the `ipython` shell and import the `session` module from chDB: + +```python +from chdb import session as chs +``` + +Initialize a session pointing to `demo..chdb`: + +``` +sess = chs.Session("demo.chdb") +``` + +We can then run the same query that returns the quantiles of numbers: + +```python +sess.query(""" +SELECT quantilesExact(0, 0.5, 0.75, 0.99)(number) AS quants +FROM foo.randomNumbers +""", "Vertical") + +Row 1: +────── +quants: [0,9976599,2147776478,4209286886] +``` + +We can also insert data into this database from chDB: + + +```python +sess.query(""" +INSERT INTO foo.randomNumbers +SELECT rand() AS number FROM numbers(10_000_000) +""") + +Row 1: +────── +quants: [0,9976599,2147776478,4209286886] +``` + +We can then re-run the quantiles query from chDB or clickhouse-local. diff --git a/sidebars.js b/sidebars.js index b8565a58f87..6fb824beb3d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -329,7 +329,6 @@ const sidebars = { "en/interfaces/mysql", "en/interfaces/odbc", "en/interfaces/postgresql", - "en/interfaces/prometheus", "en/interfaces/schema-inference", "en/interfaces/grpc", { @@ -1260,7 +1259,8 @@ const sidebars = { collapsible: false, items: [ "en/chdb/guides/jupysql", - "en/chdb/guides/querying-pandas" + "en/chdb/guides/querying-pandas", + "en/chdb/guides/clickhouse-local" ], }, {