json-functions

Существует два набора функций для разбора JSON:

• simpleJSON* (visitParam*), который предназначен для быстрого разбора ограниченного подмножества JSON.
• JSONExtract*, который предназначен для разбора обычного JSON.

Функции simpleJSON (visitParam)

ClickHouse имеет специальные функции для работы с упрощенным JSON. Все эти функции JSON основаны на строгих предположениях о том, что может содержать JSON. Они пытаются сделать как можно меньше, чтобы выполнить задачу как можно быстрее.

Следующие предположения были сделаны:

1. Имя поля (аргумент функции) должно быть константой.
2. Имя поля каким-то образом канонически закодировано в JSON. Например: simpleJSONHas('{"abc":"def"}', 'abc') = 1, но simpleJSONHas('{"\\u0061\\u0062\\u0063":"def"}', 'abc') = 0
3. Поля ищутся на любом уровне вложенности, без различия. Если есть несколько совпадающих полей, используется первое вхождение.
4. JSON не содержит пробелов вне строковых литералов.

simpleJSONHas

Проверяет, существует ли поле с именем field_name. Результат — UInt8.

Синтаксис

Псевдоним: visitParamHas.

Параметры

• json — JSON, в котором ищется поле. String
• field_name — Имя поля, которое нужно найти. String literal

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

• Возвращает 1, если поле существует, и 0 в противном случае. UInt8.

Пример

Запрос:

Результат:

simpleJSONExtractUInt

Извлекает UInt64 из значения поля с именем field_name. Если это строковое поле, оно пытается извлечь число из начала строки. Если поле не существует, или оно существует, но не содержит число, то возвращает 0.

Синтаксис

Псевдоним: visitParamExtractUInt.

Параметры

• json — JSON, в котором ищется поле. String
• field_name — Имя поля, которое нужно найти. String literal

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

• Возвращает число, извлеченное из поля, если поле существует и содержит число, иначе 0. UInt64.

Пример

Запрос:

Результат:

simpleJSONExtractInt

Извлекает Int64 из значения поля с именем field_name. Если это строковое поле, оно пытается извлечь число из начала строки. Если поле не существует, или оно существует, но не содержит число, то возвращает 0.

Синтаксис

Псевдоним: visitParamExtractInt.

Параметры

• json — JSON, в котором ищется поле. String
• field_name — Имя поля, которое нужно найти. String literal

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

• Возвращает число, извлеченное из поля, если поле существует и содержит число, иначе 0. Int64.

Пример

Запрос:

Результат:

simpleJSONExtractFloat

Извлекает Float64 из значения поля с именем field_name. Если это строковое поле, оно пытается извлечь число из начала строки. Если поле не существует, или оно существует, но не содержит число, то возвращает 0.

Синтаксис

Псевдоним: visitParamExtractFloat.

Параметры

• json — JSON, в котором ищется поле. String
• field_name — Имя поля, которое нужно найти. String literal

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

• Возвращает число, извлеченное из поля, если поле существует и содержит число, иначе 0. Float64.

Пример

Запрос:

Результат:

simpleJSONExtractBool

Извлекает значение true/false из значения поля с именем field_name. Результат — UInt8.

Синтаксис

Псевдоним: visitParamExtractBool.

Параметры

• json — JSON, в котором ищется поле. String
• field_name — Имя поля, которое нужно найти. String literal

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

Должно вернуть 1, если значение поля истинно, иначе 0. Это означает, что эта функция вернет 0 в следующих случаях:

• Если поле не существует.
• Если поле содержит "true" в виде строки, например: {"field":"true"}.
• Если поле содержит 1 как численное значение.

Пример

Запрос:

Результат:

simpleJSONExtractRaw

Возвращает значение поля с именем field_name в виде String, включая разделители.

Синтаксис

Псевдоним: visitParamExtractRaw.

Параметры

• json — JSON, в котором ищется поле. String
• field_name — Имя поля, которое нужно найти. String literal

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

• Возвращает значение поля как строку, включая разделители, если поле существует, иначе возвращает пустую строку. String

Пример

Запрос:

Результат:

simpleJSONExtractString

Извлекает String в двойных кавычках из значения поля с именем field_name.

Синтаксис

Псевдоним: visitParamExtractString.

Параметры

• json — JSON, в котором ищется поле. String
• field_name — Имя поля, которое нужно найти. String literal

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

• Возвращает необработанное значение поля как строку, включая разделители. Пустая строка возвращается, если поле не содержит строку в двойных кавычках, если разбор не удался или если поле не существует. String.

Детали реализации

В настоящее время нет поддержки кодовых точек формата \uXXXX\uYYYY, которые не входят в основную многоязычную плоскость (они конвертируются в CESU-8 вместо UTF-8).

Пример

Запрос:

Результат:

Функции JSONExtract

Следующие функции основаны на simdjson и предназначены для более сложных требований разбора JSON.

isValidJSON

Проверяет, является ли переданная строка допустимым JSON.

Синтаксис

Примеры

JSONHas

