Merge pull request #231 from hatarist/reference_improvements

Reference improvements

MacOS.md

@@ -1,6 +1,6 @@
-==How to increase maxfiles on MacOS X==
+## How to increase maxfiles on Mac OS X
 
-To increase maxfiles on MacOS create the following file:
+To increase maxfiles on MacOS, create the following file:
 
 (Note: you'll need to use sudo)
 
@@ -29,11 +29,11 @@ To increase maxfiles on MacOS create the following file:
 </plist>
 ```
 
-execute the following command:
+Execute the following command:
 ```
 sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
 ```
 
 Reboot.
 
-To check if it's working, you can use 'ulimit -n' command
+To check if it's working, you can use `ulimit -n` command.

doc/build_osx.md

@@ -72,3 +72,7 @@ cmake ..
 make -j $THREADS
 cd ..
 ```
+
+# Caveats
+
+If you intend to run clickhouse-server, make sure to increase system's maxfiles variable. See [MacOS.md](https://github.com/yandex/ClickHouse/blob/master/MacOS.md) for more details.

doc/reference_en.html

@@ -441,7 +441,7 @@ By default, access is allowed from everywhere for the default user without a pas
 
 ===Installing from source===
 
-Build following the instructions in <a href="https://github.com/yandex/ClickHouse/blob/master/doc/build.md">build.md</a>
+To build, follow the instructions in <a href="https://github.com/yandex/ClickHouse/blob/master/doc/build.md">build.md</a> (for Linux) or in <a href="https://github.com/yandex/ClickHouse/blob/master/doc/build_osx.md">build_osx.md</a> (for Mac OS X).
 
 You can compile packages and install them. You can also use programs without installing packages.
 
@@ -4753,6 +4753,8 @@ The same as &#39;substring&#39;, but for Unicode code points. Works under the as
 ===appendTrailingCharIfAbsent(s, c)===
 If the %%s%% string is non-empty and does not contain the %%c%% character at the end, it appends the %%c%% character to the end.
 
+===convertCharset(s, from, to)===
+Returns a string with the data %%s%% (encoded as %%from%% charset) that was converted to the %%to%% charset.
 
 ==Functions for searching strings==
 
@@ -4762,9 +4764,11 @@ The search substring or regular expression must be a constant in all these funct
 ===position(haystack, needle)===
 Searches for the &#39;needle&#39; substring in the &#39;haystack&#39; string.
 Returns the position (in bytes) of the found substring, starting from 1, or returns 0 if the substring was not found.
+There's also positionCaseInsensitive function.
 
 ===positionUTF8(haystack, needle)===
 The same as &#39;position&#39;, but the position is returned in Unicode code points. Works under the assumption that the string contains a set of bytes representing a UTF-8 encoded text. If this assumption is not met, it returns some result (it doesn&#39;t throw an exception).
+There's also positionCaseInsensitiveUTF8 function.
 
 ===match(haystack, pattern)===
 Checks whether the string matches the &#39;pattern&#39; regular expression.
@@ -5894,6 +5898,78 @@ LIMIT 10
 └────────────────┴─────────┘
 %%
 
+===formatReadableSize(x)===
+
+Gets a size (number of bytes). Returns a string that contains rounded size with the suffix (KiB, MiB etc.).
+
+Example:
+
+%%
+SELECT
+    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
+    formatReadableSize(filesize_bytes) AS filesize
+
+┌─filesize_bytes─┬─filesize───┐
+│              1 │ 1.00 B     │
+│           1024 │ 1.00 KiB   │
+│        1048576 │ 1.00 MiB   │
+│      192851925 │ 183.92 MiB │
+└────────────────┴────────────┘
+%%
+
+===least(a, b)===
+
+Returns the least element of a and b.
+
+===greatest(a, b)===
+
+Returns the greatest element of a and b.
+
+===uptime()===
+
+Returns server's uptime in seconds.
+
+===version()===
+
+Returns server's version as a string.
+
+===rowNumberInAllBlocks()===
+
+Returns an incremental row number within all blocks that were processed by this function.
+
+===runningDifference(x)===
+
+Calculates the difference between consecutive values in the data block.
+Result of the function depends on the order of the data in the blocks.
+
+It works only inside of the each processed block of data. Data splitting in the blocks is not explicitly controlled by the user. 
+If you specify ORDER BY in subquery and call runningDifference outside of it, you could get an expected result.
+
+Example:
+%%
+SELECT
+    EventID,
+    EventTime,
+    runningDifference(EventTime) AS delta
+FROM
+(
+    SELECT
+        EventID,
+        EventTime
+    FROM events
+    WHERE EventDate = '2016-11-24'
+    ORDER BY EventTime ASC
+    LIMIT 5
+)
+
+┌─EventID─┬───────────EventTime─┬─delta─┐
+│    1106 │ 2016-11-24 00:00:04 │     0 │
+│    1107 │ 2016-11-24 00:00:05 │     1 │
+│    1108 │ 2016-11-24 00:00:05 │     0 │
+│    1109 │ 2016-11-24 00:00:09 │     4 │
+│    1110 │ 2016-11-24 00:00:10 │     1 │
+└─────────┴─────────────────────┴───────┘
+%%
 
 ==arrayJoin function==
 
@@ -5926,14 +6002,6 @@ SELECT
 └─────┴───────────┴─────────┘
 %%
 
-===least(a, b)===
-
-Returns the least element of a and b.
-
-===greatest(a, b)===
-
-Returns the greatest element of a and b.
-
 </div>
 <div class="island">
 <h1>Aggregate functions</h1>

doc/reference_ru.html

@@ -450,7 +450,7 @@ ClickHouse содержит настройки ограничения досту
 
 ===Установка из исходников===
 
-Для сборки воспользуйтесь инструкцией: <a href="https://github.com/yandex/ClickHouse/blob/master/doc/build.md">build.md</a>
+Для сборки воспользуйтесь инструкцией <a href="https://github.com/yandex/ClickHouse/blob/master/doc/build.md">build.md</a> (для Linux) или <a href="https://github.com/yandex/ClickHouse/blob/master/doc/build_osx.md">build_osx.md</a> (для Mac OS X).
 
 Вы можете собрать пакеты и установить их.
 Также вы можете использовать программы без установки пакетов.
@@ -1598,7 +1598,7 @@ ORDER BY PageViews DESC LIMIT 1000%%
 
 Выборка с указанием относительного коэффициента является "согласованной": если рассмотреть все возможные данные, которые могли бы быть в таблице, то выборка (при использовании одного выражения сэмплирования, указанного при создании таблицы), с одинаковым коэффициентом, выбирает всегда одно и то же подмножество этих всевозможных данных. То есть, выборка из разных таблиц, на разных серверах, в разное время, делается одинаковым образом.
 
-Например, выборка по идентификаторам посетителей, выберет из разных таблиц строки с одинаковым подножеством всех возможных идентификаторов посетителей. Это позволяет использовать выборку в подзапросах в секции IN, а также при ручном сопоставлении результатов разных запросов с выборками.
+Например, выборка по идентификаторам посетителей, выберет из разных таблиц строки с одинаковым подмножеством всех возможных идентификаторов посетителей. Это позволяет использовать выборку в подзапросах в секции IN, а также при ручном сопоставлении результатов разных запросов с выборками.
 
 <h4>Секция ARRAY JOIN</h4>
 
@@ -2567,6 +2567,7 @@ calcs - имя кластера в конфигурационном файле
 
 Если после INSERT-а в Distributed таблицу, сервер перестал существовать или был грубо перезапущен (например, в следствие аппаратного сбоя), то записанные данные могут быть потеряны. Если в директории таблицы обнаружен повреждённый кусок данных, то он переносится в поддиректорию broken и больше не используется.
 
+При выставлении опции max_parallel_replicas выполнение запроса распараллеливается по всем репликам внутри одного шарда. Подробнее смотрите раздел "Настройки, max_parallel_replicas".
 
 ==MergeTree==
 
@@ -2643,12 +2644,12 @@ CollapsingMergeTree принимает дополнительный параме
 
 Здесь Sign - столбец, содержащий -1 для "старых" значений и 1 для "новых" значений.
 
-При слиянии, для каждой группы идущих подряд одинаковых значений первичного ключа (столбцов, по которым сортируются данные), остаётся не более одной строки со значением столбца sign_column = -1 ("отрицательной строки") и не более одиной строки со значением столбца sign_column = 1 ("положительной строки"). То есть - производится схлопывание записей из лога изменений.
+При слиянии, для каждой группы идущих подряд одинаковых значений первичного ключа (столбцов, по которым сортируются данные), остаётся не более одной строки со значением столбца sign_column = -1 ("отрицательной строки") и не более одной строки со значением столбца sign_column = 1 ("положительной строки"). То есть - производится схлопывание записей из лога изменений.
 
 Если количество положительных и отрицательных строк совпадает - то пишет первую отрицательную и последнюю положительную строку.
 Если положительных на 1 больше, чем отрицательных - то пишет только последнюю положительную строку.
 Если отрицательных на 1 больше, чем положительных - то пишет только первую отрицательную строку.
-Иначе - логическая ошибка, и ни одна из таких строк не пишется. (Логическая ошибка может возникать, если случано один кусок лога был вставлен более одного раза. Поэтому, об ошибке всего лишь пишется в лог сервера, и слияние продолжает работать.)
+Иначе - логическая ошибка, и ни одна из таких строк не пишется. (Логическая ошибка может возникать, если случайно один кусок лога был вставлен более одного раза. Поэтому, об ошибке всего лишь пишется в лог сервера, и слияние продолжает работать.)
 
 Как видно, от схлопывания не должны меняться результаты расчётов статистик.
 Изменения постепенно схлопываются так что в конце-концов, для почти каждого объекта, остаются лишь его последние значения.
@@ -2868,7 +2869,7 @@ min_bytes, max_bytes - условие на количество байт в бу
 
 Данные, вставляемые в таблицу Buffer, попадают в подчинённую таблицу в порядке, возможно отличающимся от порядка вставки, и блоками, возможно отличающимися от вставленных блоков. В связи с этим, трудно корректно использовать таблицу типа Buffer для записи в CollapsingMergeTree. Чтобы избежать проблемы, можно выставить num_layers в 1.
 
-Если таблица назначения является реплицируемой, то при записи в таблицу Buffer будут потеряны некоторые ожидаемые свойства реплицируемых таблиц. Из-за произвольного изменения порядка строк и размеров блоков данных, перестаёт работать дедубликация данных, в результате чего исчезает возможность надёжной exactly once записи в реплицируемые таблицы.
+Если таблица назначения является реплицируемой, то при записи в таблицу Buffer будут потеряны некоторые ожидаемые свойства реплицируемых таблиц. Из-за произвольного изменения порядка строк и размеров блоков данных, перестаёт работать дедупликация данных, в результате чего исчезает возможность надёжной exactly once записи в реплицируемые таблицы.
 
 В связи с этими недостатками, таблицы типа Buffer можно рекомендовать к применению лишь в очень редких случаях.
 
@@ -2928,7 +2929,7 @@ min_bytes, max_bytes - условие на количество байт в бу
 
 Каждый блок данных записывается атомарно. Запрос INSERT разбивается на блоки данных размером до max_insert_block_size = 1048576 строк. То есть, если в запросе INSERT менее 1048576 строк, то он делается атомарно.
 
-Блоки данных дедублицируются. При многократной записи одного и того же блока данных (блоков данных одинакового размера, содержащих одни и те же строчки в одном и том же порядке), блок будет записан только один раз. Это сделано для того, чтобы в случае сбоя в сети, когда клиентское приложение не может понять, были ли данные записаны в БД, можно было просто повторить запрос INSERT. При этом не имеет значения, на какую реплику будут отправлены INSERT-ы с одинаковыми данными. То есть, обеспечивается идемпотентность INSERT-ов. Это работает только для последних 100 вставленных в таблицу блоков.
+Блоки данных дедуплицируются. При многократной записи одного и того же блока данных (блоков данных одинакового размера, содержащих одни и те же строчки в одном и том же порядке), блок будет записан только один раз. Это сделано для того, чтобы в случае сбоя в сети, когда клиентское приложение не может понять, были ли данные записаны в БД, можно было просто повторить запрос INSERT. При этом не имеет значения, на какую реплику будут отправлены INSERT-ы с одинаковыми данными. То есть, обеспечивается идемпотентность INSERT-ов. Это работает только для последних 100 вставленных в таблицу блоков.
 
 При репликации, по сети передаются только исходные вставляемые данные. Дальнейшие преобразования данных (слияния) координируются и делаются на всех репликах одинаковым образом. За счёт этого минимизируется использование сети, и благодаря этому, репликация хорошо работает при расположении реплик в разных датацентрах. (Стоит заметить, что дублирование данных в разных датацентрах, по сути, является основной задачей репликации).
 
@@ -3044,7 +3045,7 @@ min_bytes, max_bytes - условие на количество байт в бу
 
 ===Восстановление в случае потери или повреждения метаданных на ZooKeeper кластере===
 
-Если вы продолбали ZooKeeper, то вы можете сохранить данные, переместив их в нереплицируемую таблицу, как описано в пункте выше.
+Если данные в ZooKeeper оказались утеряны или повреждены, то вы можете сохранить данные, переместив их в нереплицируемую таблицу, как описано в пункте выше.
 
 
 ==Перешардирование==
@@ -3619,7 +3620,7 @@ localhost
 Целые числа пишутся в десятичной форме. Числа могут содержать лишний символ "+" в начале (игнорируется при парсинге, а при форматировании не пишется). Неотрицательные числа не могут содержать знак отрицания. При чтении допустим парсинг пустой строки, как числа ноль, или (для знаковых типов) строки, состоящей из одного минуса, как числа ноль. Числа, не помещающиеся в соответствующий тип данных, могут парсится, как некоторое другое число, без сообщения об ошибке.
 
 Числа с плавающей запятой пишутся в десятичной форме. При этом, десятичный разделитель - точка. Поддерживается экспоненциальная запись, а также inf, +inf, -inf, nan. Запись числа с плавающей запятой может начинаться или заканчиваться на десятичную точку.
-При форматрировании, возможна потеря точности чисел с плавающей запятой.
+При форматировании возможна потеря точности чисел с плавающей запятой.
 При парсинге, допустимо чтение не обязательно наиболее близкого к десятичной записи машинно-представимого числа.
 
 Даты выводятся в формате YYYY-MM-DD, парсятся в том же формате, но с любыми символами в качестве разделителей.
@@ -4846,6 +4847,8 @@ SELECT
 ===appendTrailingCharIfAbsent(s, c)===
 Если строка %%s%% непустая и не содержит символ %%c%% на конце, то добавляет символ %%c%% в конец.
 
+===convertCharset(s, from, to)===
+Возвращает сконвертированную из кодировки from в кодировку to строку s.
 
 ==Функции поиска в строках==
 
@@ -4855,9 +4858,11 @@ SELECT
 ===position(haystack, needle)===
 Поиск подстроки needle в строке haystack.
 Возвращает позицию (в байтах) найденной подстроки, начиная с 1, или 0, если подстрока не найдена.
+Есть также функция positionCaseInsensitive.
 
 ===positionUTF8(haystack, needle)===
 Так же, как position, но позиция возвращается в кодовых точках Unicode. Работает при допущении, что строка содержит набор байт, представляющий текст в кодировке UTF-8. Если допущение не выполнено - то возвращает какой-нибудь результат (не кидает исключение).
+Есть также функция positionCaseInsensitiveUTF8.
 
 ===match(haystack, pattern)===
 Проверка строки на соответствие регулярному выражению pattern. Регулярное выражение re2.
@@ -5997,6 +6002,79 @@ LIMIT 10
 └────────────────┴─────────┘
 %%
 
+===formatReadableSize(x)===
+
+Принимает размер (число байт). Возвращает округленный размер с суффиксом (KiB, MiB и т.д.) в виде строки.
+
+Пример:
+
+%%
+SELECT
+    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
+    formatReadableSize(filesize_bytes) AS filesize
+
+┌─filesize_bytes─┬─filesize───┐
+│              1 │ 1.00 B     │
+│           1024 │ 1.00 KiB   │
+│        1048576 │ 1.00 MiB   │
+│      192851925 │ 183.92 MiB │
+└────────────────┴────────────┘
+%%
+
+===least(a, b)===
+
+Возвращает наименьшее значение из a и b.
+
+===greatest(a, b)===
+
+Возвращает наибольшее значение из a и b.
+
+===uptime()===
+
+Возвращает аптайм сервера в секундах.
+
+===version()===
+
+Возвращает версию сервера в виде строки.
+
+===rowNumberInAllBlocks()===
+
+Возвращает порядковый номер строки в блоке данных. Функция учитывает только задействованные блоки данных.
+
+===runningDifference(x)===
+
+Считает разницу между последовательными значениями строк в блоке данных.
+Возвращает 0 для первой строки и разницу с предыдущей строкой для каждой последующей строки.
+
+Результат функции зависит от затронутых блоков данных и порядка данных в блоке.
+Если сделать подзапрос с ORDER BY и вызывать функцию извне подзапроса, можно будет получить ожидаемый результат.
+
+Пример:
+%%
+SELECT
+    EventID,
+    EventTime,
+    runningDifference(EventTime) AS delta
+FROM
+(
+    SELECT
+        EventID,
+        EventTime
+    FROM events
+    WHERE EventDate = '2016-11-24'
+    ORDER BY EventTime ASC
+    LIMIT 5
+)
+
+┌─EventID─┬───────────EventTime─┬─delta─┐
+│    1106 │ 2016-11-24 00:00:04 │     0 │
+│    1107 │ 2016-11-24 00:00:05 │     1 │
+│    1108 │ 2016-11-24 00:00:05 │     0 │
+│    1109 │ 2016-11-24 00:00:09 │     4 │
+│    1110 │ 2016-11-24 00:00:10 │     1 │
+└─────────┴─────────────────────┴───────┘
+%%
+
 
 ==Функция arrayJoin==
 
@@ -6030,14 +6108,6 @@ SELECT
 └─────┴───────────┴─────────┘
 %%
 
-===least(a, b)===
-
-Возвращает наименьшее значение из a и b.
-
-===greatest(a, b)===
-
-Возвращает наибольшее значение из a и b.
-
 </div>
 <div class="island">
 <h1>Агрегатные функции</h1>
@@ -6429,7 +6499,7 @@ regions_hierarchy*.txt: TabSeparated (без заголовка), столбцы
 
 regions_names_*.txt: TabSeparated (без заголовка), столбцы:
 - идентификатор региона (UInt32);
-- имя региона (String) - не может содержать табы или переводы строк, даже заэскейпленные.
+- имя региона (String) - не может содержать табы или переводы строк, даже экранированные.
 
 Для хранения в оперативке используется плоский массив. Поэтому, идентификаторы не должны быть больше миллиона.
 
@@ -6625,7 +6695,7 @@ id рекламодателя    дата начала действия скид
  
 dictGetT('dict_name', 'attr_name', id, date)
 
-Функция достаёт значение для данного id и для диапазона дат, в который входит переданная дата. Если не найден id или для найденного id не найден диапазон, то возвращается значение по-умолчанию для словаря.
+Функция достаёт значение для данного id и для диапазона дат, в который входит переданная дата. Если не найден id или для найденного id не найден диапазон, то возвращается значение по умолчанию для словаря.
 
 Если есть перекрывающиеся диапазоны, то можно использовать любой подходящий.
  
@@ -6905,6 +6975,13 @@ dictGetT('dict_name', 'attr_name', id, date)
 Если равно 1 - сэмплирование по умолчанию не делается.
 
 
+==max_parallel_replicas==
+
+Максимальное количество используемых реплик каждого шарда при выполнении запроса.
+Для консистентности (чтобы получить разные части одного и того же разбиения), эта опция работает только при заданном ключе сэмплирования.
+Отставание реплик не контролируется.
+
+
 ==compile==
 
 Включить компиляцию запросов. По умолчанию - 0 (выключено).
@@ -6914,7 +6991,7 @@ dictGetT('dict_name', 'attr_name', id, date)
 
 ==min_count_to_compile==
 
-После скольки раз, когда скомпилированный кусок кода мог пригодиться, выполнить его компиляцию. по умолчанию, 3.
+После скольких раз, когда скомпилированный кусок кода мог пригодиться, выполнить его компиляцию. По умолчанию - 3.
 В случае, если значение равно нулю, то компиляция выполняется синхронно, и запрос будет ждать окончания процесса компиляции перед продолжением выполнения. Это можно использовать для тестирования, иначе используйте значения, начиная с 1. Как правило, компиляция занимает по времени около 5-10 секунд.
 В случае, если значение равно 1 или больше, компиляция выполняется асинхронно, в отдельном потоке. При готовности результата, он сразу же будет использован, в том числе, уже выполняющимися в данный момент запросами.