Skip to content

Commit 6603be3

Browse files
justindeguzmanjustindeguzman
authored
Merge pull request #2374 from ClickHouse/chdb-docs
Add chDB docs
2 parents 0b4bc95 + 07dc5b7 commit 6603be3

File tree

11 files changed

+502
-0
lines changed

11 files changed

+502
-0
lines changed

‎docs/en/chdb/data-formats.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Data Formats
3+
sidebar_label: Data Formats
4+
slug: /en/chdb/data-formats
5+
description: Data Formats for chDB
6+
keywords: [chdb, data formats]
7+
---
8+
9+
chDB is 100% feature compatible with ClickHouse 🚀
10+
11+
Please refer to the [ClickHouse SQL Reference](/docs/en/sql-reference) for further information and examples.
12+
13+
Just like ClickHouse, chDB can accept and return data in various formats.
14+
15+
Input formats are used to parse the data provided to `INSERT` and `SELECT` from a file-backed table such as `File`, `URL` or `S3`.
16+
Output formats are used to arrange the results of a `SELECT`, and to perform `INSERT`s into a file-backed table.
17+
Besides all of the data formats that ClickHouse supported, chDB also supports:
18+
19+
- `ArrowTable` as output format, the type is Python `pyarrow.Table`
20+
- `DataFrame` as input and output format, the type is Python `pandas.DataFrame`. For examples, see [test_joindf.py](https://github.com/chdb-io/chdb/blob/main/tests/test_joindf.py)
21+
- Debug as output (as an alias of `CSV`), but with enabled debug verbose output from ClickHouse.
22+
23+
The supported data formats from ClickHouse are:
24+
25+
| Format | Input | Output |
26+
|---------------------------------|-------|--------|
27+
| TabSeparated | ✔ | ✔ |
28+
| TabSeparatedRaw | ✔ | ✔ |
29+
| TabSeparatedWithNames | ✔ | ✔ |
30+
| TabSeparatedWithNamesAndTypes | ✔ | ✔ |
31+
| TabSeparatedRawWithNames | ✔ | ✔ |
32+
| TabSeparatedRawWithNamesAndTypes| ✔ | ✔ |
33+
| Template | ✔ | ✔ |
34+
| TemplateIgnoreSpaces | ✔ | ✗ |
35+
| CSV | ✔ | ✔ |
36+
| CSVWithNames | ✔ | ✔ |
37+
| CSVWithNamesAndTypes | ✔ | ✔ |
38+
| CustomSeparated | ✔ | ✔ |
39+
| CustomSeparatedWithNames | ✔ | ✔ |
40+
| CustomSeparatedWithNamesAndTypes| ✔ | ✔ |
41+
| SQLInsert | ✗ | ✔ |
42+
| Values | ✔ | ✔ |
43+
| Vertical | ✗ | ✔ |
44+
| JSON | ✔ | ✔ |
45+
| JSONAsString | ✔ | ✗ |
46+
| JSONStrings | ✔ | ✔ |
47+
| JSONColumns | ✔ | ✔ |
48+
| JSONColumnsWithMetadata | ✔ | ✔ |
49+
| JSONCompact | ✔ | ✔ |
50+
| JSONCompactStrings | ✗ | ✔ |
51+
| JSONCompactColumns | ✔ | ✔ |
52+
| JSONEachRow | ✔ | ✔ |
53+
| PrettyJSONEachRow | ✗ | ✔ |
54+
| JSONEachRowWithProgress | ✗ | ✔ |
55+
| JSONStringsEachRow | ✔ | ✔ |
56+
| JSONStringsEachRowWithProgress | ✗ | ✔ |
57+
| JSONCompactEachRow | ✔ | ✔ |
58+
| JSONCompactEachRowWithNames | ✔ | ✔ |
59+
| JSONCompactEachRowWithNamesAndTypes | ✔ | ✔ |
60+
| JSONCompactStringsEachRow | ✔ | ✔ |
61+
| JSONCompactStringsEachRowWithNames | ✔ | ✔ |
62+
| JSONCompactStringsEachRowWithNamesAndTypes | ✔ | ✔ |
63+
| JSONObjectEachRow | ✔ | ✔ |
64+
| BSONEachRow | ✔ | ✔ |
65+
| TSKV | ✔ | ✔ |
66+
| Pretty | ✗ | ✔ |
67+
| PrettyNoEscapes | ✗ | ✔ |
68+
| PrettyMonoBlock | ✗ | ✔ |
69+
| PrettyNoEscapesMonoBlock | ✗ | ✔ |
70+
| PrettyCompact | ✗ | ✔ |
71+
| PrettyCompactNoEscapes | ✗ | ✔ |
72+
| PrettyCompactMonoBlock | ✗ | ✔ |
73+
| PrettyCompactNoEscapesMonoBlock | ✗ | ✔ |
74+
| PrettySpace | ✗ | ✔ |
75+
| PrettySpaceNoEscapes | ✗ | ✔ |
76+
| PrettySpaceMonoBlock | ✗ | ✔ |
77+
| PrettySpaceNoEscapesMonoBlock | ✗ | ✔ |
78+
| Prometheus | ✗ | ✔ |
79+
| Protobuf | ✔ | ✔ |
80+
| ProtobufSingle | ✔ | ✔ |
81+
| Avro | ✔ | ✔ |
82+
| AvroConfluent | ✔ | ✗ |
83+
| Parquet | ✔ | ✔ |
84+
| ParquetMetadata | ✔ | ✗ |
85+
| Arrow | ✔ | ✔ |
86+
| ArrowStream | ✔ | ✔ |
87+
| ORC | ✔ | ✔ |
88+
| One | ✔ | ✗ |
89+
| RowBinary | ✔ | ✔ |
90+
| RowBinaryWithNames | ✔ | ✔ |
91+
| RowBinaryWithNamesAndTypes | ✔ | ✔ |
92+
| RowBinaryWithDefaults | ✔ | ✔ |
93+
| Native | ✔ | ✔ |
94+
| Null | ✗ | ✔ |
95+
| XML | ✗ | ✔ |
96+
| CapnProto | ✔ | ✔ |
97+
| LineAsString | ✔ | ✔ |
98+
| Regexp | ✔ | ✗ |
99+
| RawBLOB | ✔ | ✔ |
100+
| MsgPack | ✔ | ✔ |
101+
| MySQLDump | ✔ | ✗ |
102+
| Markdown | ✗ | ✔ |

‎docs/en/chdb/index.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: chDB
3+
sidebar_label: Overview
4+
slug: /en/chdb
5+
description: chDB is an in-process SQL OLAP Engine powered by ClickHouse
6+
keywords: [chdb, embedded, clickhouse-lite, in-process, in process]
7+
---
8+
9+
# chDB
10+
11+
chDB is an in-process SQL OLAP Engine powered by ClickHouse. It is developed by ClickHouse, Inc and open-source contributors.
12+
13+
## Features
14+
- In-process SQL OLAP Engine, powered by [ClickHouse](https://github.com/clickhouse/clickhouse)
15+
- Serverless. No need to install or run ClickHouse services.
16+
- Minimized data copy from C++ to Python with [python memoryview](https://docs.python.org/3/c-api/memoryview.html)
17+
- Input & Output support Parquet, CSV, JSON, Arrow, ORC and [60+ more formats](https://clickhouse.com/docs/en/interfaces/formats)
18+
- Supports Python DB API 2.0: [example](https://github.com/chdb-io/chdb/blob/main/examples/dbapi.py) and [custom UDF Functions](https://github.com/chdb-io/chdb/blob/main/examples/udf.py)
19+
- Library bindings for [Python](https://github.com/chdb-io/chdb), [Go](https://github.com/chdb-io/chdb-go), [Rust](https://github.com/chdb-io/chdb-rust), [NodeJS](https://github.com/chdb-io/chdb-node), [Bun](https://github.com/chdb-io/chdb-bun)
20+
- Apache License, Version 2.0
21+
22+
## About
23+
- Read the full story about the birth of the chDB project on Auxten's blog
24+
- Read about chDB and its usecases on the [Official ClickHouse Blog](https://auxten.com/the-birth-of-chdb/)
25+
- Discover chDB in your browser using [codapi examples](https://antonz.org/trying-chdb/)
26+
- Listen to a brief project introduction courtesy of our hero Alexey Milovidov, the original creator of ClickHouse:
27+
28+
<div class='vimeo-container'>
29+
<iframe src="//www.youtube.com/embed/cuf_hYn7dqU?start=3053"
30+
width="640"
31+
height="360"
32+
frameborder="0"
33+
allow="autoplay;
34+
fullscreen;
35+
picture-in-picture"
36+
allowfullscreen>
37+
</iframe>
38+
</div>

‎docs/en/chdb/install/bun.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: Installing chDB for Bun
3+
sidebar_label: Bun
4+
slug: /en/chdb/install/bun
5+
description: How to install chDB for Bun
6+
keywords: [chdb, embedded, clickhouse-lite, bun, install]
7+
---
8+
9+
# Installing chDB for Bun
10+
11+
## Requirements
12+
13+
Install [libchdb](https://github.com/chdb-io/chdb):
14+
15+
```bash
16+
curl -sL https://lib.chdb.io | bash
17+
```
18+
19+
## Install
20+
21+
See: [chdb-bun](https://github.com/chdb-io/chdb-bun)
22+
23+
## Usage
24+
25+
### Query(query, *format) (ephemeral)
26+
27+
```javascript
28+
import { query } from 'chdb-bun';
29+
30+
// Query (ephemeral)
31+
var result = query("SELECT version()", "CSV");
32+
console.log(result); // 23.10.1.1
33+
```
34+
35+
### Session.Query(query, *format)
36+
37+
```javascript
38+
import { Session } from 'chdb-bun';
39+
const sess = new Session('./chdb-bun-tmp');
40+
41+
// Query Session (persistent)
42+
sess.query("CREATE FUNCTION IF NOT EXISTS hello AS () -> 'Hello chDB'", "CSV");
43+
var result = sess.query("SELECT hello()", "CSV");
44+
console.log(result);
45+
46+
// Before cleanup, you can find the database files in `./chdb-bun-tmp`
47+
48+
sess.cleanup(); // cleanup session, this will delete the database
49+
```
50+

‎docs/en/chdb/install/c.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Installing chDB for C and C++
3+
sidebar_label: C and C++
4+
slug: /en/chdb/install/c
5+
description: How to install chDB for C and C++
6+
keywords: [chdb, embedded, clickhouse-lite, install]
7+
---
8+
9+
# Installing chDB for C and C++
10+
11+
## Requirements
12+
13+
Install [libchdb](https://github.com/chdb-io/chdb):
14+
15+
```bash
16+
curl -sL https://lib.chdb.io | bash
17+
```
18+
19+
## Usage
20+
21+
Follow the instructions for [libchdb](https://github.com/chdb-io/chdb/blob/main/bindings.md) to get started.
22+
23+
`chdb.h`
24+
25+
```c
26+
#pragma once
27+
#include <cstdint>
28+
#include <stddef.h>
29+
30+
extern "C" {
31+
struct local_result
32+
{
33+
char * buf;
34+
size_t len;
35+
void * _vec; // std::vector<char> *, for freeing
36+
double elapsed;
37+
uint64_t rows_read;
38+
uint64_t bytes_read;
39+
};
40+
41+
local_result * query_stable(int argc, char ** argv);
42+
void free_result(local_result * result);
43+
}
44+
```

‎docs/en/chdb/install/go.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: Installing chDB for Go
3+
sidebar_label: Go
4+
slug: /en/chdb/install/go
5+
description: How to install chDB for Go
6+
keywords: [chdb, embedded, clickhouse-lite, go, install]
7+
---
8+
9+
# Installing chDB for Go
10+
11+
## Requirements
12+
13+
Install [libchdb](https://github.com/chdb-io/chdb):
14+
15+
```bash
16+
curl -sL https://lib.chdb.io | bash
17+
```
18+
19+
## Install
20+
21+
See: [chdb-go](https://github.com/chdb-io/chdb-go)
22+
23+
## Usage
24+
25+
- API Documentation: [High Level API](https://github.com/chdb-io/chdb-go/blob/main/chdb.md)
26+
- Low Level API Documentation: [Low Level API](https://github.com/chdb-io/chdb-go/blob/main/lowApi.md)

‎docs/en/chdb/install/nodejs.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: Installing chDB for NodeJS
3+
sidebar_label: NodeJS
4+
slug: /en/chdb/install/nodejs
5+
description: How to install chDB for NodeJS
6+
keywords: [chdb, embedded, clickhouse-lite, nodejs, install]
7+
---
8+
9+
# Installing chDB for NodeJS
10+
11+
## Requirements
12+
13+
Install [libchdb](https://github.com/chdb-io/chdb):
14+
15+
```bash
16+
curl -sL https://lib.chdb.io | bash
17+
```
18+
19+
## Install
20+
21+
```bash
22+
npm i chdb
23+
```
24+
25+
## Usage
26+
27+
You can leverage the power of chdb in your NodeJS applications by importing and using the chdb-node module:
28+
29+
```javascript
30+
const { query, Session } = require("chdb");
31+
32+
var ret;
33+
34+
// Test standalone query
35+
ret = query("SELECT version(), 'Hello chDB', chdb()", "CSV");
36+
console.log("Standalone Query Result:", ret);
37+
38+
// Test session query
39+
// Create a new session instance
40+
const session = new Session("./chdb-node-tmp");
41+
ret = session.query("SELECT 123", "CSV")
42+
console.log("Session Query Result:", ret);
43+
ret = session.query("CREATE DATABASE IF NOT EXISTS testdb;" +
44+
"CREATE TABLE IF NOT EXISTS testdb.testtable (id UInt32) ENGINE = MergeTree() ORDER BY id;");
45+
46+
session.query("USE testdb; INSERT INTO testtable VALUES (1), (2), (3);")
47+
48+
ret = session.query("SELECT * FROM testtable;")
49+
console.log("Session Query Result:", ret);
50+
51+
// Clean up the session
52+
session.cleanup();
53+
```
54+
55+
## Build from source
56+
57+
```bash
58+
npm run libchdb
59+
npm install
60+
npm run test
61+
```
62+

‎docs/en/chdb/install/python.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: Installing chDB for Python
3+
sidebar_label: Python
4+
slug: /en/chdb/install/python
5+
description: How to install chDB for Python
6+
keywords: [chdb, embedded, clickhouse-lite, python, install]
7+
---
8+
9+
# Installing chDB for Python
10+
11+
## Requirements
12+
13+
Python 3.8+ on macOS and Linux (x86_64 and ARM64)
14+
15+
## Install
16+
17+
```bash
18+
pip install chdb
19+
```
20+
21+
## Usage
22+
23+
CLI example:
24+
25+
```python
26+
python3 -m chdb [SQL] [OutputFormat]
27+
```
28+
29+
```python
30+
python3 -m chdb "SELECT 1, 'abc'" Pretty
31+
```
32+
33+
Python file example:
34+
35+
```python
36+
import chdb
37+
38+
res = chdb.query("SELECT 1, 'abc'", "CSV")
39+
print(res, end="")
40+
```
41+
42+
<!-- <codapi-snippet sandbox="python" editor="basic" init-delay="500">
43+
</codapi-snippet> -->
44+
45+
<!-- <br /><br /> -->
46+
47+
Queries can return data using any [supported format](/docs/en/interfaces/formats) as well as `Dataframe` and `Debug`.

‎docs/en/chdb/install/rust.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Installing chDB for Rust
3+
sidebar_label: Rust
4+
slug: /en/chdb/install/rust
5+
description: How to install chDB for Rust
6+
keywords: [chdb, embedded, clickhouse-lite, bun, install]
7+
---
8+
9+
## Requirements
10+
11+
Install [libchdb](https://github.com/chdb-io/chdb):
12+
13+
```bash
14+
curl -sL https://lib.chdb.io | bash
15+
```
16+
17+
## Usage
18+
19+
This binding is a work in progress. Follow the instructions at [chdb-rust](https://github.com/chdb-io/chdb-rust) to get started.

0 commit comments

Comments
 (0)