Если значение существует в документе JSON, будет возвращено 1. Если значение не существует, будет возвращено 0.

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает 1, если значение существует в json, иначе 0. UInt8.

Примеры

Запрос:

Минимальный индекс элемента равен 1. Таким образом, элемент 0 не существует. Вы можете использовать целые числа для доступа как к массивам JSON, так и к объектам JSON. Например:

JSONLength

Возвращает длину массива JSON или объекта JSON. Если значение не существует или имеет неправильный тип, будет возвращено 0.

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает длину массива JSON или объекта JSON. Возвращает 0, если значение не существует или имеет неправильный тип. UInt64.

Примеры

JSONType

Возвращает тип значения JSON. Если значение не существует, будет возвращено Null=0 (необычное Null, а Null=0 типа Enum8('Null' = 0, 'String' = 34,...). .

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает тип значения JSON как строку, в противном случае, если значение не существует, возвращает Null=0. Enum.

Примеры

JSONExtractUInt

Разбирает JSON и извлекает значение типа UInt.

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает значение типа UInt, если оно существует, иначе возвращает 0. UInt64.

Примеры

Запрос:

Результат:

JSONExtractInt

Разбирает JSON и извлекает значение типа Int.

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает значение типа Int, если оно существует, иначе возвращает 0. Int64.

Примеры

Запрос:

Результат:

JSONExtractFloat

Разбирает JSON и извлекает значение типа Float.

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает значение типа Float, если оно существует, иначе возвращает 0. Float64.

Примеры

Запрос:

Результат:

JSONExtractBool

Разбирает JSON и извлекает булевое значение. Если значение не существует или имеет неправильный тип, будет возвращено 0.

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает булевое значение, если оно существует, иначе возвращает 0. Bool.

Пример

Запрос:

Результат:

JSONExtractString

Разбирает JSON и извлекает строку. Эта функция похожа на функции visitParamExtractString. Если значение не существует или имеет неправильный тип, будет возвращена пустая строка.

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает необработанную строку из json. Если разбор не удался, если значение не существует или если оно имеет неправильный тип, то возвращается пустая строка. String.

Примеры

JSONExtract

Разбирает JSON и извлекает значение указанного типа данных ClickHouse. Эта функция является обобщенной версией предыдущих функций JSONExtract<type>. Это означает, что:

JSONExtract(..., 'String') возвращает точно то же самое, что и JSONExtractString(), JSONExtract(..., 'Float64') возвращает точно то же самое, что и JSONExtractFloat().

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.
• return_type — Строка, указывающая тип значения для извлечения. String.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает значение, если оно существует указанного типа возврата, иначе возвращает 0, Null или пустую строку в зависимости от указанного типа возврата. UInt64, Int64, Float64, Bool или String.

Примеры

Обращение к вложенным значениям путем передачи нескольких параметров indices_or_keys:

Результат:

JSONExtractKeysAndValues

Извлекает пары ключ-значение из JSON, где значения имеют указанный тип данных ClickHouse.

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.
• value_type — Строка, указывающая тип значения для извлечения. String.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает массив извлеченных пар ключ-значение. Array(Tuple(value_type)).

Пример

JSONExtractKeys

Разбирает строку JSON и извлекает ключи.

Синтаксис

Параметры

• json — String с допустимым JSON.
• a, b, c... — Запятые, разделяющие индексы или ключи, которые указывают путь к внутреннему полю в вложенном JSON-объекте. Каждый аргумент может быть либо String для получения поля по ключу, либо Integer для получения n-го поля (индексируется с 1, отрицательные целые числа считаются с конца). Если не задано, весь JSON разбирается как объект верхнего уровня. Необязательный параметр.

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

• Возвращает массив с ключами JSON. Array(String).

Пример

Запрос:

Результат:

JSONExtractRaw

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

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает часть JSON как необработанную строку. Если часть не существует или имеет неправильный тип, возвращается пустая строка. String.

Пример

JSONExtractArrayRaw

Возвращает массив с элементами массива JSON, каждый представленный как необработанная строка. Если часть не существует или не является массивом, будет возвращен пустой массив.

Синтаксис

Параметры

• json — Строка JSON для разбора. String.
• indices_or_keys — Список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String, Int*.

Тип indices_or_keys:

• Строка = доступ к члену объекта по ключу.
• Положительное целое число = доступ к n-му члену/ключу с начала.
• Отрицательное целое число = доступ к n-му члену/ключу с конца.

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

• Возвращает массив с элементами массива JSON, каждый представленный как необработанная строка. В противном случае, возвращается пустой массив, если часть не существует или не является массивом. Array(String).

Пример

JSONExtractKeysAndValuesRaw

Извлекает необработанные данные из объекта JSON.

Синтаксис

Аргументы

• json — String с допустимым JSON.
• p, a, t, h — Запятые, разделяющие индексы или ключи, которые указывают путь к внутреннему полю в вложенном JSON-объекте. Каждый аргумент может быть либо string для получения поля по ключу, либо integer для получения n-го поля (индексируется с 1, отрицательные целые числа считаются с конца). Если не задано, весь JSON разбирается как объект верхнего уровня. Необязательный параметр.

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

• Массив с кортежами ('key', 'value'). Оба члена кортежа являются строками. Array(Tuple(String, String)).
• Пустой массив, если запрашиваемый объект не существует, или входной JSON недействителен. Array(Tuple(String, String)).

Примеры

Запрос:

Результат:

Запрос:

Результат:

Запрос:

Результат:

JSON_EXISTS

Если значение существует в документе JSON, будет возвращено 1. Если значение не существует, будет возвращено 0.

Синтаксис

Параметры

• json — Строка с допустимым JSON. String.
• path — Строка, представляющая путь. String.

примечание

Перед версией 21.11 порядок аргументов был неверным, т. е. JSON_EXISTS(path, json)

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

• Возвращает 1, если значение существует в документе JSON, иначе 0.

Примеры

JSON_QUERY

Разбирает JSON и извлекает значение как JSON-массив или JSON-объект. Если значение не существует, будет возвращена пустая строка.

Синтаксис

Параметры

• json — Строка с допустимым JSON. String.
• path — Строка, представляющая путь. String.

примечание

Перед версией 21.11 порядок аргументов был неверным, т. е. JSON_EXISTS(path, json)

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

• Возвращает извлеченное значение как JSON-массив или JSON-объект. В противном случае возвращается пустая строка, если значение не существует. String.

Пример

Запрос:

Результат:

JSON_VALUE

Парсит JSON и извлекает значение как скалярный JSON. Если значение не существует, по умолчанию будет возвращена пустая строка.

Эта функция контролируется следующими настройками:

• при установке function_json_value_return_type_allow_nullable = true, будет возвращено NULL. Если значение является сложным типом (таким как: структура, массив, карта), по умолчанию будет возвращена пустая строка.
• при установке function_json_value_return_type_allow_complex = true, будет возвращено сложное значение.

Синтаксис

Параметры

• json — Строка с допустимым JSON. Строка.
• path — Строка, представляющая путь. Строка.

примечание

Перед версией 21.11 порядок аргументов был неверным, т.е. JSON_EXISTS(path, json)

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

• Возвращает извлеченное значение как скалярный JSON, если оно существует, в противном случае будет возвращена пустая строка. Строка.

Пример

Запрос:

Результат:

toJSONString

Сериализует значение в его JSON представление. Поддерживаются различные типы данных и вложенные структуры. 64-битные целые числа или больше (такие как UInt64 или Int128) по умолчанию заключаются в кавычки. Настройка output_format_json_quote_64bit_integers управляет этим поведением. Специальные значения NaN и inf заменяются на null. Включите настройку output_format_json_quote_denormals, чтобы показать их. При сериализации значения Enum функция выводит его имя.

Синтаксис

Аргументы

• value — Значение для сериализации. Значение может быть любого типа данных.

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

• JSON представление значения. Строка.

Пример

Первый пример показывает сериализацию Map. Второй пример показывает некоторые специальные значения, обернутые в Tuple.

Запрос:

Результат:

См. также

• output_format_json_quote_64bit_integers
• output_format_json_quote_denormals

JSONArrayLength

Возвращает количество элементов во внешнем JSON массиве. Функция возвращает NULL, если входная JSON строка недействительна.

Синтаксис

Псевдоним: JSON_ARRAY_LENGTH(json).

Аргументы

• json — Строка с допустимым JSON.

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

• Если json является допустимой строкой JSON массива, возвращает количество элементов массива, в противном случае возвращает NULL. Nullable(UInt64).

Пример

jsonMergePatch

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

Синтаксис

Аргументы

• json — Строка с допустимым JSON.

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

• Если строки JSON объектов допустимы, возвращает объединенную строку JSON объекта. Строка.

Пример

JSONAllPaths

Возвращает список всех путей, хранящихся в каждой строке в столбце JSON.

Синтаксис

Аргументы

• json — JSON.

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

• Массив путей. Array(String).

Пример

JSONAllPathsWithTypes

Возвращает карту всех путей и их типов данных, хранящихся в каждой строке в столбце JSON.

Синтаксис

Аргументы

• json — JSON.

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

• Массив путей. Map(String, String).

Пример

JSONDynamicPaths

Возвращает список динамических путей, которые хранятся как отдельные подколонки в столбце JSON.

Синтаксис

Аргументы

• json — JSON.

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

• Массив путей. Array(String).

Пример

JSONDynamicPathsWithTypes

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

Синтаксис

Аргументы

• json — JSON.

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

• Массив путей. Map(String, String).

Пример

JSONSharedDataPaths

Возвращает список путей, которые хранятся в общей структуре данных в JSON столбце.

Синтаксис

Аргументы

• json — JSON.

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

• Массив путей. Array(String).

Пример

JSONSharedDataPathsWithTypes

Возвращает карту путей, которые хранятся в общей структуре данных и их типов в каждой строке в JSON столбце.

Синтаксис

Аргументы

• json — JSON.

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

• Массив путей. Map(String, String).

Пример