mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-11-17 13:13:36 +00:00

Alexey Milovidov d87d833691 Remove trailing whitespaces from docs

2021-07-29 18:20:55 +03:00

29 KiB

Raw Blame History

toc_priority	toc_title
40	Функции для работы со строками

Функции для работы со строками

empty

Возвращает 1 для пустой строки, и 0 для непустой строки. Тип результата — UInt8. Строка считается непустой, если содержит хотя бы один байт, пусть даже это пробел или нулевой байт. Функция также работает для массивов.

notEmpty

Возвращает 0 для пустой строки, и 1 для непустой строки. Тип результата — UInt8. Функция также работает для массивов.

length

Возвращает длину строки в байтах (не символах, не кодовых точках). Тип результата — UInt64. Функция также работает для массивов.

lengthUTF8

Возвращает длину строки в кодовых точках Unicode (не символах), при допущении, что строка содержит набор байтов, являющийся текстом в кодировке UTF-8. Если допущение не выполнено, то возвращает какой-нибудь результат (не кидает исключение). Тип результата — UInt64.

char_length, CHAR_LENGTH

Возвращает длину строки в кодовых точках Unicode (не символах), при допущении, что строка содержит набор байтов, являющийся текстом в кодировке UTF-8. Если допущение не выполнено, возвращает какой-нибудь результат (не кидает исключение). Тип результата — UInt64.

character_length, CHARACTER_LENGTH

Возвращает длину строки в кодовых точках Unicode (не символах), при допущении, что строка содержит набор байтов, являющийся текстом в кодировке UTF-8. Если допущение не выполнено, возвращает какой-нибудь результат (не кидает исключение). Тип результата — UInt64.

lower, lcase

Переводит ASCII-символы латиницы в строке в нижний регистр.

upper, ucase

Переводит ASCII-символы латиницы в строке в верхний регистр.

lowerUTF8

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

upperUTF8

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

isValidUTF8

Возвращает 1, если набор байтов является корректным в кодировке UTF-8, 0 иначе.

toValidUTF8

Заменяет некорректные символы UTF-8 на символ <EFBFBD> (U+FFFD). Все идущие подряд некорректные символы схлопываются в один заменяющий символ.

toValidUTF8(input_string)

Аргументы

input_string — произвольный набор байтов, представленный как объект типа String.

Возвращаемое значение: Корректная строка UTF-8.

Пример

SELECT toValidUTF8('\x61\xF0\x80\x80\x80b');

┌─toValidUTF8('a<><61><EFBFBD><EFBFBD>b')─┐
│ a<>b                   │
└───────────────────────┘

repeat

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

Синоним: REPEAT.

Синтаксис

repeat(s, n)

Аргументы

s — строка для повторения. String.
n — количество повторов. UInt.

Возвращаемое значение

Строка, состоящая из повторений n раз исходной строки s. Если n < 1, то функция вернет пустую строку.

Тип: String.

Пример

Запрос:

SELECT repeat('abc', 10);

Результат:

┌─repeat('abc', 10)──────────────┐
│ abcabcabcabcabcabcabcabcabcabc │
└────────────────────────────────┘

reverse

Разворачивает строку (как последовательность байтов).

reverseUTF8

Разворачивает последовательность кодовых точек Unicode, при допущении, что строка содержит набор байтов, представляющий текст в кодировке UTF-8. Иначе — что-то делает (не кидает исключение).

format(pattern, s0, s1, …)

Форматирует константный шаблон со строками, перечисленными в аргументах. pattern — упрощенная версия шаблона в языке Python. Шаблон содержит «заменяющие поля», которые окружены фигурными скобками {}. Всё, что не содержится в скобках, интерпретируется как обычный текст и просто копируется. Если нужно использовать символ фигурной скобки, можно экранировать двойной скобкой {{ '{{' }} или {{ '}}' }}. Имя полей могут быть числами (нумерация с нуля) или пустыми (тогда они интерпретируются как последовательные числа).

SELECT format('{1} {0} {1}', 'World', 'Hello')

┌─format('{1} {0} {1}', 'World', 'Hello')─┐
│ Hello World Hello                       │
└─────────────────────────────────────────┘

SELECT format('{} {}', 'Hello', 'World')

┌─format('{} {}', 'Hello', 'World')─┐
│ Hello World                       │
└───────────────────────────────────┘

concat

Склеивает строки, переданные в аргументы, в одну строку без разделителей.

Cинтаксис

concat(s1, s2, ...)

Аргументы

Значения типа String или FixedString.

Возвращаемое значение

Возвращает строку, полученную в результате склейки аргументов.

