HTTP Interface

### Examples[​](#examples "Direct link to Examples")

To create a table:

```
$ echo 'CREATE TABLE t (a UInt8) ENGINE = Memory' | curl 'http://localhost:8123/' --data-binary @-
```

To use the familiar `INSERT` query for data insertion:

```
$ echo 'INSERT INTO t VALUES (1),(2),(3)' | curl 'http://localhost:8123/' --data-binary @-
```

To send data separately from the query:

```
$ echo '(4),(5),(6)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20VALUES' --data-binary @-
```

Any data format can be specified. For example, the 'Values' format, the same format as the one used when writing `INSERT INTO t VALUES`, can be specified:

```
$ echo '(7),(8),(9)' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20FORMAT%20Values' --data-binary @-
```

To insert data from a tab-separated dump, specify the corresponding format:

```
$ echo -ne '10\n11\n12\n' | curl 'http://localhost:8123/?query=INSERT%20INTO%20t%20FORMAT%20TabSeparated' --data-binary @-
```

To read the table contents:

```
$ curl 'http://localhost:8123/?query=SELECT%20a%20FROM%20t'
7
8
9
10
11
12
1
2
3
4
5
6
```

Note

Data is output in a random order due to parallel query processing

To delete the table:

```
$ echo 'DROP TABLE t' | curl 'http://localhost:8123/' --data-binary @-
```

For successful requests that don't return a data table, an empty response body is returned.

## Compression[​](#compression "Direct link to Compression")

Compression can be used to reduce network traffic when transmitting a large amount of data, or for creating dumps that are immediately compressed.

You can use the internal ClickHouse compression format when transmitting data. The compressed data has a non-standard format, and you need the `clickhouse-compressor` program to work with it. It is installed by default with the `clickhouse-client` package.

To increase the efficiency of data insertion, disable server-side checksum verification by using the [`http_native_compression_disable_checksumming_on_decompress`](/docs/operations/settings/settings#http_native_compression_disable_checksumming_on_decompress) setting.

If you specify `compress=1` in the URL, the server will compress the data it sends to you. If you specify `decompress=1` in the URL, the server will decompress the data which you pass in the `POST` method.

You can also choose to use [HTTP compression](https://en.wikipedia.org/wiki/HTTP_compression). ClickHouse supports the following [compression methods](https://en.wikipedia.org/wiki/HTTP_compression#Content-Encoding_tokens):

- `gzip`
- `br`
- `deflate`
- `xz`
- `zstd`
- `lz4`
- `bz2`
- `snappy`

To send a compressed `POST` request, append the request header `Content-Encoding: compression_method`.

In order for ClickHouse to compress the response, append the `Accept-Encoding: compression_method` header to the request.

You can configure the data compression level using the [`http_zlib_compression_level`](/docs/operations/settings/settings#http_zlib_compression_level) setting for all compression methods.

References

Some HTTP clients might decompress data from the server by default (with `gzip` and `deflate`) and you might get decompressed data even if you use the compression settings correctly.

## Examples[​](#examples-compression "Direct link to Examples")

To send compressed data to the server:

```
echo "SELECT 1" | gzip -c | \
curl -sS --data-binary @- -H 'Content-Encoding: gzip' 'http://localhost:8123/'
```

To receive the compressed data archive from the server:

```
curl -vsS "http://localhost:8123/?enable_http_compression=1" \
-H 'Accept-Encoding: gzip' --output result.gz -d 'SELECT number FROM system.numbers LIMIT 3'

zcat result.gz
0
1
2
```

To receive compressed data from the server, using gunzip to receive decompressed data:

```
curl -sS "http://localhost:8123/?enable_http_compression=1" \
-H 'Accept-Encoding: gzip' -d 'SELECT number FROM system.numbers LIMIT 3' | gunzip -
0
1
2
```

## Default database[​](#default-database "Direct link to Default database")

You can use the `database` URL parameter or the `X-ClickHouse-Database` header to specify the default database.

```
echo 'SELECT number FROM numbers LIMIT 10' | curl 'http://localhost:8123/?database=system' --data-binary @-
0
1
2
3
4
5
6
7
8
9
```

By default, the database that is registered in the server settings is used as the default database. Out of the box, this is the database called `default`. Alternatively, you can always specify the database using a dot before the table name.

## Authentication[​](#authentication "Direct link to Authentication")

The username and password can be indicated in one of three ways:

1. Using HTTP Basic Authentication.

For example:

```
echo 'SELECT 1' | curl 'http://user:password@localhost:8123/' -d @-
```

2. In the `user` and `password` URL parameters

Note

We don't recommend using this method as the parameter might be logged by web proxy and cached in the browser

For example:

```
echo 'SELECT 1' | curl 'http://localhost:8123/?user=user&password=password' -d @-
```

3. Using the 'X-ClickHouse-User' and 'X-ClickHouse-Key' headers

For example:

```
echo 'SELECT 1' | curl -H 'X-ClickHouse-User: user' -H 'X-ClickHouse-Key: password' 'http://localhost:8123/' -d @-
```

If the user name isn't specified, then the `default` name is used. If the password isn't specified, then an empty password is used.
You can also use the URL parameters to specify any settings for processing a single query or entire profiles of settings.

For example:

```
http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1
```

```
$ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:8123/?' --data-binary @-
0
1
2
3
4
5
6
7
8
9
```

For more information see:

- [Settings](/docs/operations/settings/settings)
- [SET](/docs/sql-reference/statements/set)

## Using ClickHouse sessions in the HTTP protocol[​](#using-clickhouse-sessions-in-the-http-protocol "Direct link to Using ClickHouse sessions in the HTTP protocol")

You can also use ClickHouse sessions in the HTTP protocol. To do this, you need to add the `session_id` `GET` parameter to the request. You can use any string as the session ID.

By default, the session is terminated after 60 seconds of inactivity. To change this timeout (in seconds), modify the `default_session_timeout` setting in the server configuration, or add the `session_timeout` `GET` parameter to the request.

To check the session status, use the `session_check=1` parameter. Only one query at a time can be executed within a single session.

You can receive information about the progress of a query in the `X-ClickHouse-Progress` response headers. To do this, enable [`send_progress_in_http_headers`](/docs/operations/settings/settings#send_progress_in_http_headers).

Below is an example of the header sequence:

```
X-ClickHouse-Progress: {"read_rows":"261636","read_bytes":"2093088","total_rows_to_read":"1000000","elapsed_ns":"14050417","memory_usage":"22205975"}
X-ClickHouse-Progress: {"read_rows":"654090","read_bytes":"5232720","total_rows_to_read":"1000000","elapsed_ns":"27948667","memory_usage":"83400279"}
X-ClickHouse-Progress: {"read_rows":"1000000","read_bytes":"8000000","total_rows_to_read":"1000000","elapsed_ns":"38002417","memory_usage":"80715679"}
```

The possible header fields are: