Contents

1 Как развернуть быстро Clickhouse с помощью Docker
2 Подключаемся к Clickhouse с помощью DBeaver
3 Интерфейсы для доступа к Clickhouse
4 Как создать database в Clickhouse, таблицу и вставить тестовые данные
5 Как подключиться к Clickhouse с помощью Python
6 Как создать таблицу в Clickhouse и записать данные с помощью Python
7 Как получить данные из таблицы Clickhouse в Python

Как развернуть быстро Clickhouse с помощью Docker

Как собрать свой образ Clickhouse (docker-compose из оффициальной репы)

В репозитории Github Clickhouse лежит docker-compose.yml файл со следующим содержимым:

version: "2"

services:
  builder:
    image: clickhouse/clickhouse-builder
    build: docker/builder
  client:
    image: clickhouse/clickhouse-client
    build: docker/client
    command: ['--host', 'server']
  server:
    image: clickhouse/clickhouse-server
    build: docker/server
    ports:
      - 8123:8123

version: "2"

services:

builder:

image: clickhouse/clickhouse-builder

build: docker/builder

client:

image: clickhouse/clickhouse-client

build: docker/client

command: ['--host', 'server']

server:

image: clickhouse/clickhouse-server

build: docker/server

ports:

- 8123:8123

Данный файл запускает сборку образов и после сборки запускает контейнеры. Запустится три контейнера:

clickhouse_client_1
clickhouse_builder_1
clickhouse_server_1

Сразу скажу, что не очень подходящий способ для использования Clickhouse, т.к. сборка образов требует много времени и лучше использовать уже сформированный официальный образ от Clickhouse.

Но если вы хотите пойти по пути сборки своих образов, то Вам понадобится запустить следующие команды на сервере:

git clone https://github.com/ClickHouse/ClickHouse.git

cd ClickHouse

git checkout v21.12.2.17-stable

git status

sudo docker-compose -f docker-compose.yml up

git clone https://github.com/ClickHouse/ClickHouse.git

cd ClickHouse

git checkout v21.12.2.17-stable

git status

sudo docker-compose -f docker-compose.yml up

Если в браузере перейти по url http://localhost:8123/, то отрисуется сообщение OK

Установка Clickhouse из официального образа с hub.docker.com

Официальная инструкция как задеплоить образ находится здесь https://hub.docker.com/r/clickhouse/clickhouse-server/.

Запускаем команду:

sudo docker pull clickhouse/clickhouse-server

1	sudo docker pull clickhouse/clickhouse-server

Скачается официальный докер образ (но пока еще не запустится):

Далее необходимо запустить из образа контейнер:

sudo docker run -d --name some-clickhouse-server -p 8123:8123 --ulimit nofile=262144:262144 yandex/clickhouse-server

1	sudo docker run -d --name some-clickhouse-server -p 8123:8123 --ulimit nofile=262144:262144 yandex/clickhouse-server

Чтобы проверить, что у Вас запустился контейнер с Clickhouse — запустите команду:

sudo docker ps

1	sudo docker ps

Проверить работу Clickhouse-server можно перейдя по url http://localhost:8123/:

Далее запускаем команду:

sudo docker run -it --rm --link some-clickhouse-server:clickhouse-server yandex/clickhouse-client --host clickhouse-server

1	sudo docker run -it --rm --link some-clickhouse-server:clickhouse-server yandex/clickhouse-client --host clickhouse-server

С помощью этой команды мы подключимся к Clickhouse через native client:

Клиент командной строки

ClickHouse предоставляет собственный клиент командной строки: clickhouse-client. Клиент поддерживает запуск с аргументами командной строки и с конфигурационными файлами.

Клиент устанавливается пакетом clickhouse-client и запускается командой clickhouse-client.

Установка на Ubuntu:

sudo apt install clickhouse-client

1	sudo apt install clickhouse-client

Запуск клиента:

$ clickhouse-client
ClickHouse client version 20.13.1.5273 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 20.13.1 revision 54442.

:)

$ clickhouse-client

ClickHouse client version 20.13.1.5273 (official build).

Connecting to localhost:9000 as user default.

Connected to ClickHouse server version 20.13.1 revision 54442.

Клиенты и серверы различных версий совместимы, однако если клиент старее сервера, то некоторые новые функции могут быть недоступны. Рекомендуется использовать одинаковые версии клиента и сервера.

Видео «Установка базы данных ClickHouse в виде контейнера Docker»

Установка Clickhouse с помощью docker-compose