Если любой из аргументов имеет значение NULL, concat возвращает значение NULL.

Пример

Запрос:

SELECT concat('Hello, ', 'World!');

Результат:

┌─concat('Hello, ', 'World!')─┐
│ Hello, World!               │
└─────────────────────────────┘

concatAssumeInjective

Аналогична concat. Разница заключается в том, что вам нужно убедиться, что concat(s1, s2, ...) → sn является инъективным, так как это предположение будет использоваться для оптимизации GROUP BY.

Функция называется «инъективной», если она возвращает разные значения для разных аргументов. Или, иными словами, функция никогда не выдаёт одно и то же значение, если аргументы разные.

Синтаксис

concatAssumeInjective(s1, s2, ...)

Аргументы

Значения типа String или FixedString.

Возвращаемые значения

Возвращает строку, полученную в результате объединения аргументов.

Если любой из аргументов имеет значение NULL, concatAssumeInjective возвращает значение NULL.

Пример

Вводная таблица:

CREATE TABLE key_val(`key1` String, `key2` String, `value` UInt32) ENGINE = TinyLog
INSERT INTO key_val VALUES ('Hello, ','World',1)('Hello, ','World',2)('Hello, ','World!',3)('Hello',', World!',2)
SELECT * from key_val

┌─key1────┬─key2─────┬─value─┐
│ Hello,  │ World    │     1 │
│ Hello,  │ World    │     2 │
│ Hello,  │ World!   │     3 │
│ Hello   │ , World! │     2 │
└─────────┴──────────┴───────┘

Запрос:

SELECT concat(key1, key2), sum(value) FROM key_val GROUP BY (key1, key2);

Результат:

┌─concat(key1, key2)─┬─sum(value)─┐
│ Hello, World!      │          3 │
│ Hello, World!      │          2 │
│ Hello, World       │          3 │
└────────────────────┴────────────┘

substring(s, offset, length), mid(s, offset, length), substr(s, offset, length)

Возвращает подстроку, начиная с байта по индексу offset, длины length байт. Индексация символов — начиная с единицы (как в стандартном SQL). Аргументы offset и length должны быть константами.

substringUTF8(s, offset, length)

Так же, как substring, но для кодовых точек Unicode. Работает при допущении, что строка содержит набор байтов, представляющий текст в кодировке UTF-8. Если допущение не выполнено, то возвращает какой-нибудь результат (не кидает исключение).

appendTrailingCharIfAbsent(s, c)

Если строка s непустая и не содержит символ c на конце, то добавляет символ c в конец.

convertCharset(s, from, to)

Возвращает сконвертированную из кодировки from в кодировку to строку s.

base64Encode(s)

Производит кодирование строки s в base64-представление.

Синоним: TO_BASE64.

base64Decode(s)

Декодирует base64-представление s в исходную строку. При невозможности декодирования выбрасывает исключение

Синоним: FROM_BASE64.

tryBase64Decode(s)

Функционал аналогичен base64Decode, но при невозможности декодирования возвращает пустую строку.

endsWith(s, suffix)

Возвращает 1, если строка завершается указанным суффиксом, и 0 в противном случае.

startsWith(str, prefix)

Возвращает 1, если строка начинается указанным префиксом, в противном случае 0.

SELECT startsWith('Spider-Man', 'Spi');

Возвращаемые значения

1, если строка начинается указанным префиксом.
0, если строка не начинается указанным префиксом.

Пример

Запрос:

SELECT startsWith('Hello, world!', 'He');

Результат:

┌─startsWith('Hello, world!', 'He')─┐
│                                 1 │
└───────────────────────────────────┘

trim

Удаляет все указанные символы с начала или окончания строки. По умолчанию удаляет все последовательные вхождения обычных пробелов (32 символ ASCII) с обоих концов строки.

Синтаксис

trim([[LEADING|TRAILING|BOTH] trim_character FROM] input_string)

Аргументы

trim_character — один или несколько символов, подлежащие удалению. String.
input_string — строка для обрезки. String.

Возвращаемое значение

Исходную строку после обрезки с левого и (или) правого концов строки.

Тип: String.

Пример

Запрос:

SELECT trim(BOTH ' ()' FROM '(   Hello, world!   )');

Результат:

┌─trim(BOTH ' ()' FROM '(   Hello, world!   )')─┐
│ Hello, world!                                 │
└───────────────────────────────────────────────┘

trimLeft

Удаляет все последовательные вхождения обычных пробелов (32 символ ASCII) с левого конца строки. Не удаляет другие виды пробелов (табуляция, пробел без разрыва и т. д.).

