Функции 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 и извлекает значение типа Int.

Синтаксис

Параметры

• 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. Каждый аргумент может быть либо строкой 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. String.
• path — Строка, представляющая путь. String.

примечание

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

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

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

Пример

Запрос:

Результат:

JSON_VALUE

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

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

• при SET function_json_value_return_type_allow_nullable = true, будет возвращено NULL. Если значение имеет сложный тип (например: struct, array, map), по умолчанию будет возвращена пустая строка.
• при 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).

Пример