Источник docker-compose файла: ClickHouse Server in 1 minute with Docker

Создаем директорию:

mkdir clickhouse-dc
cd clickhouse-dc

1 2	mkdir clickhouse-dc cd clickhouse-dc

Далее создаем папку db, куда clickhouse будет сохранять файлы:

mkdir db

mkdir db

Далее создаем файл docker-compose.yml

version: '3'

services:
  ch_server:
    image: yandex/clickhouse-server
    ports:
      - "8123:8123"
    volumes:
      - ./db:/var/lib/clickhouse
    networks:
        - ch_ntw

  ch_client:
    image: yandex/clickhouse-client
    entrypoint:
      - /bin/sleep
    command:
      - infinity
    networks:
        - ch_ntw

version: '3'

services:

ch_server:

image: yandex/clickhouse-server

ports:

- "8123:8123"

volumes:

- ./db:/var/lib/clickhouse

networks:

- ch_ntw

ch_client:

image: yandex/clickhouse-client

entrypoint:

- /bin/sleep

command:

- infinity

networks:

- ch_ntw

Далее запускаем установку с помощью docker-compose:

sudo docker-compose up -d

1	sudo docker-compose up -d

Зайти внутрь клиента кликхауса можно с помощью команды:

sudo docker-compose exec ch_server clickhouse-client

1	sudo docker-compose exec ch_server clickhouse-client

Подключаемся к Clickhouse с помощью DBeaver

Установить dbeaver в Ubuntu можно через Ubuntu Software:

Выбираем коннектор к Clickhouse:

Настройки подключения с дефолтным юзером:

show databases — проверочный запрос к clickhouse:

Интерфейсы для доступа к Clickhouse

ClickHouse имеет богатый набор функций для управления сетевыми подключениями для клиентов, а также для других серверов в кластере. Тем не менее, новым пользователям может быть сложно проработать возможные варианты, а опытным пользователям может быть сложно обеспечить полный доступ к развернутым системам для приложений и их надлежащую защиту.

Следующий кусок взят из официальной документации раздела «Интерфейсы»:

ClickHouse предоставляет три сетевых интерфейса (они могут быть обернуты в TLS для дополнительной безопасности):

HTTP, который задокументирован и прост для использования напрямую;
Native TCP, который имеет меньше накладных расходов;
gRPC.

В большинстве случаев рекомендуется использовать подходящий инструмент или библиотеку, а не напрямую взаимодействовать с ClickHouse. Официально поддерживаемые Яндексом:

Существует также широкий спектр сторонних библиотек для работы с ClickHouse:

Что такое http-интерфейс

HTTP интерфейс позволяет использовать ClickHouse на любой платформе, из любого языка программирования. HTTP интерфейс более ограничен по сравнению с родным интерфейсом, но является более совместимым. По умолчанию clickhouse-server слушает HTTP на порту 8123. Запрос отправляется в виде URL параметра с именем query. Или как тело запроса при использовании метода POST. Или начало запроса в URL параметре query, а продолжение POST-ом. Размер URL ограничен 16KB, это следует учитывать при отправке больших запросов.

Порт 8123 является конечной точкой интерфейса HTTP по умолчанию. Вы будете использовать этот порт, если используете команды curl для отправки запросов серверу. Кроме того, ряд библиотек, таких как JDBC-драйвер Yandex ClickHouse, скрытно используют HTTP-запросы, так что вы можете использовать http-интерфейс, даже не подозревая об этом.

Что такое Native TCP (Родной интерфейс)

Нативный протокол используется в клиенте командной строки, для взаимодействия между серверами во время обработки распределенных запросов, а также в других программах на C++. К сожалению, у родного протокола ClickHouse пока нет формальной спецификации.

Порт 9000 является конечной точкой Native TCP интерфейса (по-умолчанию). Он широко используется клиентами, как показано на следующих примерах.

Clickhouse-client, стандартный клиент командной строки для ClickHouse, использует собственный протокол TCP/IP.
Точно так же механизм ClickHouse Distributed использует собственный протокол TCP/IP для отправки подзапросов в базовые таблицы. В редких случаях он также используется реплицированными таблицами при отправке запросов ведущей реплике.
Наконец, драйверы, такие как драйвер Python clickhouse или драйвер Golang, общаются с ClickHouse, используя собственный протокол TCP/IP.

Что такое gRPC

ClickHouse поддерживает интерфейс gRPC. Это система удаленного вызова процедур с открытым исходным кодом, которая использует HTTP/2 и Protocol Buffers.