Синтаксис

trimLeft(input_string)

Алиас: ltrim(input_string).

Аргументы

input_string — строка для обрезки. String.

Возвращаемое значение

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

Тип: String.

Пример

Запрос:

SELECT trimLeft('     Hello, world!     ');

Результат:

┌─trimLeft('     Hello, world!     ')─┐
│ Hello, world!                       │
└─────────────────────────────────────┘

trimRight

Удаляет все последовательные вхождения обычных пробелов (32 символ ASCII) с правого конца строки. Не удаляет другие виды пробелов (табуляция, пробел без разрыва и т. д.).

Синтаксис

trimRight(input_string)

Алиас: rtrim(input_string).

Аргументы

input_string — строка для обрезки. String.

Возвращаемое значение

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

Тип: String.

Пример

Запрос:

SELECT trimRight('     Hello, world!     ');

Результат:

┌─trimRight('     Hello, world!     ')─┐
│      Hello, world!                   │
└──────────────────────────────────────┘

trimBoth

Удаляет все последовательные вхождения обычных пробелов (32 символ ASCII) с обоих концов строки. Не удаляет другие виды пробелов (табуляция, пробел без разрыва и т. д.).

Синтаксис

trimBoth(input_string)

Алиас: trim(input_string).

Аргументы

input_string — строка для обрезки. String.

Возвращаемое значение

Исходную строку без общих пробельных символов с обоих концов строки.

Тип: String.

Пример

Запрос:

SELECT trimBoth('     Hello, world!     ');

Результат:

┌─trimBoth('     Hello, world!     ')─┐
│ Hello, world!                       │
└─────────────────────────────────────┘

CRC32(s)

Возвращает чексумму CRC32 данной строки, используется CRC-32-IEEE 802.3 многочлен и начальным значением 0xffffffff (т.к. используется реализация из zlib).

Тип результата — UInt32.

CRC32IEEE(s)

Возвращает чексумму CRC32 данной строки, используется CRC-32-IEEE 802.3 многочлен.

Тип результата — UInt32.

CRC64(s)

Возвращает чексумму CRC64 данной строки, используется CRC-64-ECMA многочлен.

Тип результата — UInt64.

normalizeQuery

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

Синтаксис

normalizeQuery(x)

Аргументы

x — последовательность символов. String.

Возвращаемое значение

Последовательность символов с заполнителями.

Тип: String.

Пример

Запрос:

SELECT normalizeQuery('[1, 2, 3, x]') AS query;

Результат:

┌─query────┐
│ [?.., x] │
└──────────┘

normalizedQueryHash

Возвращает идентичные 64-битные хэш - суммы без значений литералов для аналогичных запросов. Это помогает анализировать журнал запросов.

Синтаксис

normalizedQueryHash(x)

Аргументы

x — последовательность символов. String.

Возвращаемое значение

Хэш-сумма.

Тип: UInt64.

Пример

Запрос:

SELECT normalizedQueryHash('SELECT 1 AS `xyz`') != normalizedQueryHash('SELECT 1 AS `abc`') AS res;

Результат:

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

encodeXMLComponent

Экранирует символы для размещения строки в текстовом узле или атрибуте XML.

Экранируются символы, которые в формате XML являются зарезервированными (служебными): <, &, >, ", '.

Синтаксис

encodeXMLComponent(x)

Аргументы

x — последовательность символов. String.

Возвращаемое значение

Строка, в которой зарезервированные символы экранированы.

Тип: String.

Пример

Запрос:

SELECT encodeXMLComponent('Hello, "world"!');
SELECT encodeXMLComponent('<123>');
SELECT encodeXMLComponent('&clickhouse');
SELECT encodeXMLComponent('\'foo\'');

Результат:

Hello, &quot;world&quot;!
&lt;123&gt;
&amp;clickhouse
&apos;foo&apos;

decodeXMLComponent

Заменяет символами предопределенные мнемоники XML: " & ' > < Также эта функция заменяет числовые ссылки соответствующими символами юникод. Поддерживаются десятичная (например, ✓) и шестнадцатеричная (✓) формы.

Синтаксис

decodeXMLComponent(x)

Аргументы

x — последовательность символов. String.

Возвращаемое значение

Строка с произведенными заменами.

Тип: String.

Пример

Запрос:

SELECT decodeXMLComponent('&apos;foo&apos;');
SELECT decodeXMLComponent('&lt; &#x3A3; &gt;');

Результат:

'foo'
< Σ >

Смотрите также

Мнемоники в HTML

extractTextFromHTML

