Типы JSON-функций
Существует два набора функций для разбора JSON:simpleJSON*(visitParam*) — для чрезвычайно быстрого разбора ограниченного подмножества JSON.JSONExtract*— для разбора обычного JSON.
Функции simpleJSON (visitParam)
В ClickHouse есть специальные функции для работы с упрощённым JSON. Все эти JSON-функции основаны на строгих допущениях относительно того, каким может быть JSON. Они стараются делать как можно меньше, чтобы выполнить задачу как можно быстрее. Предполагается следующее:- Имя поля (аргумент функции) должно быть константой.
- Имя поля в JSON должно быть закодировано в канонической форме. Например:
simpleJSONHas('{"abc":"def"}', 'abc') = 1, ноsimpleJSONHas('{"\\u0061\\u0062\\u0063":"def"}', 'abc') = 0 - Поля ищутся на любом уровне вложенности без учёта контекста. Если есть несколько совпадающих полей, используется первое вхождение.
- В JSON не должно быть пробельных символов вне строковых литералов.
Функции JSONExtract
Эти функции основаны на simdjson и предназначены для более сложных сценариев парсинга JSON.Регистронезависимые функции JSONExtract
Эти функции выполняют регистронезависимое сопоставление ASCII-ключей при извлечении значений из объектов JSON. Они работают так же, как и их регистрозависимые аналоги, за исключением того, что ключи объектов сопоставляются без учета регистра. Если нескольким ключам с разным регистром соответствует совпадение, возвращается первое из них.Эти функции могут работать медленнее, чем их регистрозависимые аналоги, поэтому по возможности используйте обычные функции JSONExtract.
Синтаксис JSONPath
ФункцииJSON_EXISTS, JSON_VALUE и JSON_QUERY принимают выражение JSONPath
в качестве второго аргумента. ClickHouse реализует небольшое подмножество
JSONPath, в общих чертах основанное на стандарте SQL/JSON (ISO/IEC TR 19075-6)
и намеренно более ограниченное, чем RFC 9535
и другие популярные реализации. Поддерживаемые операторы перечислены ниже.
Эталонная реализация находится в
src/Functions/JSONPath/Parsers.
Поддерживаемые операторы
Примечания:
- Индексы и диапазоны можно комбинировать в одной паре скобок (например,
[0 to 2, 4]). - Диапазоны индексов и подстановочный знак нельзя комбинировать в одной паре скобок (например,
[* , 0]недопустимо). - В диапазоне
[n to m]начальный индексnдолжен быть строго меньше конечного индексаm, иначе возникает исключение. - Одиночный индекс
[n]эквивалентен диапазону[n to n+1].
Неподдерживаемые операторы
Следующие операторы JSONPath, доступные в RFC 9535 или других реализациях, не поддерживаются ClickHouse:JSONAllPaths
Добавленный в: v24.8.0 Возвращает список всех путей, хранящихся в каждой строке JSON-столбца. Синтаксисjson— JSON-столбец.JSON
Array(String)
Примеры
Пример использования
Query
Response
JSONAllPathsWithTypes
Добавленный в: v24.8.0 Возвращает список всех путей и соответствующих им типов данных, хранящихся в каждой строке JSON-столбца. Синтаксисjson— JSON-столбец.JSON
Map(String, String)
Примеры
Пример использования
Query
Response
JSONAllValues
Добавленный в: v26.4.0 Возвращает все значения из каждой строки JSON-столбца в виде массива строк. Значения сериализуются в текстовом представлении и упорядочиваются по именам путей. Синтаксисjson— JSON-столбец.JSON
Array(String)
Примеры
Пример использования
Query
Response
JSONArrayLength
Добавленный в: v23.2.0 Возвращает количество элементов в JSON-массиве верхнего уровня. Функция возвращаетNULL, если входная JSON-строка недействительна.
Синтаксис
JSON_ARRAY_LENGTH
Аргументы
json— строкаStringс корректным JSON.String
json является строкой с корректным JSON-массивом; в противном случае возвращает NULL. Nullable(UInt64)
Примеры
Пример использования
Query
Response
JSONDynamicPaths
Добавленный в: v24.8.0 Возвращает список динамических путей, хранящихся в JSON-столбце как отдельные подстолбцы. Синтаксисjson— JSON-столбец.JSON
Array(String)
Примеры
Пример использования
Query
Response
JSONDynamicPathsWithTypes
Добавленный в: v24.8.0 Возвращает список динамических путей, которые хранятся как отдельные подстолбцы, и их типы для каждой строки в JSON-столбце. Синтаксисjson— JSON-столбец.JSON
Map(String, String)
Примеры
Пример использования
Query
Response
JSONExtract
Добавленный в: v19.14.0 Разбирает JSON и извлекает значение указанного типа данных ClickHouse. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.Stringили(U)Int*return_type— Тип данных ClickHouse, который нужно вернуть.String
Query
Response
JSONExtractArrayRaw
Добавленный в: v20.1.0 Возвращает массив, содержащий элементы JSON-массива, каждый из которых представлен в виде неразобранной строки. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом.Stringили(U)Int*
Array(String)
Примеры
Пример использования
Query
Response
JSONExtractArrayRawCaseInsensitive
Добавленный в: v25.8.0 Возвращает массив из элементов JSON-массива, каждый из которых представлен как неразобранная строка, с использованием регистронезависимого сопоставления ключей. Эта функция аналогичнаJSONExtractArrayRaw.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к массиву. Для ключей используется регистронезависимое сравнениеStringили(U)Int*
Array(String)
Примеры
базовый
Query
Response
JSONExtractBool
Добавленный в: v20.1.0 Разбирает JSON и извлекает значение типа Bool. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.Stringили(U)Int*
0. Bool
Примеры
Пример использования
Query
Response
JSONExtractBoolCaseInsensitive
Добавленный в: v25.8.0 Разбирает JSON и извлекает булево значение, используя регистронезависимое сопоставление ключей. Эта функция похожа наJSONExtractBool.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к полю. Для ключей используется регистронезависимое сопоставлениеStringили(U)Int*
UInt8
Примеры
базовый
Query
Response
JSONExtractCaseInsensitive
Добавленный в: v25.8.0 Разбирает JSON и извлекает значение указанного типа данных ClickHouse с помощью регистронезависимого сопоставления ключей. Эта функция похожа наJSONExtract.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к полю. Для ключей используется регистронезависимое сопоставлениеStringили(U)Int*return_type— Тип данных ClickHouse, который нужно извлечьString
Any
Примеры
int_type
Query
Response
Query
Response
JSONExtractFloat
Добавленный в: v20.1.0 Разбирает JSON и извлекает значение типа Float. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.Stringили(U)Int*
0. Float64
Примеры
Пример использования
Query
Response
JSONExtractFloatCaseInsensitive
Добавленный в: v25.8.0 Разбирает JSON и извлекает значение типа Float, используя регистронезависимое сопоставление ключей. Эта функция аналогичнаJSONExtractFloat.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к полю. Для ключей используется регистронезависимое сопоставлениеStringили(U)Int*
Float64
Примеры
базовый
Query
Response
JSONExtractInt
Добавленный в: v20.1.0 Разбирает JSON и извлекает значение типа Int. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.Stringили(U)Int*
0. Int64
Примеры
Пример использования
Query
Response
JSONExtractIntCaseInsensitive
Добавленный в: v25.8.0 Разбирает JSON и извлекает значение типа Int с регистронезависимым сопоставлением ключей. Эта функция аналогичнаJSONExtractInt.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к полю. Для ключей используется регистронезависимое сравнениеStringили(U)Int*
0, если значение не найдено или его нельзя преобразовать. Int64
Примеры
базовый пример
Query
Response
Query
Response
JSONExtractKeys
Добавленный в: v21.11.0 Разбирает строку JSON и извлекает из неё ключи. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом.Stringили(U)Int*
Array(String)
Примеры
Пример использования
Query
Response
JSONExtractKeysAndValues
Добавленный в: v20.1.0 Разбирает пары ключ-значение из JSON, где значения имеют указанный тип данных ClickHouse. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом.Stringили(U)Int*value_type— Тип данных ClickHouse для значений.String
Array(Tuple(String, value_type))
Примеры
Пример использования
Query
Response
JSONExtractKeysAndValuesCaseInsensitive
Добавленный в: v25.8.0 Разбирает пары «ключ-значение» из JSON, используя регистронезависимое сопоставление ключей. Эта функция похожа наJSONExtractKeysAndValues.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к объекту. Ключи сопоставляются без учета регистраStringили(U)Int*value_type— Тип данных ClickHouse для значенийString
Array(Tuple(String, T))
Примеры
базовый
Query
Response
JSONExtractKeysAndValuesRaw
Добавленный в: v20.4.0 Возвращает массив Tuple с ключами и значениями из объекта JSON. Все значения представлены в виде необработанных строк. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом.Stringили(U)Int*
Array(Tuple(String, String))
Примеры
Пример использования
Query
Response
JSONExtractKeysAndValuesRawCaseInsensitive
Добавленный в: v25.8.0 Извлекает из JSON необработанные пары ключ-значение с регистронезависимым сопоставлением ключей. Эта функция похожа наJSONExtractKeysAndValuesRaw.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к объекту. Для ключей используется регистронезависимое сравнениеStringили(U)Int*
Array(Tuple(String, String))
Примеры
простой
Query
Response
JSONExtractKeysCaseInsensitive
Добавленный в: v25.8.0 Разбирает строку JSON и извлекает ключи, используя регистронезависимое сопоставление ключей для перехода к вложенным объектам. Эта функция похожа наJSONExtractKeys.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к объекту. Ключи используют регистронезависимое сопоставление ключейStringили(U)Int*
Array(String)
Примеры
базовый
Query
Response
Query
Response
JSONExtractRaw
Добавленный в: v20.1.0 Возвращает часть JSON как неразобранную строку. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.Stringили(U)Int*
String
Примеры
Пример использования
Query
Response
JSONExtractRawCaseInsensitive
Добавленный в: v25.8.0 Возвращает часть JSON в виде неразобранной строки, используя регистронезависимое сопоставление ключей. Эта функция похожа наJSONExtractRaw.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к полю. Для ключей используется регистронезависимое сопоставлениеStringили(U)Int*
String
Примеры
объект
Query
Response
JSONExtractString
Добавленный в: v20.1.0 Разбирает JSON и извлекает значение типа String. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.Stringили(U)Int*
String
Примеры
Пример использования
Query
Response
JSONExtractStringCaseInsensitive
Добавленный в: v25.8.0 Разбирает JSON и извлекает строку, используя регистронезависимое сопоставление ключей. Эта функция похожа наJSONExtractString.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к нужному полю. Для ключей используется регистронезависимое сопоставлениеStringили(U)Int*
String
Примеры
базовый
Query
Response
Query
Response
JSONExtractUInt
Добавленный в: v20.1.0 Разбирает JSON и извлекает значение типа UInt. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Список из нуля, одного или нескольких аргументов, каждый из которых может быть строкой или целым числом.Stringили(U)Int*
0. UInt64
Примеры
Пример использования
Query
Response
JSONExtractUIntCaseInsensitive
Добавленный в: v25.8.0 Разбирает JSON и извлекает значение типа UInt, используя регистронезависимое сопоставление ключей. Эта функция похожа наJSONExtractUInt.
Синтаксис
json— JSON-строка для разбораStringindices_or_keys— Необязательно. Индексы или ключи для перехода к полю. Ключи используют регистронезависимое сопоставлениеStringили(U)Int*
0, если значение не найдено или его невозможно преобразовать. UInt64
Примеры
базовый
Query
Response
JSONHas
Добавленный в: v20.1.0 Проверяет наличие указанных значений в JSON-документе. Синтаксисjson— JSON-строка для разбораString[ ,indices_or_keys, ...]— Список из нуля или более аргументов.Stringили(U)Int*
1, если значение присутствует в json, в противном случае — 0 UInt8
Примеры
Пример использования
Query
Response
JSONKey
Добавленный в: v20.1.0 Возвращает ключ поля объекта JSON по его индексу (начиная с 1). Если JSON передан в виде строки, сначала он разбирается. Второй аргумент — путь JSON для перехода к вложенным объектам. Функция возвращает имя ключа в указанной позиции. Синтаксисjson— JSON-строка для разбора.Stringindices_or_keys— Необязательный список индексов или ключей, указывающий путь к вложенному элементу. Каждый argument может быть либо строкой (доступ по ключу), либо целым числом (доступ по индексу, начиная с 1).StringилиInt*
String
Примеры
Пример использования
Query
Response
JSONLength
Добавленный в: v20.1.0 Возвращает длину JSON-массива или объекта JSON. Если значение отсутствует или имеет неверный тип, возвращается0.
Синтаксис
json— JSON-строка для разбораString[, indices_or_keys, ...]— Необязательно. Список из нуля или более аргументов.Stringили(U)Int8/16/32/64
0, если значение отсутствует или имеет неверный тип. UInt64
Примеры
Пример использования
Query
Response
JSONMergePatch
Добавленный в: v23.10.0 Возвращает строку объекта JSON, полученного путём слияния нескольких объектов JSON. СинтаксисjsonMergePatch
Аргументы
json1[, json2, ...]— Одна или несколько строк с корректным JSON.String
String
Примеры
Пример использования
Query
Response
JSONSharedDataPaths
Добавленный в: v24.8.0 Возвращает список путей, хранящихся в общей структуре данных JSON-столбца. Синтаксисjson— JSON-столбец.JSON
Array(String)
Примеры
Пример использования
Query
Response
JSONSharedDataPathsWithTypes
Добавленный в: v24.8.0 Возвращает список путей, хранящихся в общей структуре данных, и их типы для каждой строки в JSON-столбце. Синтаксисjson— JSON-столбец.JSON
Map(String, String)
Примеры
Пример использования
Query
Response
JSONType
Добавленный в: v20.1.0 Возвращает тип значения JSON. Если значение отсутствует, возвращаетсяNull=0.
Синтаксис
json— JSON-строка для разбораStringjson[, indices_or_keys, ...]— Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом.Stringили(U)Int8/16/32/64
Null=0 Enum
Примеры
Пример использования
Query
Response
JSON_EXISTS
Добавленный в: v21.8.0 Если значение существует в JSON-документе, возвращается1.
Если значение не существует, возвращается 0.
Синтаксис
1, если значение существует в JSON-документе, иначе — 0. UInt8
Примеры
Пример использования
Query
Response
JSON_QUERY
Добавленный в: v21.8.0 Разбирает JSON и извлекает значение в виде JSON-массива или объекта JSON. Если значение отсутствует, возвращается пустая строка. СинтаксисString
Примеры
Пример использования
Query
Response
JSON_VALUE
Добавленный в: v21.11.0 Разбирает JSON и извлекает значение в виде JSON-скаляра. Если значение не существует, по умолчанию возвращается пустая строка. Поведение этой функции определяется следующими настройками:- при SET
function_json_value_return_type_allow_nullable=trueвозвращаетсяNULL. Если значение имеет сложный тип (например: struct, array, map), по умолчанию возвращается пустая строка. - при SET
function_json_value_return_type_allow_complex=trueвозвращается сложное значение.
String
Примеры
Пример использования
Query
Response
dynamicElement
Добавленный в: v24.1.0 Извлекает столбец с указанным типом из столбца типаDynamic.
Эта функция позволяет извлекать значения определённого типа из столбца типа Dynamic. Если строка содержит значение
запрошенного типа, функция возвращает это значение. Если строка содержит значение другого типа или NULL, она возвращает NULL
для скалярных типов или пустой массив для типов Array.
Синтаксис
dynamic— столбец типа Dynamic, из которого извлекаются значения.Dynamictype_name— имя типа варианта, который нужно извлечь (например, ‘String’, ‘Int64’, ‘Array(Int64)’).
Any
Примеры
Извлечение различных типов из столбца типа Dynamic
Query
Response
dynamicType
Добавленный в: v24.1.0 Возвращает имя типа варианта для каждой строки в столбце типаDynamic.
Для строк, содержащих NULL, функция возвращает ‘None’. Для всех остальных строк она возвращает фактический тип данных,
хранящийся в этой строке столбца типа Dynamic (например, ‘Int64’, ‘String’, ‘Array(Int64)’).
Синтаксис
dynamic— столбец типа Dynamic для анализа.Dynamic
String
Примеры
Проверка типов в столбце типа Dynamic
Query
Response
isDynamicElementInSharedData
Добавленный в: v24.1.0 Возвращает true для строк в столбце типа Dynamic, которые хранятся в общем формате variant, а не в виде отдельных подстолбцов. Если для столбца типа Dynamic задано ограничениеmax_types, значения, превышающие этот предел, сохраняются в общем бинарном формате,
а не разделяются на отдельные типизированные подстолбцы. Эта функция определяет, какие строки хранятся в этом общем формате.
Синтаксис
dynamic— столбец типа Dynamic для анализа.Dynamic
Bool
Примеры
Проверка формата хранения в столбце типа Dynamic с ограничением max_types
Query
Response
isValidJSON
Добавленный в: v20.1.0 Проверяет, является ли переданная строка корректным JSON. Синтаксисjson— строка JSON, которую нужно проверитьString
1, если строка содержит корректный JSON, иначе 0. UInt8
Примеры
Пример использования
Query
Response
Query
Response
prettyPrintJSON
Добавленный в: v26.4.0 Возвращает JSON-строку в удобочитаемом формате с переводами строк и отступами пробелами. Синтаксисjson— Допустимая JSON-строка для форматирования.Stringindent— Число пробелов на каждый уровень отступа. По умолчанию: 4. Максимум: 32UInt*
String
Примеры
Простой объект
Query
Response
Query
Response
simpleJSONExtractBool
Добавленный в: v21.4.0 Разбирает значение true/false из поля с именемfield_name.
Результат — UInt8.
Синтаксис
visitParamExtractBool
Аргументы
json— JSON, в котором выполняется поиск поля.Stringfield_name— Имя искомого поля.const String
1, если значение поля равно true, в противном случае — 0. Это означает, что функция будет возвращать 0, в том числе (и не только) в следующих случаях:
- Если поле не существует.
- Если поле содержит
trueв виде строки, например:{"field":"true"}. - Если поле содержит
1в виде числового значения.UInt8
Query
Response
simpleJSONExtractFloat
Добавленный в: v21.4.0 РазбираетFloat64 из значения поля с именем field_name.
Если field_name — строковое поле, пытается разобрать число из начала строки.
Если поле не существует или существует, но не содержит числа, возвращается 0.
Синтаксис
visitParamExtractFloat
Аргументы
json— JSON, в котором ищется поле.Stringfield_name— Имя искомого поля.const String
0. Float64
Примеры
Пример использования
Query
Response
simpleJSONExtractInt
Добавленный в: v21.4.0 ИзвлекаетInt64 из значения поля с именем field_name.
Если field_name — строковое поле, функция пытается разобрать число из начала строки.
Если поле не существует или существует, но не содержит числа, возвращается 0.
Синтаксис
visitParamExtractInt
Аргументы
json— JSON, в котором выполняется поиск поля.Stringfield_name— Имя искомого поля.const String
0 Int64
Примеры
Пример использования
Query
Response
simpleJSONExtractRaw
Добавленный в: v21.4.0 Возвращает значение поля с именемfield_name в виде String, включая разделители.
Синтаксис
visitParamExtractRaw
Аргументы
json— JSON, в котором выполняется поиск поля.Stringfield_name— Имя искомого поля.const String
String
Примеры
Пример использования
Query
Response
simpleJSONExtractString
Добавленный в: v21.4.0 Извлекает строкуString в двойных кавычках из значения поля с именем field_name.
Подробности реализации
В настоящее время не поддерживаются кодовые точки в формате \uXXXX\uYYYY, не относящиеся к базовой многоязычной плоскости (они преобразуются в CESU-8 вместо UTF-8).
Синтаксис
visitParamExtractString
Аргументы
json— JSON, в котором выполняется поиск поля.Stringfield_name— Имя поля, которое нужно найти.const String
String
Примеры
Пример использования
Query
Response
simpleJSONExtractUInt
Добавленный в: v21.4.0 ИзвлекаетUInt64 из значения поля с именем field_name.
Если field_name — строковое поле, функция пытается разобрать число из начала строки.
Если поле не существует или существует, но не содержит числа, возвращает 0.
Синтаксис
visitParamExtractUInt
Аргументы
json— JSON, в котором выполняется поиск поля.Stringfield_name— Имя искомого поля.const String
0 UInt64
Примеры
Пример использования
Query
Response
simpleJSONHas
Добавленный в: v21.4.0 Проверяет, существует ли поле с именемfield_name.
Синтаксис
visitParamHas
Аргументы
json— JSON, в котором ищется поле.Stringfield_name— Имя искомого поля.const String
1, если поле существует, иначе — 0 UInt8
Примеры
Пример использования
Query
Response
toJSONString
Добавленный в: v21.7.0 Сериализует значение в JSON-представление. Поддерживаются различные типы данных и вложенные структуры. 64-битные целые числа и более крупные (например,UInt64 или Int128) по умолчанию выводятся без кавычек. Это поведение контролируется параметром output_format_json_quote_64bit_integers.
Специальные значения NaN и inf заменяются на null. Чтобы они отображались, включите настройку output_format_json_quote_denormals.
При сериализации значения Enum функция выводит его имя.
См. также:
Синтаксис
value— Значение для сериализации. Значение может быть любого типа данных.Any
String
Примеры
Сериализация Map
Query
Response
Query
Response