gRPC — мощный фреймворк для работы с удаленными вызовами процедур. RPC позволяют писать код так, как если бы он был запущен на локальном компьютере, даже если он может выполняться на другом компьютере.

Как правило, gRPC считается лучшей альтернативой протоколу REST для микросервисной архитектуры. Букву g в gRPC можно отнести к компании Google, которая изначально разработала эту технологию. gRPC создан для преодоления ограничений REST в связи с микросервисами.

gRPC — это новейшая структура, созданная на основе протокола RPC. Он использует свои преимущества и пытается исправить проблемы традиционного RPC. gRPC использует буферы протокола в качестве языка определения интерфейса для сериализации и связи вместо JSON/XML.

Буферы протокола могут описывать структуру данных, и на основе этого описания может быть сгенерирован код для генерации или анализа потока байтов, представляющего структурированные данные. По этой причине gRPC предпочтительнее для многоязычных веб-приложений (реализованных с использованием различных технологий). Формат двоичных данных позволяет облегчить общение. gRPC также можно использовать с другими форматами данных, но предпочтительным является буфер протокола.

Кроме того, gRPC построен на основе HTTP/2, который поддерживает двунаправленную связь наряду с традиционным запросом/ответом. gRPC допускает слабую связь между сервером и клиентом. На практике клиент открывает долговременное соединение с сервером gRPC, и новый поток HTTP/2 открывается для каждого вызова RPC.

В отличие от REST, который использует JSON (в основном), gRPC использует буферы протокола, которые являются лучшим способом кодирования данных. Поскольку JSON — это текстовый формат, он будет намного тяжелее, чем сжатые данные в формате protobuf.

Network Listener Configuration

ClickHouse позволяет легко включать и отключать порты слушателей, а также назначать им новые номера. Для каждого типа порта существуют простые теги config.xml, как показано в следующей таблице. Столбец обычных значений показывает номер порта, который большинство клиентов предполагает для определенного соединения. Если вы измените значение, вам может потребоваться соответствующее изменение клиентов.

Тег	Описание	Условное значение
http_port	Порт для незашифрованных HTTP-запросов	8123
https_port	Порт для зашифрованных запросов HTTPS	8443
interserver_http_port	Порт для незашифрованного трафика HTTP-репликации	9009
interserver_https_port	Порт для зашифрованного трафика репликации HTTPS
tcp_port	Порт для незашифрованных собственных запросов TCP/IP	9000
tcp_port_secure	Порт для зашифрованных TLS собственных запросов TCP/IP	9440

Как создать database в Clickhouse, таблицу и вставить тестовые данные

Идем в dbeaver и запускаем скрипты.

1. Создаем базу данных в Clickhouse

CREATE DATABASE db_superset ENGINE = Memory COMMENT 'The temporary database to test Clickhouse and Apache Superset';

1	CREATE DATABASE db_superset ENGINE = Memory COMMENT 'The temporary database to test Clickhouse and Apache Superset';

2. Проверяем, что база данных создалась:

SELECT name, comment FROM system.databases WHERE name = 'db_superset';

1	SELECT name, comment FROM system.databases WHERE name = 'db_superset';

3. Создаем таблицу в Clickhouse:

CREATE TABLE IF NOT EXISTS db_superset.facts
(
id            UInt32,
product       String,
datetime      DateTime,
customer      Nullable(String),
amount        Nullable(Float32)
) ENGINE = Log;

CREATE TABLE IF NOT EXISTS db_superset.facts

(

id UInt32,

product String,

datetime DateTime,

customer Nullable(String),

amount Nullable(Float32)

) ENGINE = Log;

4. Вставляем первую строку данных:

INSERT INTO db_superset.facts (*) VALUES (1, 'product 1', '2021-10-01', 'Customer 1', 10);

1	INSERT INTO db_superset.facts (*) VALUES (1, 'product 1', '2021-10-01', 'Customer 1', 10);

5. Проверяем, что в Clickhouse данные вставились:

SELECT id, product, `datetime`, customer, amount
FROM db_superset.facts;

1 2	SELECT id, product, `datetime`, customer, amount FROM db_superset.facts;

Далее попробуем вставить еще 1 строку с помощью разных вариантов.

Как подключиться к Clickhouse с помощью Python

Вариант 1 — clickhouse-driver (Python Driver with native interface)

https://github.com/mymarilyn/clickhouse-driver — ClickHouse Python Driver with native interface support
Подробная документация по clickhouse-driver >>>

Установка:

pip install clickhouse-driver