Функция для извлечения текста из HTML или XHTML. Она не соответствует всем HTML, XML или XHTML стандартам на 100%, но ее реализация достаточно точная и быстрая. Правила обработки следующие:

Комментарии удаляются. Пример: . Комментарий должен оканчиваться символами -->. Вложенные комментарии недопустимы. Примечание: конструкции наподобие  не являются допустимыми комментариями в HTML, но они будут удалены согласно другим правилам.
Содержимое CDATA вставляется дословно. Примечание: формат CDATA специфичен для XML/XHTML. Но он обрабатывается всегда по принципу "наилучшего возможного результата".
Элементы script и style удаляются вместе со всем содержимым. Примечание: предполагается, что закрывающий тег не может появиться внутри содержимого. Например, в JS строковый литерал должен быть экранирован как "<\/script>". Примечание: комментарии и CDATA возможны внутри script или style - тогда закрывающие теги не ищутся внутри CDATA. Пример: <script><![CDATA[</script>]]></script>. Но они ищутся внутри комментариев. Иногда возникают сложные случаи: <script>var x = ""; alert(x + y);</script> Примечание: script и style могут быть названиями пространств имен XML - тогда они не обрабатываются как обычные элементы script или style. Пример: <script:a>Hello</script:a>. Примечание: пробелы возможны после имени закрывающего тега: </script >, но не перед ним: < / script>.
Другие теги или элементы, подобные тегам, удаляются, а их внутреннее содержимое остается. Пример: <a>.</a> Примечание: ожидается, что такой HTML является недопустимым: <a test=">"></a> Примечание: функция также удаляет подобные тегам элементы: <>, <!>, и т. д. Примечание: если встречается тег без завершающего символа >, то удаляется этот тег и весь следующий за ним текст: <hello
Мнемоники HTML и XML не декодируются. Они должны быть обработаны отдельной функцией.
Пробелы в тексте удаляются и добавляются по следующим правилам:

Пробелы в начале и в конце извлеченного текста удаляются.
Несколько пробелов подряд заменяются одним пробелом.
Если текст разделен другими удаляемыми элементами и в этом месте нет пробела, он добавляется.
Это может привести к появлению неестественного написания, например: Hello<b>world</b>, Helloworld — в HTML нет пробелов, но функция вставляет их. Также следует учитывать такие варианты написания: Hello<p>world</p>, Hello<br>world. Подобные результаты выполнения функции могут использоваться для анализа данных, например, для преобразования HTML-текста в набор используемых слов.

Также обратите внимание, что правильная обработка пробелов требует поддержки <pre></pre> и свойств CSS display и white-space.

Синтаксис

extractTextFromHTML(x)

Аргументы

x — текст для обработки. String.

Возвращаемое значение

Извлеченный текст.

Тип: String.

Пример

Первый пример содержит несколько тегов и комментарий. На этом примере также видно, как обрабатываются пробелы. Второй пример показывает обработку CDATA и тега script. В третьем примере текст выделяется из полного HTML ответа, полученного с помощью функции url.

Запрос:

SELECT extractTextFromHTML(' <p> A text <i>with</i><b>tags</b>. <!-- comments --> </p> ');
SELECT extractTextFromHTML('<![CDATA[The content within <b>CDATA</b>]]> <script>alert("Script");</script>');
SELECT extractTextFromHTML(html) FROM url('http://www.donothingfor2minutes.com/', RawBLOB, 'html String');

Результат:

A text with tags .
The content within <b>CDATA</b>
Do Nothing for 2 Minutes 2:00 &nbsp;

29 KiB Raw Blame History Unescape Escape

Функции для работы со строками

empty

notEmpty

length

lengthUTF8

char_length, CHAR_LENGTH

character_length, CHARACTER_LENGTH

lower, lcase

upper, ucase

lowerUTF8

upperUTF8

isValidUTF8

toValidUTF8

repeat

reverse

reverseUTF8

format(pattern, s0, s1, …)

concat

concatAssumeInjective

substring(s, offset, length), mid(s, offset, length), substr(s, offset, length)

substringUTF8(s, offset, length)

appendTrailingCharIfAbsent(s, c)

convertCharset(s, from, to)

base64Encode(s)

base64Decode(s)

tryBase64Decode(s)

endsWith(s, suffix)

startsWith(str, prefix)

trim

trimLeft

trimRight

trimBoth

CRC32(s)

CRC32IEEE(s)

CRC64(s)

normalizeQuery

normalizedQueryHash

encodeXMLComponent

decodeXMLComponent

extractTextFromHTML

29 KiB

Raw Blame History