Функции JSON

Существует два набора функций для разбора 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, если значение поля равно true, 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 тип:

• String = доступ к объекту по ключу.
• Положительное целое число = доступ к 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 тип:

• String = доступ к объекту по ключу.
• Положительное целое число = доступ к 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 тип:

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

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

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

Примеры

JSONExtractUInt

Парсит JSON и извлекает значение типа UInt.

Синтаксис

Параметры

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

indices_or_keys тип:

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

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

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

Примеры

Запрос:

Результат:

JSONExtractInt

Парсит JSON и извлекает значение типа Int.

Синтаксис

Параметры

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

indices_or_keys тип:

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

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

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

Примеры

Запрос:

Результат:

JSONExtractFloat

Парсит JSON и извлекает значение типа Float.

Синтаксис

Параметры

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

indices_or_keys тип:

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

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

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

Примеры

Запрос:

Результат:

JSONExtractBool

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

Синтаксис

Параметры

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

indices_or_keys тип:

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

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

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

Пример

Запрос:

Результат:

JSONExtractString

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

Синтаксис

Параметры

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

indices_or_keys тип:

• String = доступ к объекту по ключу.
• Положительное целое число = доступ к 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 тип:

• String = доступ к объекту по ключу.
• Положительное целое число = доступ к 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 тип:

• String = доступ к объекту по ключу.
• Положительное целое число = доступ к 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 тип:

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

Возврат значения

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

Пример

JSONExtractArrayRaw

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

Синтаксис

Параметры

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

indices_or_keys тип:

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

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

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

Пример

JSONExtractKeysAndValuesRaw

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

Синтаксис

Аргументы

• json — String с валидным JSON.
• p, a, t, h — Запятая, разделяющая индексы или ключи, которые указывают путь к внутреннему полю в вложенном объекте JSON. Каждый аргумент может быть либо строкой, чтобы получить поле по ключу, либо целым числом, чтобы получить 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. Если значение не существует, по умолчанию будет возвращена пустая строка.

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

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

Синтаксис

Параметры

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

примечание

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

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

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

Пример

Запрос:

Результат:

toJSONString

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

Синтаксис

Аргументы

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

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

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

Пример

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

Запрос:

Результат:

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

• output_format_json_quote_64bit_integers
• output_format_json_quote_denormals

JSONArrayLength

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

Синтаксис

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

Аргументы

• json — String с корректным JSON.

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

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

Пример

jsonMergePatch

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

Синтаксис

Аргументы

• json — String с корректным JSON.

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

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

Пример

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).

Пример