Документация

Начало работы

Системные требования

Система некроссплатформенная. Требуется ОС Linux Ubuntu не более старая, чем Precise (12.04); архитектура x86_64 с поддержкой набора инструкций SSE 4.2. Для проверки наличия SSE 4.2, выполните:

grep -q sse4_2 /proc/cpuinfo && echo "SSE 4.2 supported" || echo "SSE 4.2 not supported"

Рекомендуется использовать Ubuntu Trusty или Ubuntu Xenial или Ubuntu Precise. Терминал должен работать в кодировке UTF-8 (как по умолчанию в Ubuntu).

Установка

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

Установка из пакетов

Пропишите в /etc/apt/sources.list (или в отдельный файл /etc/apt/sources.list.d/clickhouse.list) репозитории:

deb http://repo.yandex.ru/clickhouse/trusty stable main

На других версиях Ubuntu, замените trusty на xenial или precise.

Затем выполните:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv E0C56BD4    # optional
sudo apt-get update
sudo apt-get install clickhouse-client clickhouse-server-common

Также можно скачать и установить пакеты вручную, отсюда: http://repo.yandex.ru/clickhouse/trusty/pool/main/c/clickhouse/, http://repo.yandex.ru/clickhouse/xenial/pool/main/c/clickhouse/, http://repo.yandex.ru/clickhouse/precise/pool/main/c/clickhouse/.

ClickHouse содержит настройки ограничения доступа. Они расположены в файле users.xml (рядом с config.xml). По умолчанию, разрешён доступ отовсюду для пользователя default без пароля. См. секцию users/default/networks. Подробнее смотрите в разделе “конфигурационные файлы”.

Установка из исходников

Для сборки воспользуйтесь инструкцией: build.md

Вы можете собрать пакеты и установить их. Также вы можете использовать программы без установки пакетов.

Клиент: dbms/src/Client/ Сервер: dbms/src/Server/

Для сервера создаёте директории с данными, например:

/opt/clickhouse/data/default/
/opt/clickhouse/metadata/default/

(Настраивается в конфиге сервера.) Сделайте chown под нужного пользователя.

Обратите внимание на путь к логам в конфиге сервера (src/dbms/src/Server/config.xml).

Другие методы установки

Docker образ: https://hub.docker.com/r/yandex/clickhouse-server/

Gentoo overlay: https://github.com/kmeaw/clickhouse-overlay

Запуск

Для запуска сервера (в качестве демона), выполните:

sudo service clickhouse-server start

Смотрите логи в директории /var/log/clickhouse-server/

Если сервер не стартует - проверьте правильность конфигурации в файле /etc/clickhouse-server/config.xml

Также можно запустить сервер из консоли:

clickhouse-server --config-file=/etc/clickhouse-server/config.xml

При этом, лог будет выводиться в консоль - удобно для разработки. Если конфигурационный файл лежит в текущей директории, то указывать параметр –config-file не требуется - по умолчанию будет использован файл ./config.xml

Соединиться с сервером можно с помощью клиента командной строки:

clickhouse-client

Параметры по умолчанию обозначают - соединяться с localhost:9000, от имени пользователя default без пароля. Клиент может быть использован для соединения с удалённым сервером. Пример:

clickhouse-client --host=example.com

Подробнее смотри раздел “Клиент командной строки”.

Проверим работоспособность системы:

milovidov@milovidov-Latitude-E6320:~/work/metrica/src/dbms/src/Client$ ./clickhouse-client
ClickHouse client version 0.0.18749.
Connecting to localhost:9000.
Connected to ClickHouse server version 0.0.18749.

:) SELECT 1

SELECT 1

┌─1─┐
│ 1 │
└───┘

1 rows in set. Elapsed: 0.003 sec.

:)

Поздравляю, система работает!

Тестовые данные

Если вы сотрудник Яндекса, вы можете воспользоваться тестовыми данными Яндекс.Метрики для изучения возможностей системы. Как загрузить тестовые данные, написано здесь.

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

Если возникли вопросы

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

Иначе вы можете задавать вопросы на Stackoverflow или участвовать в обсуждениях на Google Groups. Также вы можете отправить приватное сообщение для разрабочиков по адресу clickhouse-feedback@yandex-team.com.

Интерфейсы

Для изучения возможностей системы, загрузки данных в таблицы, ручных запросов, используйте программу clickhouse-client.

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

Для работы из командной строки вы можете использовать clickhouse-client:

