Функции JSON
Типы функций 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, если это возможно.
JSONAllPaths
Введено в: v24.8
Возвращает список всех путей, хранящихся в каждой строке в колонке JSON.
Синтаксис
Аргументы
json
— колонка JSON.JSON
Возвращаемое значение
Возвращает массив всех путей в колонке JSON. Array(String)
Примеры
Пример использования
JSONAllPathsWithTypes
Введено в: v24.8
Возвращает список всех путей и их типов данных, хранящихся в каждой строке в колонке JSON.
Синтаксис
Аргументы
json
— колонка JSON.JSON
Возвращаемое значение
Возвращает карту всех путей и их типов данных в колонке JSON. Map(String, String)
Примеры
Пример использования
JSONArrayLength
Введено в: v23.2
Возвращает количество элементов в самом внешнем массиве JSON.
Функция возвращает NULL
, если входная строка JSON недействительна.
Синтаксис
Аргументы
json
— строка с допустимым JSON.String
Возвращаемое значение
Возвращает количество элементов массива, если json
является допустимой строкой массива JSON, в противном случае возвращает NULL
. Nullable(UInt64)
Примеры
Пример использования
JSONDynamicPaths
Введено в: v24.8
Возвращает список динамических путей, которые хранятся как отдельные подколонки в колонке JSON.
Синтаксис
Аргументы
json
— колонка JSON.JSON
Возвращаемое значение
Возвращает массив динамических путей в колонке JSON. Array(String)
Примеры
Пример использования
JSONDynamicPathsWithTypes
Введено в: v24.8
Возвращает список динамических путей, которые хранятся как отдельные подколонки и их типы в каждой строке в колонке JSON.
Синтаксис
Аргументы
json
— колонка JSON.JSON
Возвращаемое значение
Возвращает карту динамических путей и их типов данных в колонке JSON. Map(String, String)
Примеры
Пример использования
JSONExtract
Введено в: v19.14
Разбирает JSON и извлекает значение с заданным типом данных ClickHouse.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
return_type
— тип данных ClickHouse для возврата.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает значение указанного типа данных ClickHouse, если это возможно, в противном случае возвращает значение по умолчанию для этого типа.
Примеры
Пример использования
JSONExtractArrayRaw
Введено в: v20.1
Возвращает массив с элементами массива JSON, каждый из которых представлен как неразобранная строка.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает массив строк с элементами массива JSON. Если часть не является массивом или не существует, будет возвращен пустой массив. Array(String)
Примеры
Пример использования
JSONExtractArrayRawCaseInsensitive
Введено в: v25.8
Возвращает массив с элементами массива JSON, каждый из которых представлен как неразобранная строка, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtractArrayRaw
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к массиву. Ключи используют несравнительное соответствиеString
или(U)Int*
Возвращаемое значение
Возвращает массив неразобранных строк JSON. Array(String)
Примеры
базовый
JSONExtractBool
Введено в: v20.1
Разбирает JSON и извлекает значение типа Bool.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает значение типа Bool, если оно существует, в противном случае возвращает 0
. Bool
Примеры
Пример использования
JSONExtractBoolCaseInsensitive
Введено в: v25.8
Разбирает JSON и извлекает логическое значение, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtractBool
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к полю. Ключи используют несравнительное соответствиеString
или(U)Int*
Возвращаемое значение
Возвращает извлеченное логическое значение (1 для true, 0 для false), 0, если не найдено. UInt8
Примеры
базовый
JSONExtractCaseInsensitive
Введено в: v25.8
Разбирает JSON и извлекает значение данного типа данных ClickHouse, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtract
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к полю. Ключи используют несравнительное соответствиеString
или(U)Int*
return_type
— Тип данных ClickHouse для извлеченияString
Возвращаемое значение
Возвращает извлеченное значение в указанном типе данных. Any
Примеры
int_type
array_type
JSONExtractFloat
Введено в: v20.1
Разбирает JSON и извлекает значение типа Float.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает значение типа Float, если оно существует, в противном случае возвращает 0
. Float64
Примеры
Пример использования
JSONExtractFloatCaseInsensitive
Введено в: v25.8
Разбирает JSON и извлекает значение типа Float, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtractFloat
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к полю. Ключи используют несравнительное соответствиеString
или(U)Int*
Возвращаемое значение
Возвращает извлеченное значение Float, 0 если не найдено или не может быть преобразовано. Float64
Примеры
базовый
JSONExtractInt
Введено в: v20.1
Разбирает JSON и извлекает значение типа Int.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает значение типа Int, если оно существует, в противном случае возвращает 0
. Int64
Примеры
Пример использования
JSONExtractIntCaseInsensitive
Введено в: v25.8
Разбирает JSON и извлекает значение типа Int, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtractInt
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к полю. Ключи используют несравнительное соответствиеString
или(U)Int*
Возвращаемое значение
Возвращает извлеченное значение Int, 0 если не найдено или не может быть преобразовано. Int64
Примеры
базовый
вложенный
JSONExtractKeys
Введено в: v21.11
Разбирает строку JSON и извлекает ключи.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает массив с ключами объекта JSON. Array(String)
Примеры
Пример использования
JSONExtractKeysAndValues
Введено в: v20.1
Извлекает пары ключ-значение из JSON, где значения являются заданного типа данных ClickHouse.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
value_type
— тип данных ClickHouse значений.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает массив кортежей с разобранными парами ключ-значение. Array(Tuple(String, value_type))
Примеры
Пример использования
JSONExtractKeysAndValuesCaseInsensitive
Введено в: v25.8
Извлекает пары ключ-значение из JSON, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtractKeysAndValues
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к объекту. Ключи используют несравнительное соответствиеString
или(U)Int*
value_type
— Тип данных ClickHouse значенийString
Возвращаемое значение
Возвращает массив кортежей, содержащих пары ключ-значение. Array(Tuple(String, T))
Примеры
базовый
JSONExtractKeysAndValuesRaw
Введено в: v20.4
Возвращает массив кортежей с ключами и значениями из JSON-объекта. Все значения представлены как неразобранные строки.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает массив кортежей с разобранными парами ключ-значение, где значения являются неразобранными строками. Array(Tuple(String, String))
Примеры
Пример использования
JSONExtractKeysAndValuesRawCaseInsensitive
Введено в: v25.8
Извлекает сырые пары ключ-значение из JSON, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtractKeysAndValuesRaw
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к объекту. Ключи используют несравнительное соответствиеString
или(U)Int*
Возвращаемое значение
Возвращает массив кортежей, содержащих пары ключ-значение в виде сырых строк. Array(Tuple(String, String))
Примеры
базовый
JSONExtractKeysCaseInsensitive
Введено в: v25.8
Разбирает строку JSON и извлекает ключи, используя несравнительное соответствие ключей для навигации к вложенным объектам. Эта функция аналогична JSONExtractKeys
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к объекту. Ключи используют несравнительное соответствиеString
или(U)Int*
Возвращаемое значение
Возвращает массив ключей из JSON-объекта. Array(String)
Примеры
базовый
вложенный
JSONExtractRaw
Введено в: v20.1
Возвращает часть JSON как неразобранную строку.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает часть JSON как неразобранную строку. Если часть не существует или имеет неправильный тип, будет возвращена пустая строка. String
Примеры
Пример использования
JSONExtractRawCaseInsensitive
Введено в: v25.8
Возвращает часть JSON как неразобранную строку, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtractRaw
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к полю. Ключи используют несравнительное соответствиеString
или(U)Int*
Возвращаемое значение
Возвращает сырую строку JSON извлеченного элемента. String
Примеры
объект
JSONExtractString
Введено в: v20.1
Разбирает JSON и извлекает значение типа String.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает значение типа String, если оно существует, в противном случае возвращает пустую строку. String
Примеры
Пример использования
JSONExtractStringCaseInsensitive
Введено в: v25.8
Разбирает JSON и извлекает строку, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtractString
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к полю. Ключи используют несравнительное соответствиеString
или(U)Int*
Возвращаемое значение
Возвращает извлеченное строковое значение, пустую строку, если не найдено. String
Примеры
базовый
вложенный
JSONExtractUInt
Введено в: v20.1
Разбирает JSON и извлекает значение типа UInt.
Синтаксис
Аргументы
json
— строка JSON для разбора.String
indices_or_keys
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int*
Возвращаемое значение
Возвращает значение типа UInt, если оно существует, в противном случае возвращает 0
. UInt64
Примеры
Пример использования
JSONExtractUIntCaseInsensitive
Введено в: v25.8
Разбирает JSON и извлекает значение типа UInt, используя несравнительное соответствие ключей. Эта функция аналогична JSONExtractUInt
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
indices_or_keys
— Опционально. Индексы или ключи для навигации к полю. Ключи используют несравнительное соответствиеString
или(U)Int*
Возвращаемое значение
Возвращает извлеченное значение UInt, 0 если не найдено или не может быть преобразовано. UInt64
Примеры
базовый
JSONHas
Введено в: v20.1
Проверяет наличие предоставленных значений в документе JSON.
Синтаксис
Аргументы
json
— строка JSON для разбораString
[ ,indices_or_keys, ...]
— Список нуля или более аргументов.String
или(U)Int*
Возвращаемое значение
Возвращает 1
, если значение существует в json
, в противном случае 0
UInt8
Примеры
Пример использования
JSONLength
Введено в: v20.1
Возвращает длину массива JSON или объекта JSON.
Если значение не существует или имеет неправильный тип, будет возвращено 0
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
[, indices_or_keys, ...]
— Опционально. Список нуля или более аргументов.String
или(U)Int8/16/32/64
Возвращаемое значение
Возвращает длину массива JSON или объекта JSON, в противном случае возвращает 0
, если значение не существует или имеет неправильный тип. UInt64
Примеры
Пример использования
JSONMergePatch
Введено в: v23.10
Возвращает объединенную строку JSON-объекта, которая формируется путем объединения нескольких JSON-объектов.
Синтаксис
Аргументы
json1[, json2, ...]
— Одна или несколько строк с допустимым JSON.String
Возвращаемое значение
Возвращает объединенную строку JSON-объекта, если строки JSON-объекта допустимы. String
Примеры
Пример использования
JSONSharedDataPaths
Введено в: v24.8
Возвращает список путей, которые хранятся в общей структуре данных в колонке JSON.
Синтаксис
Аргументы
json
— колонка JSON.JSON
Возвращаемое значение
Возвращает массив путей, хранящихся в общей структуре данных в колонке JSON. Array(String)
Примеры
Пример использования
JSONSharedDataPathsWithTypes
Введено в: v24.8
Возвращает список путей, которые хранятся в общей структуре данных и их типов в каждой строке в колонке JSON.
Синтаксис
Аргументы
json
— колонка JSON.JSON
Возвращаемое значение
Возвращает карту путей, хранящихся в общей структуре данных и их типов данных в колонке JSON. Map(String, String)
Примеры
Пример использования
JSONType
Введено в: v20.1
Возвращает тип значения JSON. Если значение не существует, будет возвращено Null=0
.
Синтаксис
Аргументы
json
— строка JSON для разбораString
json[, indices_or_keys, ...]
— Список нуля или более аргументов, каждый из которых может быть либо строкой, либо целым числом.String
или(U)Int8/16/32/64
Возвращаемое значение
Возвращает тип значения JSON в виде строки, в противном случае, если значение не существует, оно возвращает Null=0
Enum
Примеры
Пример использования
JSON_EXISTS
Введено в: v21.8
Если значение существует в документе JSON, будет возвращено 1
.
Если значение не существует, будет возвращено 0
.
Синтаксис
Аргументы
Возвращаемое значение
Возвращает 1
, если значение существует в документе JSON, в противном случае 0
. UInt8
Примеры
Пример использования
JSON_QUERY
Введено в: v21.8
Разбирает JSON и извлекает значение как массив JSON или объект JSON. Если значение не существует, будет возвращена пустая строка.
Синтаксис
Аргументы
Возвращаемое значение
Возвращает извлеченный JSON-массив или JSON-объект в виде строки, или пустую строку, если значение не существует. String
Примеры
Пример использования
JSON_VALUE
Введено в: v21.11
Разбирает JSON и извлекает значение в виде скалярного значения JSON. Если значение не существует, по умолчанию будет возвращена пустая строка.
Эта функция управляется следующими настройками:
- установив
function_json_value_return_type_allow_nullable
=true
, будет возвращеноNULL
. Если значение имеет сложный тип (например: структура, массив, карта), по умолчанию будет возвращена пустая строка. - установив
function_json_value_return_type_allow_complex
=true
, будет возвращено сложное значение.
Синтаксис
Аргументы
Возвращаемое значение
Возвращает извлеченное скалярное значение JSON в виде строки, или пустую строку, если значение не существует. String
Примеры
Пример использования
dynamicElement
Введено в: v
Извлекает колонку с указанным типом из колонки Dynamic
.
Синтаксис
Аргументы
dynamic
— динамическая колонка -type_name
— имя варианта типа для извлечения
Возвращаемое значение
Примеры
Пример
dynamicType
Введено в: v
Возвращает имя варианта типа для каждой строки динамической колонки. Если строка содержит NULL, для нее возвращается 'None'.
Синтаксис
Аргументы
dynamic
— динамическая колонка
Возвращаемое значение
Примеры
Пример
isDynamicElementInSharedData
Введено в: v
Возвращает true для строк в динамической колонке, которые не разделены на подколонки и хранятся внутри общего варианта в двоичном формате.
Синтаксис
Аргументы
dynamic
— динамическая колонка
Возвращаемое значение
Примеры
Пример
isValidJSON
Введено в: v20.1
Проверяет, что переданная строка является допустимым JSON.
Синтаксис
Аргументы
json
— строка JSON для проверкиString
Возвращаемое значение
Возвращает 1
, если строка является допустимым JSON, в противном случае 0
. UInt8
Примеры
Пример использования
Использование целых чисел для доступа как к массивам JSON, так и к объектам JSON
simpleJSONExtractBool
Введено в: v21.4
Извлекает значение true/false из значения поля с именем field_name
.
Результат - UInt8
.
Синтаксис
Аргументы
json
— JSON, в котором ищется поле.String
field_name
— имя поля для поиска.const String
Возвращаемое значение
Возвращает 1
, если значение поля равно true
, 0
в противном случае. Это означает, что эта функция вернет 0
, включая (но не ограничиваясь) следующие случаи:
- Если поле не существует.
- Если поле содержит
true
в виде строки, например:{"field":"true"}
. - Если поле содержит
1
в качестве числового значения.UInt8
Примеры
Пример использования
simpleJSONExtractFloat
Представлено в: v21.4
Парсит Float64
из значения поля с именем field_name
.
Если field_name
— это строковое поле, оно пытается парсить число из начала строки.
Если поле не существует или существует, но не содержит числа, оно возвращает 0
.
Синтаксис
Аргументы
json
— JSON, в котором ищется поле.String
field_name
— имя поля, которое нужно найти.const String
Возвращаемое значение
Возвращает число, распарсенное из поля, если поле существует и содержит число, в противном случае 0
. Float64
Примеры
Пример использования
simpleJSONExtractInt
Представлено в: v21.4
Парсит Int64
из значения поля с именем field_name
.
Если field_name
— это строковое поле, оно пытается парсить число из начала строки.
Если поле не существует или существует, но не содержит числа, оно возвращает 0
.
Синтаксис
Аргументы
json
— JSON, в котором ищется поле.String
field_name
— имя поля, которое нужно найти.const String
Возвращаемое значение
Возвращает число, распарсенное из поля, если поле существует и содержит число, 0
в противном случае. Int64
Примеры
Пример использования
simpleJSONExtractRaw
Представлено в: v21.4
Возвращает значение поля с именем field_name
в виде String
, включая разделители.
Синтаксис
Аргументы
json
— JSON, в котором ищется поле.String
field_name
— имя поля, которое нужно найти.const String
Возвращаемое значение
Возвращает значение поля в виде строки, включая разделители, если поле существует, или пустую строку в противном случае. String
Примеры
Пример использования
simpleJSONExtractString
Представлено в: v21.4
Парсит String
в двойных кавычках из значения поля с именем field_name
.
Детали реализации
В настоящее время нет поддержки кодовых точек в формате \uXXXX\uYYYY
, которые не принадлежат базовой многоязычной плоскости (они конвертируются в CESU-8 вместо UTF-8).
Синтаксис
Аргументы
json
— JSON, в котором ищется поле.String
field_name
— имя поля, которое нужно найти.const String
Возвращаемое значение
Возвращает неэкранированное значение поля в виде строки, включая разделители. Пустая строка возвращается, если поле не содержит строки в двойных кавычках, если распаковка не удалась или если поле не существует. String
Примеры
Пример использования
simpleJSONExtractUInt
Представлено в: v21.4
Парсит UInt64
из значения поля с именем field_name
.
Если field_name
— это строковое поле, оно пытается парсить число из начала строки.
Если поле не существует или существует, но не содержит числа, оно возвращает 0
.
Синтаксис
Аргументы
json
— JSON, в котором ищется поле.String
field_name
— имя поля, которое нужно найти.const String
Возвращаемое значение
Возвращает число, распарсенное из поля, если поле существует и содержит число, 0
в противном случае. UInt64
Примеры
Пример использования
simpleJSONHas
Представлено в: v21.4
Проверяет, существует ли поле с именем field_name
.
Синтаксис
Аргументы
json
— JSON, в котором ищется поле.String
field_name
— имя поля, которое нужно найти.const String
Возвращаемое значение
Возвращает 1
, если поле существует, 0
в противном случае. UInt8
Примеры
Пример использования
toJSONString
Представлено в: v21.7
Сериализует значение в его JSON-представление. Поддерживаются различные типы данных и вложенные структуры.
64-битные целые числа или больше (например, UInt64
или Int128
) заключаются в кавычки по умолчанию. output_format_json_quote_64bit_integers управляет этим поведением.
Специальные значения NaN
и inf
заменяются на null
. Включите настройку output_format_json_quote_denormals, чтобы отобразить их.
При сериализации значения Enum функция выводит его имя.
Смотрите также:
Синтаксис
Аргументы
value
— Значение для сериализации. Значение может быть любого типа.Any
Возвращаемое значение
Возвращает JSON-представление значения. String
Примеры
Сериализация Map
Специальные значения
variantElement
Представлено в: v
Извлекает колонку с указанным типом из колонки Variant
.
Синтаксис
Аргументы
variant
— колонка Varianttype_name
— имя типа варианта, который нужно извлечьdefault_value
— значение по умолчанию, которое будет использоваться, если вариант не содержит варианта с указанным типом. Может быть любого типа. Необязательный параметр
Возвращаемое значение
Примеры
Пример
variantType
Представлено в: v
Возвращает имя типа варианта для каждой строки колонки Variant
. Если строка содержит NULL, то для неё возвращается 'None'.
Синтаксис
Аргументы
variant
— колонка Variant
Возвращаемое значение
Примеры
Пример