1	pip install clickhouse-driver

Краткое описание: clickhouse-driver работает через 9000 порт, поэтому он должен быть открыт и должен быть настроен listener. По умолчанию 9000 порт в образе докера открыт, но может не настроен listener. Делается это через config файл для clickhouse server — по-умолчанию лежит тут etc/clickhouse-server/config.xml.

Пример запроса Show Databases:

from clickhouse_driver import Client
client = Client('63.123.91.237') #логин пароль порт по умолчанию, дефолтная БД тоже по умолчанию
result = client.execute("SHOW DATABASES")
print(result)

from clickhouse_driver import Client

client = Client('63.123.91.237') #логин пароль порт по умолчанию, дефолтная БД тоже по умолчанию

result = client.execute("SHOW DATABASES")

print(result)

Пример Select запроса:

from clickhouse_driver import Client
client = Client('63.123.91.237') #логин пароль порт по умолчанию, дефолтная БД тоже по умолчанию
result = client.execute("SELECT * FROM db_superset.facts")
print(result)

from clickhouse_driver import Client

client = Client('63.123.91.237') #логин пароль порт по умолчанию, дефолтная БД тоже по умолчанию

result = client.execute("SELECT * FROM db_superset.facts")

print(result)

Вставка 1 команды Insert через Execute:

from clickhouse_driver import Client
import pandas as pd

client = Client('63.123.91.237')

client.execute("INSERT INTO db_superset.facts (*) VALUES (1, 'product 1', '2021-10-01', 'Customer 1', 10)")

from clickhouse_driver import Client

import pandas as pd

client = Client('63.123.91.237')

client.execute("INSERT INTO db_superset.facts (*) VALUES (1, 'product 1', '2021-10-01', 'Customer 1', 10)")

Вставка dataframe pandas:

Подробности по настройкам можно почитать в документации в разделе NumPy/Pandas support >>>

from clickhouse_driver import Client
import pandas as pd

client = Client('63.123.91.237', settings={'use_numpy': True})

# Creating Dataframe 
df = pd.DataFrame([
                    [152, 'product 152', '2021-10-04', 'Customer 1', 4], 
                    [153, 'product 153', '2021-10-06', 'Customer 1', 5], 
                    [154, 'product 154', '2021-10-07', 'Customer 1', 7]
                  ],
                  columns =['id', 'product', 'datetime', 'customer', 'amount'])
print(df)

client.insert_dataframe(f'INSERT INTO db_superset.facts VALUES', df)

from clickhouse_driver import Client

import pandas as pd

client = Client('63.123.91.237', settings={'use_numpy': True})

# Creating Dataframe

df = pd.DataFrame([

[152, 'product 152', '2021-10-04', 'Customer 1', 4],

[153, 'product 153', '2021-10-06', 'Customer 1', 5],

[154, 'product 154', '2021-10-07', 'Customer 1', 7]

columns =['id', 'product', 'datetime', 'customer', 'amount'])

print(df)

client.insert_dataframe(f'INSERT INTO db_superset.facts VALUES', df)

Вариант 2 — sqlalchemy-clickhouse (ClickHouse dialect for SQLAlchemy)

https://github.com/cloudflare/sqlalchemy-clickhouse — этот коннектор рекомендуется для использования в superset. Строка подключения выглядит как:

clickhouse+native://<user>:<password>@<host>:<port>/<database>[?options…]clickhouse://{username}:{password}@{hostname}:{port}/{database}

1	clickhouse+native://<user>:<password>@<host>:<port>/<database>[?options…]clickhouse://{username}:{password}@{hostname}:{port}/{database}

Установка:

pip install sqlalchemy-clickhouse

1	pip install sqlalchemy-clickhouse

Пример Select запроса:

туду

Вариант 3 — pandahouse (Pandas interface for Clickhouse database)

Github проект Pandahouse — https://github.com/kszucs/pandahouse

Установка:

pip install pandahouse

1	pip install pandahouse

Пример Select запроса:

туду

Вариант 4 — aiochclient (http(s) ClickHouse client for python 3.6+)

https://github.com/maximdanilchenko/aiochclient — Lightweight async http(s) ClickHouse client for python 3.6+ with types converting

туду

Вариант 5 — asynch (native TCP interface)

https://github.com/long2ice/asynch — An asyncio ClickHouse Python Driver with native (TCP) interface support.

туду

Как создать таблицу в Clickhouse и записать данные с помощью Python

todo

Как получить данные из таблицы Clickhouse в Python

todo