$ clickhouse-client
ClickHouse client version 0.0.26176.
Connecting to localhost:9000.
Connected to ClickHouse server version 0.0.26176.

:) SELECT 1

Программа clickhouse-client принимает следующие параметры, все из которых являются необязательными:

--host, -h - имя сервера, по умолчанию - localhost. Вы можете использовать как имя, так и IPv4 или IPv6 адрес.

--port - порт, к которому соединяться, по умолчанию - 9000. Замечу, что для HTTP и родного интерфейса используются разные порты.

--user, -u - имя пользователя, по умолчанию - default.

--password - пароль, по умолчанию - пустая строка.

--query, -q - запрос для выполнения, при использовании в неинтерактивном режиме.

--database, -d - выбрать текущую БД, по умолчанию - текущая БД из настроек сервера (по умолчанию - БД default).

--multiline, -m - если указано - разрешить многострочные запросы, не отправлять запрос по нажатию Enter.

--multiquery, -n - если указано - разрешить выполнять несколько запросов, разделённых точкой с запятой. Работает только в неинтерактивном режиме.

--format, -f - использовать указанный формат по умолчанию для вывода результата. --vertical, -E - если указано, использовать формат Vertical по умолчанию для вывода результата. То же самое, что –format=Vertical. В этом формате каждое значение выводится на отдельной строке, что удобно для отображения широких таблиц. --time, -t - если указано, в неинтерактивном режиме вывести время выполнения запроса в stderr. --stacktrace - если указано, в случае исключения, выводить также его стек трейс. --config-file - имя конфигурационного файла, в котором есть дополнительные настройки или изменены умолчания для настроек, указанных выше. По умолчанию, ищутся файлы в следующем порядке: ./clickhouse-client.xml ~/./clickhouse-client/config.xml /etc/clickhouse-client/config.xml Настройки берутся только из первого найденного файла.

Также вы можете указать любые настроки, которые будут использованы для обработки запросов. Например, clickhouse-client –max_threads=1. Подробнее см. раздел “Настройки”.

Клиент может быть использован в интерактивном и неинтерактивном (batch) режиме. Чтобы использовать batch режим, укажите параметр query, или отправьте данные в stdin (проверяется, что stdin - не терминал), или и то, и другое. Аналогично HTTP интерфейсу, при использовании одновременно параметра query и отправке данных в stdin, запрос составляется из конкатенации параметра query, перевода строки, и данных в stdin. Это удобно для больших INSERT запросов.

Примеры использования клиента для вставки данных:

echo -ne "1, 'some text', '2016-08-14 00:00:00'\n2, 'some more text', '2016-08-14 00:00:01'" | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

cat <<_EOF | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";
3, 'some text', '2016-08-14 00:00:00'
4, 'some more text', '2016-08-14 00:00:01'
_EOF

cat file.csv | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

В batch режиме в качестве формата данных по умолчанию используется формат TabSeparated. Формат может быть указан в секции FORMAT запроса.

По умолчанию, в batch режиме вы можете выполнить только один запрос. Чтобы выполнить несколько запросов из “скрипта”, используйте параметр –multiquery. Это работает для всех запросов кроме INSERT. Результаты запросов выводятся подряд без дополнительных разделителей. Также, при необходимости выполнить много запросов, вы можете запускать clickhouse-client на каждый запрос. Заметим, что запуск программы clickhouse-client может занимать десятки миллисекунд.

В интерактивном режиме, вы получите командную строку, в которую можно вводить запросы.

Если не указано multiline (по умолчанию): Чтобы выполнить запрос, нажмите Enter. Точка с запятой на конце запроса не обязательна. Чтобы ввести запрос, состоящий из нескольких строк, перед переводом строки, введите символ обратного слеша: \ - тогда после нажатия Enter, вам предложат ввести следующую строку запроса.

Если указано multiline (многострочный режим): Чтобы выполнить запрос, завершите его точкой с запятой и нажмите Enter. Если в конце введённой строки не было точки с запятой, то вам предложат ввести следующую строчку запроса.

Исполняется только один запрос, поэтому всё, что введено после точки с запятой, игнорируется.

Вместо или после точки с запятой может быть указано \G. Это обозначает использование формата Vertical. В этом формате каждое значение выводится на отдельной строке, что удобно для широких таблиц. Столь необычная функциональность добавлена для совместимости с MySQL CLI.

Командная строка сделана на основе readline (и history) (или libedit, или без какой-либо библиотеки, в зависимости от сборки) - то есть, в ней работают привычные сочетания клавиш, а также присутствует история. История пишется в ~/.clickhouse-client-history.

