mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-11-18 05:32:52 +00:00
abae86f7a6
* Doc fix: add spaces where missing
* Doc fixes: rm double spaces
* Doc fixes: edit spaces
* Doc fixes: rm double spaces in /fa
* Revert "Doc fixes: rm double spaces in /fa"
This reverts commit bb879a62ef.
* Doc fix: resolve all problems with double spaces in /fa
* Doc fix: add spaces for readability
* Doc fix: add spaces
* Fix spaces
544 lines
24 KiB
Markdown
544 lines
24 KiB
Markdown
# Прочие функции
|
||
|
||
## hostName()
|
||
Возвращает строку - имя хоста, на котором эта функция была выполнена. При распределённой обработке запроса, это будет имя хоста удалённого сервера, если функция выполняется на удалённом сервере.
|
||
|
||
## visibleWidth(x)
|
||
Вычисляет приблизительную ширину при выводе значения в текстовом (tab-separated) виде на консоль.
|
||
Функция используется системой для реализации Pretty форматов.
|
||
|
||
`NULL` представляется как строка, соответствующая отображению `NULL` в форматах `Pretty`.
|
||
|
||
```
|
||
SELECT visibleWidth(NULL)
|
||
|
||
┌─visibleWidth(NULL)─┐
|
||
│ 4 │
|
||
└────────────────────┘
|
||
```
|
||
|
||
## toTypeName(x)
|
||
Возвращает строку, содержащую имя типа переданного аргумента.
|
||
|
||
Если на вход функции передать `NULL`, то она вернёт тип `Nullable(Nothing)`, что соответствует внутреннему представлению `NULL` в ClickHouse.
|
||
|
||
## blockSize()
|
||
Получить размер блока.
|
||
В ClickHouse выполнение запроса всегда идёт по блокам (наборам кусочков столбцов). Функция позволяет получить размер блока, для которого её вызвали.
|
||
|
||
## materialize(x)
|
||
Превращает константу в полноценный столбец, содержащий только одно значение.
|
||
В ClickHouse полноценные столбцы и константы представлены в памяти по-разному. Функции по-разному работают для аргументов-констант и обычных аргументов (выполняется разный код), хотя результат почти всегда должен быть одинаковым. Эта функция предназначена для отладки такого поведения.
|
||
|
||
## ignore(...)
|
||
Принимает любые аргументы, в т.ч. `NULL`, всегда возвращает 0.
|
||
При этом, аргумент всё равно вычисляется. Это может использоваться для бенчмарков.
|
||
|
||
## sleep(seconds)
|
||
Спит seconds секунд на каждый блок данных. Можно указать как целое число, так и число с плавающей запятой.
|
||
|
||
## currentDatabase()
|
||
Возвращает имя текущей базы данных.
|
||
Эта функция может использоваться в параметрах движка таблицы в запросе CREATE TABLE там, где нужно указать базу данных.
|
||
|
||
## isFinite(x)
|
||
Принимает Float32 или Float64 и возвращает UInt8, равный 1, если аргумент не бесконечный и не NaN, иначе 0.
|
||
|
||
## isInfinite(x)
|
||
Принимает Float32 или Float64 и возвращает UInt8, равный 1, если аргумент бесконечный, иначе 0. Отметим, что в случае NaN возвращается 0.
|
||
|
||
## isNaN(x)
|
||
Принимает Float32 или Float64 и возвращает UInt8, равный 1, если аргумент является NaN, иначе 0.
|
||
|
||
## hasColumnInTable(\['hostname'\[, 'username'\[, 'password'\]\],\] 'database', 'table', 'column')
|
||
Принимает константные строки - имя базы данных, имя таблицы и название столбца. Возвращает константное выражение типа UInt8, равное 1,
|
||
если есть столбец, иначе 0. Если задан параметр hostname, проверка будет выполнена на удалённом сервере.
|
||
Функция кидает исключение, если таблица не существует.
|
||
Для элементов вложенной структуры данных функция проверяет существование столбца. Для самой же вложенной структуры данных функция возвращает 0.
|
||
|
||
## bar
|
||
|
||
Позволяет построить unicode-art диаграмму.
|
||
|
||
`bar(x, min, max, width)` рисует полосу ширины пропорциональной `(x - min)` и равной `width` символов при `x = max`.
|
||
|
||
Параметры:
|
||
|
||
- `x` — Величина для отображения.
|
||
- `min, max` — Целочисленные константы, значение должно помещаться в `Int64`.
|
||
- `width` — Константа, положительное число, может быть дробным.
|
||
|
||
Полоса рисуется с точностью до одной восьмой символа.
|
||
|
||
Пример:
|
||
|
||
``` sql
|
||
SELECT
|
||
toHour(EventTime) AS h,
|
||
count() AS c,
|
||
bar(c, 0, 600000, 20) AS bar
|
||
FROM test.hits
|
||
GROUP BY h
|
||
ORDER BY h ASC
|
||
```
|
||
|
||
```
|
||
┌──h─┬──────c─┬─bar────────────────┐
|
||
│ 0 │ 292907 │ █████████▋ │
|
||
│ 1 │ 180563 │ ██████ │
|
||
│ 2 │ 114861 │ ███▋ │
|
||
│ 3 │ 85069 │ ██▋ │
|
||
│ 4 │ 68543 │ ██▎ │
|
||
│ 5 │ 78116 │ ██▌ │
|
||
│ 6 │ 113474 │ ███▋ │
|
||
│ 7 │ 170678 │ █████▋ │
|
||
│ 8 │ 278380 │ █████████▎ │
|
||
│ 9 │ 391053 │ █████████████ │
|
||
│ 10 │ 457681 │ ███████████████▎ │
|
||
│ 11 │ 493667 │ ████████████████▍ │
|
||
│ 12 │ 509641 │ ████████████████▊ │
|
||
│ 13 │ 522947 │ █████████████████▍ │
|
||
│ 14 │ 539954 │ █████████████████▊ │
|
||
│ 15 │ 528460 │ █████████████████▌ │
|
||
│ 16 │ 539201 │ █████████████████▊ │
|
||
│ 17 │ 523539 │ █████████████████▍ │
|
||
│ 18 │ 506467 │ ████████████████▊ │
|
||
│ 19 │ 520915 │ █████████████████▎ │
|
||
│ 20 │ 521665 │ █████████████████▍ │
|
||
│ 21 │ 542078 │ ██████████████████ │
|
||
│ 22 │ 493642 │ ████████████████▍ │
|
||
│ 23 │ 400397 │ █████████████▎ │
|
||
└────┴────────┴────────────────────┘
|
||
```
|
||
|
||
|
||
## transform
|
||
Преобразовать значение согласно явно указанному отображению одних элементов на другие.
|
||
Имеется два варианта функции:
|
||
|
||
1. `transform(x, array_from, array_to, default)`
|
||
|
||
`x` - что преобразовывать.
|
||
|
||
`array_from` - константный массив значений для преобразования.
|
||
|
||
`array_to` - константный массив значений, в которые должны быть преобразованы значения из from.
|
||
|
||
`default` - какое значение использовать, если x не равен ни одному из значений во from.
|
||
|
||
`array_from` и `array_to` - массивы одинаковых размеров.
|
||
|
||
Типы:
|
||
|
||
`transform(T, Array(T), Array(U), U) -> U`
|
||
|
||
`T` и `U` - могут быть числовыми, строковыми, или Date или DateTime типами.
|
||
При этом, где обозначена одна и та же буква (T или U), могут быть, в случае числовых типов, не совпадающие типы, а типы, для которых есть общий тип.
|
||
Например, первый аргумент может иметь тип Int64, а второй - Array(UInt16).
|
||
|
||
Если значение x равно одному из элементов массива array_from, то возвращает соответствующий (такой же по номеру) элемент массива array_to; иначе возвращает default. Если имеется несколько совпадающих элементов в array_from, то возвращает какой-нибудь из соответствующих.
|
||
|
||
Пример:
|
||
|
||
``` sql
|
||
SELECT
|
||
transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
|
||
count() AS c
|
||
FROM test.hits
|
||
WHERE SearchEngineID != 0
|
||
GROUP BY title
|
||
ORDER BY c DESC
|
||
```
|
||
|
||
```
|
||
┌─title─────┬──────c─┐
|
||
│ Yandex │ 498635 │
|
||
│ Google │ 229872 │
|
||
│ Other │ 104472 │
|
||
└───────────┴────────┘
|
||
```
|
||
|
||
2. `transform(x, array_from, array_to)`
|
||
|
||
Отличается от первого варианта отсутствующим аргументом default.
|
||
Если значение x равно одному из элементов массива array_from, то возвращает соответствующий (такой же по номеру) элемент массива array_to; иначе возвращает x.
|
||
|
||
Типы:
|
||
|
||
`transform(T, Array(T), Array(T)) -> T`
|
||
|
||
Пример:
|
||
|
||
``` sql
|
||
SELECT
|
||
transform(domain(Referer), ['yandex.ru', 'google.ru', 'vk.com'], ['www.yandex', 'example.com']) AS s,
|
||
count() AS c
|
||
FROM test.hits
|
||
GROUP BY domain(Referer)
|
||
ORDER BY count() DESC
|
||
LIMIT 10
|
||
```
|
||
|
||
```
|
||
┌─s──────────────┬───────c─┐
|
||
│ │ 2906259 │
|
||
│ www.yandex │ 867767 │
|
||
│ ███████.ru │ 313599 │
|
||
│ mail.yandex.ru │ 107147 │
|
||
│ ██████.ru │ 100355 │
|
||
│ █████████.ru │ 65040 │
|
||
│ news.yandex.ru │ 64515 │
|
||
│ ██████.net │ 59141 │
|
||
│ example.com │ 57316 │
|
||
└────────────────┴─────────┘
|
||
```
|
||
|
||
## formatReadableSize(x)
|
||
Принимает размер (число байт). Возвращает округленный размер с суффиксом (KiB, MiB и т.д.) в виде строки.
|
||
|
||
Пример:
|
||
|
||
``` sql
|
||
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 и вызывать функцию извне подзапроса, можно будет получить ожидаемый результат.
|
||
|
||
Пример:
|
||
|
||
``` sql
|
||
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 │
|
||
└─────────┴─────────────────────┴───────┘
|
||
```
|
||
|
||
## MACNumToString(num)
|
||
Принимает число типа UInt64. Интерпретирует его, как MAC-адрес в big endian. Возвращает строку, содержащую соответствующий MAC-адрес в формате AA:BB:CC:DD:EE:FF (числа в шестнадцатеричной форме через двоеточие).
|
||
|
||
## MACStringToNum(s)
|
||
Функция, обратная к MACNumToString. Если MAC адрес в неправильном формате, то возвращает 0.
|
||
|
||
## MACStringToOUI(s)
|
||
Принимает MAC адрес в формате AA:BB:CC:DD:EE:FF (числа в шестнадцатеричной форме через двоеточие). Возвращает первые три октета как число в формате UInt64. Если MAC адрес в неправильном формате, то возвращает 0.
|
||
|
||
## getSizeOfEnumType
|
||
|
||
Возвращает количество полей в [Enum](../../data_types/enum.md).
|
||
|
||
```
|
||
getSizeOfEnumType(value)
|
||
```
|
||
|
||
**Параметры**
|
||
|
||
- `value` — Значение типа `Enum`.
|
||
|
||
|
||
**Возвращаемые значения**
|
||
|
||
- Количество полей входного значения типа `Enum`.
|
||
- Исключение, если тип не `Enum`.
|
||
|
||
**Пример**
|
||
|
||
```
|
||
SELECT getSizeOfEnumType( CAST('a' AS Enum8('a' = 1, 'b' = 2) ) ) AS x
|
||
|
||
┌─x─┐
|
||
│ 2 │
|
||
└───┘
|
||
```
|
||
|
||
## toColumnTypeName
|
||
|
||
Возвращает имя класса, которым представлен тип данных столбца в оперативной памяти.
|
||
|
||
```
|
||
toColumnTypeName(value)
|
||
```
|
||
|
||
**Параметры**
|
||
|
||
- `value` — Значение произвольного типа.
|
||
|
||
**Возвращаемые значения**
|
||
|
||
- Строка с именем класса, который используется для представления типа данных `value` в оперативной памяти.
|
||
|
||
**Пример разницы между `toTypeName` и `toColumnTypeName`**
|
||
|
||
```
|
||
:) select toTypeName(cast('2018-01-01 01:02:03' AS DateTime))
|
||
|
||
SELECT toTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))
|
||
|
||
┌─toTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
|
||
│ DateTime │
|
||
└─────────────────────────────────────────────────────┘
|
||
|
||
1 rows in set. Elapsed: 0.008 sec.
|
||
|
||
:) select toColumnTypeName(cast('2018-01-01 01:02:03' AS DateTime))
|
||
|
||
SELECT toColumnTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))
|
||
|
||
┌─toColumnTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
|
||
│ Const(UInt32) │
|
||
└───────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
В примере видно, что тип данных `DateTime` хранится в памяти как `Const(UInt32)`.
|
||
|
||
## dumpColumnStructure
|
||
|
||
Выводит развернутое описание структур данных в оперативной памяти
|
||
|
||
```
|
||
dumpColumnStructure(value)
|
||
```
|
||
|
||
**Параметры**
|
||
|
||
- `value` — Значение произвольного типа.
|
||
|
||
**Возвращаемые значения**
|
||
|
||
- Строка с описанием структуры, которая используется для представления типа данных `value` в оперативной памяти.
|
||
|
||
**Пример**
|
||
|
||
```
|
||
SELECT dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))
|
||
|
||
┌─dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
|
||
│ DateTime, Const(size = 1, UInt32(size = 1)) │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## defaultValueOfArgumentType
|
||
|
||
Выводит значение по умолчанию для типа данных.
|
||
|
||
Не учитывает значения по умолчанию для столбцов, заданные пользователем.
|
||
|
||
```
|
||
defaultValueOfArgumentType(expression)
|
||
```
|
||
|
||
**Параметры**
|
||
|
||
- `expression` — Значение произвольного типа или выражение, результатом которого является значение произвольного типа.
|
||
|
||
**Возвращаемые значения**
|
||
|
||
- `0` для чисел;
|
||
- Пустая строка для строк;
|
||
- `ᴺᵁᴸᴸ` для [Nullable](../../data_types/nullable.md).
|
||
|
||
**Пример**
|
||
|
||
```
|
||
:) SELECT defaultValueOfArgumentType( CAST(1 AS Int8) )
|
||
|
||
SELECT defaultValueOfArgumentType(CAST(1, 'Int8'))
|
||
|
||
┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
|
||
│ 0 │
|
||
└─────────────────────────────────────────────┘
|
||
|
||
1 rows in set. Elapsed: 0.002 sec.
|
||
|
||
:) SELECT defaultValueOfArgumentType( CAST(1 AS Nullable(Int8) ) )
|
||
|
||
SELECT defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))
|
||
|
||
┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
|
||
│ ᴺᵁᴸᴸ │
|
||
└───────────────────────────────────────────────────────┘
|
||
|
||
1 rows in set. Elapsed: 0.002 sec.
|
||
```
|
||
|
||
## indexHint
|
||
|
||
Выводит данные, попавшие в диапазон, выбранный по индексу без фильтрации по указанному в качестве аргумента выражению.
|
||
|
||
Переданное в функцию выражение не вычисляется, но при этом ClickHouse применяет к этому выражению индекс таким же образом, как если бы выражение участвовало в запросе без `indexHint`.
|
||
|
||
|
||
**Возвращаемое значение**
|
||
|
||
- 1.
|
||
|
||
|
||
**Пример**
|
||
|
||
Рассмотрим таблицу с тестовыми данными [ontime](../../getting_started/example_datasets/ontime.md).
|
||
|
||
```
|
||
SELECT count() FROM ontime
|
||
|
||
┌─count()─┐
|
||
│ 4276457 │
|
||
└─────────┘
|
||
```
|
||
|
||
В таблице есть индексы по полям `(FlightDate, (Year, FlightDate))`.
|
||
|
||
Выполним выборку по дате следующим образом:
|
||
|
||
```
|
||
:) SELECT FlightDate AS k, count() FROM ontime GROUP BY k ORDER BY k
|
||
|
||
SELECT
|
||
FlightDate AS k,
|
||
count()
|
||
FROM ontime
|
||
GROUP BY k
|
||
ORDER BY k ASC
|
||
|
||
┌──────────k─┬─count()─┐
|
||
│ 2017-01-01 │ 13970 │
|
||
│ 2017-01-02 │ 15882 │
|
||
........................
|
||
│ 2017-09-28 │ 16411 │
|
||
│ 2017-09-29 │ 16384 │
|
||
│ 2017-09-30 │ 12520 │
|
||
└────────────┴─────────┘
|
||
|
||
273 rows in set. Elapsed: 0.072 sec. Processed 4.28 million rows, 8.55 MB (59.00 million rows/s., 118.01 MB/s.)
|
||
```
|
||
|
||
В этой выборке индекс не используется и ClickHouse обработал всю таблицу (`Processed 4.28 million rows`). Для подключения индекса выберем конкретную дату и выполним следующий запрос:
|
||
|
||
```
|
||
:) SELECT FlightDate AS k, count() FROM ontime WHERE k = '2017-09-15' GROUP BY k ORDER BY k
|
||
|
||
SELECT
|
||
FlightDate AS k,
|
||
count()
|
||
FROM ontime
|
||
WHERE k = '2017-09-15'
|
||
GROUP BY k
|
||
ORDER BY k ASC
|
||
|
||
┌──────────k─┬─count()─┐
|
||
│ 2017-09-15 │ 16428 │
|
||
└────────────┴─────────┘
|
||
|
||
1 rows in set. Elapsed: 0.014 sec. Processed 32.74 thousand rows, 65.49 KB (2.31 million rows/s., 4.63 MB/s.)
|
||
```
|
||
|
||
В последней строке выдачи видно, что благодаря использованию индекса, ClickHouse обработал значительно меньшее количество строк (`Processed 32.74 thousand rows`).
|
||
|
||
|
||
Теперь передадим выражение `k = '2017-09-15'` в функцию `indexHint`:
|
||
|
||
```
|
||
:) SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2017-09-15') GROUP BY k ORDER BY k
|
||
|
||
SELECT
|
||
FlightDate AS k,
|
||
count()
|
||
FROM ontime
|
||
WHERE indexHint(k = '2017-09-15')
|
||
GROUP BY k
|
||
ORDER BY k ASC
|
||
|
||
┌──────────k─┬─count()─┐
|
||
│ 2017-09-14 │ 7071 │
|
||
│ 2017-09-15 │ 16428 │
|
||
│ 2017-09-16 │ 1077 │
|
||
│ 2017-09-30 │ 8167 │
|
||
└────────────┴─────────┘
|
||
|
||
4 rows in set. Elapsed: 0.004 sec. Processed 32.74 thousand rows, 65.49 KB (8.97 million rows/s., 17.94 MB/s.)
|
||
```
|
||
|
||
В ответе на запрос видно, что ClickHouse применил индекс таким же образом, что и в предыдущий раз (`Processed 32.74 thousand rows`). Однако по результирующему набору строк видно, что выражение `k = '2017-09-15'` не использовалось при формировании результата.
|
||
|
||
Поскольку индекс в ClickHouse разреженный, то при чтении диапазона в ответ попадают "лишние" данные, в данном случае соседние даты. Функция `indexHint` позволяет их увидеть.
|
||
|
||
## replicate
|
||
|
||
Создает массив, заполненный одним значением.
|
||
|
||
Используется для внутренней реализации [arrayJoin](array_join.md#functions_arrayjoin).
|
||
|
||
```
|
||
replicate(x, arr)
|
||
```
|
||
|
||
**Параметры**
|
||
|
||
- `arr` — Исходный массив. ClickHouse создаёт новый массив такой же длины как исходный и заполняет его значением `x`.
|
||
- `x` — Значение, которым будет заполнен результирующий массив.
|
||
|
||
**Выходное значение**
|
||
|
||
- Массив, заполненный значением `x`.
|
||
|
||
**Пример**
|
||
|
||
```
|
||
SELECT replicate(1, ['a', 'b', 'c'])
|
||
|
||
┌─replicate(1, ['a', 'b', 'c'])─┐
|
||
│ [1,1,1] │
|
||
└───────────────────────────────┘
|
||
```
|
||
|
||
[Оригинальная статья](https://clickhouse.yandex/docs/ru/query_language/functions/other_functions/) <!--hide-->
|