ClickHouse/docs/ru/functions/other_functions.rst

Прочие функции
--------------

hostName()
~~~~~~~~~~
Возвращает строку - имя хоста, на котором эта функция была выполнена. При распределённой обработке запроса, это будет имя хоста удалённого сервера, если функция выполняется на удалённом сервере.

visibleWidth(x)
~~~~~~~~~~~~~~~
Вычисляет приблизительную ширину при выводе значения в текстовом (tab-separated) виде на консоль.
Функция используется системой для реализации Pretty форматов.

toTypeName(x)
~~~~~~~~~~~~~
Возвращает строку, содержащую имя типа переданного аргумента.

blockSize()
~~~~~~~~~~~
Получить размер блока.
В ClickHouse выполнение запроса всегда идёт по блокам (наборам кусочков столбцов). Функция позволяет получить размер блока, для которого её вызвали.

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

ignore(...)
~~~~~~~~~~~
Принимает любые аргументы, всегда возвращает 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.
``min, max`` - целочисленные константы, значение должно помещаться в Int64.
``width`` - константа, положительное число, может быть дробным.

Полоса рисуется с точностью до одной восьмой символа.

Пример:

.. code-block:: 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

.. code-block:: text
  
  ┌──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, то возвращает какой-нибудь из соответствующих.

Пример:

.. code-block:: sql
  
  SELECT
      transform(SearchEngineID, [2, 3], ['Яндекс', 'Google'], 'Остальные') AS title,
      count() AS c
  FROM test.hits
  WHERE SearchEngineID != 0
  GROUP BY title
  ORDER BY c DESC

.. code-block:: text

  ┌─title─────┬──────c─┐
  │ Яндекс    │ 498635 │
  │ Google    │ 229872 │
  │ Остальные │ 104472 │
  └───────────┴────────┘


2. ``transform(x, array_from, array_to)``
  
Отличается от первого варианта отсутствующим аргументом default.
Если значение x равно одному из элементов массива array_from, то возвращает соответствующий (такой же по номеру) элемент массива array_to; иначе возвращает x.

Типы:

``transform(T, Array(T), Array(T)) -> T``

Пример:

.. code-block:: 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

.. code-block:: text
  
  ┌─s──────────────┬───────c─┐
  │                │ 2906259 │
  │ www.yandex     │  867767 │
  │ ███████.ru     │  313599 │
  │ mail.yandex.ru │  107147 │
  │ ввв.яндекс.рф  │  105668 │
  │ ██████.ru      │  100355 │
  │ █████████.ru   │   65040 │
  │ news.yandex.ru │   64515 │
  │ ██████.net     │   59141 │
  │ example.com    │   57316 │
  └────────────────┴─────────┘

formatReadableSize(x)
~~~~~~~~~~~~~~~~~~~~~
Принимает размер (число байт). Возвращает округленный размер с суффиксом (KiB, MiB и т.д.) в виде строки.

Пример:

.. code-block:: sql

  SELECT
      arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
      formatReadableSize(filesize_bytes) AS filesize

.. code-block:: text
  
  ┌─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 и вызывать функцию извне подзапроса, можно будет получить ожидаемый результат.

Пример:

.. code-block:: 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
  )

.. code-block:: text
  
  ┌─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.