По умолчанию, в качестве формата, используется формат PrettyCompact (красивые таблички). Вы можете изменить формат с помощью секции FORMAT запроса, или с помощью указания G на конце запроса, с помощью аргумента командной строки –format или –vertical, или с помощью конфигурационного файла клиента.

Чтобы выйти из клиента, нажмите Ctrl+D (или Ctrl+C), или наберите вместо запроса одно из: “exit”, “quit”, “logout”, “учше”, “йгше”, “дщпщге”, “exit;”, “quit;”, “logout;”, “учшеж”, “йгшеж”, “дщпщгеж”, “q”, “й”, “q”, “Q”, ”:q”, “й”, “Й”, “Жй”

При выполнении запроса, клиент показывает:

1. Прогресс выполнение запроса, который обновляется не чаще, чем 10 раз в секунду (по умолчанию). При быстрых запросах, прогресс может не успеть отобразиться.
2. Отформатированный запрос после его парсинга - для отладки.
3. Результат в заданном формате.
4. Количество строк результата, прошедшее время, а также среднюю скорость выполнения запроса.

Вы можете прервать длинный запрос, нажав Ctrl+C. При этом вам всё равно придётся чуть-чуть подождать, пока сервер остановит запрос. На некоторых стадиях выполнения, запрос невозможно прервать. Если вы не дождётесь и нажмёте Ctrl+C второй раз, то клиент будет завершён.

Клиент командной строки позволяет передать внешние данные (внешние временные таблицы) для использования запроса. Подробнее смотрите раздел “Внешние данные для обработки запроса”

HTTP-интерфейс

HTTP интерфейс позволяет использовать ClickHouse на любой платформе, из любого языка программирования. У нас он используется для работы из Java и Perl, а также из shell-скриптов. В других отделах, HTTP интерфейс используется из Perl, Python и Go. HTTP интерфейс более ограничен по сравнению с родным интерфейсом, но является более совместимым.

По умолчанию, clickhouse-server слушает HTTP на порту 8123 (это можно изменить в конфиге). Если запросить GET / без параметров, то вернётся строка “Ok.” (с переводом строки на конце). Это может быть использовано в скриптах проверки живости.

$ curl 'http://localhost:8123/'
Ok.

Запрос отправляется в виде параметра URL query. Или POST-ом. Или начало запроса в параметре query, а продолжение POST-ом (зачем это нужно, будет объяснено ниже). В случае успеха, вам вернётся код ответа 200 и результат обработки запроса в теле ответа. В случае ошибки, вам вернётся код ответа 500 и текст с описанием ошибки в теле ответа.

При использовании метода GET, выставляется настройка readonly. То есть, для запросов, модифицирующие данные, можно использовать только метод POST. Сам запрос при этом можно отправлять как в теле POST-а, так и в параметре URL.

Примеры:

$ curl 'http://localhost:8123/?query=SELECT%201'
1

$ wget -O- -q 'http://localhost:8123/?query=SELECT 1'
1

$ GET 'http://localhost:8123/?query=SELECT 1'
1

$ echo -ne 'GET /?query=SELECT%201 HTTP/1.0\r\n\r\n' | nc localhost 8123
HTTP/1.0 200 OK
Connection: Close
Date: Fri, 16 Nov 2012 19:21:50 GMT

1

Как видно, curl немного неудобен тем, что надо URL-эскейпить пробелы. wget сам всё эскейпит, но его не рекомендуется использовать, так как он плохо работает по HTTP 1.1 при использовании keep-alive и Transfer-Encoding: chunked.

$ echo 'SELECT 1' | curl 'http://localhost:8123/' --data-binary @-
1

$ echo 'SELECT 1' | curl 'http://localhost:8123/?query=' --data-binary @-
1

$ echo '1' | curl 'http://localhost:8123/?query=SELECT' --data-binary @-
1

Если часть запроса отправляется в параметре, а часть POST-ом, то между этими двумя кусками данных ставится перевод строки. Пример (так работать не будет):

$ echo 'ECT 1' | curl 'http://localhost:8123/?query=SEL' --data-binary @-
Code: 59, e.displayText() = DB::Exception: Syntax error: failed at position 0: SEL
ECT 1
, expected One of: SHOW TABLES, SHOW DATABASES, SELECT, INSERT, CREATE, ATTACH, RENAME, DROP, DETACH, USE, SET, OPTIMIZE., e.what() = DB::Exception

