You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+55-46Lines changed: 55 additions & 46 deletions
Original file line number
Diff line number
Diff line change
@@ -7,51 +7,54 @@ Minimal HTTP [ClickHouse](https://clickhouse.com) client for Elixir.
7
7
8
8
Used in [Ecto ClickHouse adapter.](https://github.com/plausible/ecto_ch)
9
9
10
-
### Key features
11
-
12
-
- RowBinary
13
-
- Native query parameters
14
-
- Per query settings
15
-
- Minimal API
16
-
17
-
Your ideas are welcome [here.](https://github.com/plausible/ch/issues/82)
18
-
19
10
## Installation
20
11
21
12
```elixir
22
13
defpdepsdo
23
14
[
24
-
{:ch, "~> 0.3.0"}
15
+
{:ch, "~> 0.4.0"}
25
16
]
26
17
end
27
18
```
28
19
29
20
## Usage
30
21
22
+
#### Start ClickHouse
23
+
24
+
```sh
25
+
# don't forget to stop the container once done
26
+
docker run --rm -p 8123:8123 -e CLICKHOUSE_PASSWORD=secret --ulimit nofile=262144:262144 clickhouse/clickhouse-server:latest-alpine
27
+
```
28
+
31
29
#### Start [DBConnection](https://github.com/elixir-ecto/db_connection) pool
32
30
33
31
```elixir
34
32
defaults = [
35
33
scheme:"http",
36
34
hostname:"localhost",
37
35
port:8123,
38
-
database:"default",
36
+
database:"default",
39
37
settings: [],
40
38
pool_size:1,
41
39
timeout::timer.seconds(15)
42
40
]
43
41
44
-
# note that starting in ClickHouse 25.1.3.23 `default` user doesn't have
45
-
# network access by default in the official Docker images
46
-
# see https://github.com/ClickHouse/ClickHouse/pull/75259
47
-
{:ok, pid} =Ch.start_link(defaults)
42
+
custom = [
43
+
# note that starting in ClickHouse 25.1.3.23 `default` user doesn't have
44
+
# network access by default in the official Docker images
45
+
# see https://github.com/ClickHouse/ClickHouse/pull/75259
46
+
username:"default",
47
+
# this password was provided via `CLICKHOUSE_PASSWORD` to the container above
48
+
password:"secret",
49
+
]
50
+
51
+
config =Keyword.merge(defaults, custom)
52
+
{:ok, pid} =Ch.start_link(config)
48
53
```
49
54
50
55
#### Select rows
51
56
52
57
```elixir
53
-
{:ok, pid} =Ch.start_link()
54
-
55
58
{:ok, %Ch.Result{rows: [[0], [1], [2]]}} =
56
59
Ch.query(pid, "SELECT * FROM system.numbers LIMIT 3")
57
60
@@ -70,70 +73,76 @@ Note on datetime encoding in query parameters:
70
73
#### Insert rows
71
74
72
75
```elixir
73
-
{:ok, pid} =Ch.start_link()
74
-
75
76
Ch.query!(pid, "CREATE TABLE IF NOT EXISTS ch_demo(id UInt64) ENGINE Null")
76
77
77
78
%Ch.Result{num_rows:2} =
78
79
Ch.query!(pid, "INSERT INTO ch_demo(id) VALUES (0), (1)")
79
80
80
-
%Ch.Result{num_rows:2} =
81
-
Ch.query!(pid, "INSERT INTO ch_demo(id) VALUES ({$0:UInt8}), ({$1:UInt32})", [0, 1])
82
-
83
81
%Ch.Result{num_rows:2} =
84
82
Ch.query!(pid, "INSERT INTO ch_demo(id) VALUES ({a:UInt16}), ({b:UInt64})", %{"a"=>0, "b"=>1})
85
83
86
84
%Ch.Result{num_rows:2} =
87
85
Ch.query!(pid, "INSERT INTO ch_demo(id) SELECT number FROM system.numbers LIMIT {limit:UInt8}", %{"limit"=>2})
88
86
```
89
87
90
-
#### Insert rows as [RowBinary](https://clickhouse.com/docs/en/interfaces/formats#rowbinary) (efficient)
88
+
#### Insert rows as [RowBinary](https://clickhouse.com/docs/en/interfaces/formats/RowBinary) (efficient)
91
89
92
90
```elixir
93
-
{:ok, pid} =Ch.start_link()
91
+
Ch.query!(pid, "CREATE TABLE IF NOT EXISTS ch_demo(id UInt64, name String) ENGINE Null")
94
92
95
-
Ch.query!(pid, "CREATE TABLE IF NOT EXISTS ch_demo(id UInt64) ENGINE Null")
93
+
rows = [
94
+
[0, "zero"],
95
+
[1, "one"],
96
+
[2, "two"]
97
+
]
96
98
97
-
types = ["UInt64"]
98
-
# or
99
-
types = [Ch.Types.u64()]
100
-
# or
101
-
types = [:u64]
99
+
types = ["UInt64", "String"]
100
+
# or types = [:u64, :string]
101
+
# or types = [Ch.Types.u64(), Ch.Types.string()]
102
102
103
-
%Ch.Result{num_rows:2} =
104
-
Ch.query!(pid, "INSERT INTO ch_demo(id) FORMAT RowBinary", [[0], [1]], types: types)
105
-
```
103
+
sql = [
104
+
# note the \n -- ClickHouse uses it to separate SQL from the data
105
+
"INSERT INTO ch_demo(id, name) FORMAT RowBinary\n"|Ch.RowBinary.encode_rows(rows, types)
106
+
]
106
107
107
-
Note that RowBinary format encoding requires `:types` option to be provided.
108
+
%Ch.Result{num_rows:2} =Ch.query!(pid, sql)
109
+
```
108
110
109
-
Similarly, you can use [`RowBinaryWithNamesAndTypes`](https://clickhouse.com/docs/en/interfaces/formats#rowbinarywithnamesandtypes) which would additionally do something like a type check.
111
+
Similarly, you can use [`RowBinaryWithNamesAndTypes`](https://clickhouse.com/docs/en/interfaces/formats/RowBinaryWithNamesAndTypes) which would additionally do something like a type check.
110
112
111
113
```elixir
112
-
sql ="INSERT INTO ch_demo FORMAT RowBinaryWithNamesAndTypes"
113
-
opts = [names: ["id"], types: ["UInt64"]]
114
-
rows = [[0], [1]]
114
+
names = ["id", "name"]
115
+
types = ["UInt64", "String"]
116
+
117
+
rows = [
118
+
[0, "zero"],
119
+
[1, "one"],
120
+
[2, "two"]
121
+
]
122
+
123
+
sql = [
124
+
"INSERT INTO ch_demo FORMAT RowBinaryWithNamesAndTypes\n",
Ch.query!(pid, "SELECT b FROM ch_nulls ORDER BY b")
209
216
```
210
217
218
+
Or [`RowBinaryWithDefaults`](https://clickhouse.com/docs/en/interfaces/formats/RowBinaryWithDefaults). TODO.
219
+
211
220
#### UTF-8 in RowBinary
212
221
213
222
When decoding [`String`](https://clickhouse.com/docs/en/sql-reference/data-types/string) columns non UTF-8 characters are replaced with `�` (U+FFFD). This behaviour is similar to [`toValidUTF8`](https://clickhouse.com/docs/en/sql-reference/functions/string-functions#tovalidutf8) and [JSON format.](https://clickhouse.com/docs/en/interfaces/formats#json)
0 commit comments