По умолчанию, данные возвращаются в формате TabSeparated (подробнее смотри раздел “Форматы”). Можно попросить любой другой формат - с помощью секции FORMAT запроса.

$ echo 'SELECT 1 FORMAT Pretty' | curl 'http://localhost:8123/?' --data-binary @-
┏━━━┓
┃ 1 ┃
┡━━━┩
│ 1 │
└───┘

Возможность передавать данные POST-ом нужна для INSERT-запросов. В этом случае вы можете написать начало запроса в параметре URL, а вставляемые данные передать POST-ом. Вставляемыми данными может быть, например, tab-separated дамп, полученный из MySQL. Таким образом, запрос INSERT заменяет LOAD DATA LOCAL INFILE из MySQL.

Примеры: Создаём таблицу:

echo 'CREATE TABLE t (a UInt8) ENGINE = Memory' | POST 'http://localhost:8123/'

Используем привычный запрос INSERT для вставки данных:

echo 'INSERT INTO t VALUES (1),(2),(3)' | POST 'http://localhost:8123/'

Данные можно отправить отдельно от запроса:

echo '(4),(5),(6)' | POST 'http://localhost:8123/?query=INSERT INTO t VALUES'

Можно указать любой формат для данных. Формат Values - то же, что используется при записи INSERT INTO t VALUES:

echo '(7),(8),(9)' | POST 'http://localhost:8123/?query=INSERT INTO t FORMAT Values'

Можно вставить данные из tab-separated дампа, указав соответствующий формат:

echo -ne '10\n11\n12\n' | POST 'http://localhost:8123/?query=INSERT INTO t FORMAT TabSeparated'

Прочитаем содержимое таблицы. Данные выводятся в произвольном порядке из-за параллельной обработки запроса:

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

Удаляем таблицу.

POST 'http://localhost:8123/?query=DROP TABLE t'

Для запросов, которые не возвращают таблицу с данными, в случае успеха, выдаётся пустое тело ответа.

Вы можете использовать сжатие при передаче данных. Формат сжатых данных нестандартный, и вам придётся использовать для работы с ним специальную программу compressor (sudo apt-get install compressor-metrika-yandex).

Если вы указали в URL compress=1, то сервер будет сжимать отправляемые вам данные. Если вы указали в URL decompress=1, то сервер будет разжимать те данные, которые вы передаёте ему POST-ом.

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

В параметре URL 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

По умолчанию используется БД, которая прописана в настройках сервера, как БД по умолчанию. По умолчанию, это - БД default. Также вы всегда можете указать БД через точку перед именем таблицы.

Имя пользователя и пароль могут быть указаны в одном из двух вариантов: 1. С использованием HTTP Basic Authentification. Пример:

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

2. В параметрах URL user и password. Пример:

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

Если имя пользователя не указано, то используется имя пользователя default. Если пароль не указан, то используется пустой пароль. Также в параметрах URL вы можете указать любые настроки, которые будут использованы для обработки одного запроса, или целые профили настроек. Пример: 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

Об остальных параметрах смотри раздел “SET”.

В отличие от родного интерфейса, HTTP интерфейс не поддерживает понятие сессии и настройки в пределах сессии, не позволяет (вернее, позволяет лишь в некоторых случаях) прервать выполнение запроса, не показывает прогресс выполнения запроса. Парсинг и форматирование данных производится на стороне сервера и использование сети может быть неэффективным. Может быть передан необязательный параметр query_id - идентификатор запроса, произвольная строка. Подробнее смотрите раздел “Настройки, replace_running_query”.

Может быть передан необязательный параметр quota_key - ключ квоты, произвольная строка. Подробнее смотрите раздел “Квоты”.

HTTP интерфейс позволяет передать внешние данные (внешние временные таблицы) для использования запроса. Подробнее смотрите раздел “Внешние данные для обработки запроса”

JDBC-драйвер

Для ClickHouse существует официальный JDBC драйвер. Смотрите здесь .

Родной интерфейс (TCP)

Родной интерфейс используется в клиенте командной строки clickhouse-client, при межсерверном взаимодействии для распределённой обработки запроса, а также в программах на C++. Будет рассмотрен только клиент командной строки.

Библиотеки от сторонних разработчиков

Существуют библиотеки для работы с ClickHouse для:

• Python
• PHP (1, 2, 3)
• Go, (1, 2)
• Perl.

Библиотеки не тестировались нами. Порядок перечисления произвольный.

GUI от сторонних разработчиков

Существует минималистичный веб-интерфейс для ClickHouse от SMI2.