Перейти к основному содержанию
Перейти к основному содержанию

Функции JSON

Типы 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 нет пробелов вне строковых литералов.

Функции JSONExtract

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

Регистронезависимые функции JSONExtract

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

Примечание

Эти функции могут работать медленнее, чем их регистрозависимые аналоги, поэтому по возможности используйте обычные функции JSONExtract.

JSONAllPaths

Представлена в версии v24.8

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

Синтаксис

JSONAllPaths(json)

Аргументы

  • json — столбец JSON. JSON

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

Возвращает массив всех путей в столбце JSON. Array(String)

Примеры

Пример использования

CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONAllPaths(json) FROM test;
┌─json─────────────────────────────────┬─JSONAllPaths(json)─┐
│ {"a":"42"}                           │ ['a']              │
│ {"b":"Hello"}                        │ ['b']              │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ ['a','c']          │
└──────────────────────────────────────┴────────────────────┘

JSONAllPathsWithTypes

Добавлено в версии: v24.8

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

Синтаксис

JSONAllPathsWithTypes(json)

Аргументы

  • json — JSON-столбец. JSON

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

Возвращает карту всех путей и соответствующих им типов данных в JSON-столбце. Map(String, String)

Примеры

Пример использования

CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONAllPathsWithTypes(json) FROM test;
┌─json─────────────────────────────────┬─JSONAllPathsWithTypes(json)───────────────┐
│ {"a":"42"}                           │ {'a':'Int64'}                             │
│ {"b":"Hello"}                        │ {'b':'String'}                            │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ {'a':'Array(Nullable(Int64))','c':'Date'} │
└──────────────────────────────────────┴───────────────────────────────────────────┘

JSONArrayLength

Появилась в версии: v23.2

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

Синтаксис

JSONArrayLength(json)

Псевдонимы: JSON_ARRAY_LENGTH

Аргументы

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

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

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

Примеры

Пример использования

SELECT
    JSONArrayLength(''),
    JSONArrayLength('[1,2,3]');
┌─JSONArrayLength('')─┬─JSONArrayLength('[1,2,3]')─┐
│                ᴺᵁᴸᴸ │                          3 │
└─────────────────────┴────────────────────────────┘

JSONDynamicPaths

Добавлено в: v24.8

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

Синтаксис

JSONDynamicPaths(json)

Аргументы

  • json — JSON-столбец. JSON

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

Возвращает массив динамических путей в JSON-столбце. Array(String)

Примеры

Пример использования

CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONDynamicPaths(json) FROM test;
┌─json─────────────────────────────────┬─JSONDynamicPaths(json)─┐
│ {"a":"42"}                           │ ['a']                  │
│ {"b":"Hello"}                        │ []                     │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ ['a']                  │
└──────────────────────────────────────┴────────────────────────┘

JSONDynamicPathsWithTypes

Добавлено в: v24.8

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

Синтаксис

JSONDynamicPathsWithTypes(json)

Аргументы

  • json — столбец JSON. JSON

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

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

Примеры

Пример использования

CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONDynamicPathsWithTypes(json) FROM test;
┌─json─────────────────────────────────┬─JSONDynamicPathsWithTypes(json)─┐
│ {"a":"42"}                           │ {'a':'Int64'}                   │
│ {"b":"Hello"}                        │ {}                              │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ {'a':'Array(Nullable(Int64))'}  │
└──────────────────────────────────────┴─────────────────────────────────┘

JSONExtract

Добавлена в версии: v19.14

Парсит JSON и извлекает значение заданного типа данных ClickHouse.

Синтаксис

JSONExtract(json[, indices_or_keys, ...], return_type)

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSONExtract('{"a": "hello", "b": [-100, 200.0, 300]}', 'Tuple(String, Array(Float64))') AS res;
┌─res──────────────────────────────┐
│ ('hello',[-100,200,300])         │
└──────────────────────────────────┘

JSONExtractArrayRaw

Появилась в версии: v20.1

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

Синтаксис

JSONExtractArrayRaw(json[, indices_or_keys, ...])

Аргументы

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

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

Возвращает массив строк с элементами JSON-массива. Если соответствующее значение не является массивом или не существует, возвращается пустой массив. Array(String)

Примеры

Пример использования

SELECT JSONExtractArrayRaw('{"a": "hello", "b": [-100, 200.0, "hello"]}', 'b') AS res;
┌─res──────────────────────────┐
│ ['-100','200.0','"hello"']   │
└──────────────────────────────┘

JSONExtractArrayRawCaseInsensitive

Добавлено в: v25.8

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

Синтаксис

JSONExtractArrayRawCaseInsensitive(json [, indices_or_keys]...)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — Необязательный параметр. Индексы или ключи для перехода к массиву. Ключи сравниваются без учета регистра String или (U)Int*

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

Возвращает массив сырых JSON-строк. Array(String)

Примеры

базовый

SELECT JSONExtractArrayRawCaseInsensitive('{"Items": [1, 2, 3]}', 'ITEMS')
['1','2','3']

JSONExtractBool

Добавлена в версии: v20.1

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

Синтаксис

JSONExtractBool(json[, indices_or_keys, ...])

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSONExtractBool('{"passed": true}', 'passed') AS res;
┌─res─┐
│   1 │
└─────┘

JSONExtractBoolCaseInsensitive

Добавлена в версии: v25.8

Парсит JSON и извлекает логическое значение, используя регистронезависимый поиск по ключу. Эта функция аналогична JSONExtractBool.

Синтаксис

JSONExtractBoolCaseInsensitive(json [, indices_or_keys]...)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — необязательный аргумент. Индексы или ключи для перехода к полю. Ключи сопоставляются без учета регистра String или (U)Int*

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

Возвращает извлечённое логическое значение (1 для true, 0 для false), либо 0, если значение не найдено. UInt8

Примеры

Базовый пример

SELECT JSONExtractBoolCaseInsensitive('{"IsActive": true}', 'isactive')
1

JSONExtractCaseInsensitive

Добавлена в: v25.8

Разбирает JSON и извлекает значение указанного типа данных ClickHouse, используя регистронезависимое сопоставление ключей. Эта функция аналогична JSONExtract.

Синтаксис

JSONExtractCaseInsensitive(json [, indices_or_keys...], return_type)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — Необязательный параметр. Индексы или ключи для перехода к полю. Ключи сравниваются без учёта регистра String или (U)Int*
  • return_type — Тип данных ClickHouse, в котором нужно вернуть значение String

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

Возвращает извлечённое значение в указанном типе данных. Any

Примеры

int_type

SELECT JSONExtractCaseInsensitive('{"Number": 123}', 'number', 'Int32')
123

array_type

SELECT JSONExtractCaseInsensitive('{"List": [1, 2, 3]}', 'list', 'Array(Int32)')
[1,2,3]

JSONExtractFloat

Появилась в версии: v20.1

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

Синтаксис

JSONExtractFloat(json[, indices_or_keys, ...])

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSONExtractFloat('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 2) AS res;
┌─res─┐
│ 200 │
└─────┘

JSONExtractFloatCaseInsensitive

Впервые представлена в: v25.8

Разбирает JSON и извлекает значение типа Float, используя регистронезависимое сопоставление ключей. Эта функция аналогична JSONExtractFloat.

Синтаксис

JSONExtractFloatCaseInsensitive(json [, indices_or_keys]...)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — Необязательный параметр. Индексы или ключи для перехода к полю. Ключи сопоставляются без учета регистра String или (U)Int*

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

Возвращает извлеченное значение с плавающей запятой, 0 — если поле не найдено или значение не может быть преобразовано. Float64

Примеры

базовый пример

SELECT JSONExtractFloatCaseInsensitive('{"Price": 12.34}', 'PRICE')
12.34

JSONExtractInt

Добавлено в версии: v20.1

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

Синтаксис

JSONExtractInt(json[, indices_or_keys, ...])

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSONExtractInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 1) AS res;
┌──res─┐
│ -100 │
└──────┘

JSONExtractIntCaseInsensitive

Добавлена в: v25.8

Разбирает JSON и извлекает значение типа Int, используя регистронезависимое сопоставление ключей. Эта функция аналогична JSONExtractInt.

Синтаксис

JSONExtractIntCaseInsensitive(json [, indices_or_keys]...)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — Необязательный параметр. Индексы или ключи для перехода к полю. Ключи сопоставляются без учета регистра String или (U)Int*

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

Возвращает извлечённое значение типа Int, 0 — если значение не найдено или не может быть преобразовано. Int64

Примеры

Базовый пример

SELECT JSONExtractIntCaseInsensitive('{"Value": 123}', 'value')
123

вложенный

SELECT JSONExtractIntCaseInsensitive('{"DATA": {"COUNT": 42}}', 'data', 'Count')
42

JSONExtractKeys

Добавлена в версии: v21.11

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

Синтаксис

JSONExtractKeys(json[, indices_or_keys, ...])

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSONExtractKeys('{"a": "hello", "b": [-100, 200.0, 300]}') AS res;
┌─res─────────┐
│ ['a','b']   │
└─────────────┘

JSONExtractKeysAndValues

Появилось в версии: v20.1

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

Синтаксис

JSONExtractKeysAndValues(json[, indices_or_keys, ...], value_type)

Аргументы

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

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

Возвращает массив кортежей с разобранными парами ключ–значение. Array(Tuple(String, value_type))

Примеры

Пример использования

SELECT JSONExtractKeysAndValues('{"x": {"a": 5, "b": 7, "c": 11}}', 'Int8', 'x') AS res;
┌─res────────────────────┐
│ [('a',5),('b',7),('c',11)] │
└────────────────────────┘

JSONExtractKeysAndValuesCaseInsensitive

Добавлена в: v25.8

Извлекает пары ключ–значение из JSON с регистронезависимым сопоставлением ключей. Эта функция аналогична функции JSONExtractKeysAndValues.

Синтаксис

JSONExtractKeysAndValuesCaseInsensitive(json [, indices_or_keys...], value_type)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — Необязательный параметр. Индексы или ключи для перехода к объекту. Ключи сопоставляются без учета регистра String или (U)Int*
  • value_type — тип данных ClickHouse для значений String

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

Возвращает массив кортежей, содержащих пары ключ-значение. Array(Tuple(String, T))

Примеры

простой пример

SELECT JSONExtractKeysAndValuesCaseInsensitive('{"Name": "Alice", "AGE": 30}', 'String')
[('Name','Alice'),('AGE','30')]

JSONExtractKeysAndValuesRaw

Добавлена в версии: v20.4

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

Синтаксис

JSONExtractKeysAndValuesRaw(json[, indices_or_keys, ...])

Аргументы

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

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

Возвращает массив кортежей с разобранными парами ключ–значение, где значения представляют собой неразобранные строки. Array(Tuple(String, String))

Примеры

Пример использования

SELECT JSONExtractKeysAndValuesRaw('{"a": [-100, 200.0], "b": "hello"}') AS res;
┌─res──────────────────────────────────┐
│ [('a','[-100,200.0]'),('b','"hello"')] │
└──────────────────────────────────────┘

JSONExtractKeysAndValuesRawCaseInsensitive

Добавлена в версии: v25.8

Извлекает необработанные пары ключ-значение из JSON, сопоставляя ключи без учета регистра. Эта функция похожа на JSONExtractKeysAndValuesRaw.

Синтаксис

JSONExtractKeysAndValuesRawCaseInsensitive(json [, indices_or_keys]...)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — Необязательный параметр. Индексы или ключи для перехода к объекту. Ключи сопоставляются без учета регистра String или (U)Int*

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

Возвращает массив кортежей, содержащих пары ключ-значение в виде исходных строк. Array(Tuple(String, String))

Примеры

простой пример

SELECT JSONExtractKeysAndValuesRawCaseInsensitive('{"Name": "Alice", "AGE": 30}')
[('Name','"Alice"'),('AGE','30')]

JSONExtractKeysCaseInsensitive

Добавлено в: v25.8

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

Синтаксис

JSONExtractKeysCaseInsensitive(json [, indices_or_keys]...)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — Необязательный параметр. Индексы или ключи для перехода к объекту. Ключи сравниваются без учета регистра String или (U)Int*

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

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

Примеры

базовый

SELECT JSONExtractKeysCaseInsensitive('{"Name": "Alice", "AGE": 30}')
['Name','AGE']

вложенный

SELECT JSONExtractKeysCaseInsensitive('{"User": {"name": "John", "AGE": 25}}', 'user')
['name','AGE']

JSONExtractRaw

Добавлен в версии: v20.1

Возвращает часть JSON в виде строки без парсинга.

Синтаксис

JSONExtractRaw(json[, indices_or_keys, ...])

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSONExtractRaw('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') AS res;
┌─res──────────────┐
│ [-100,200.0,300] │
└──────────────────┘

JSONExtractRawCaseInsensitive

Добавлено в: v25.8

Возвращает часть JSON в виде необработанной строки, используя регистронезависимое сопоставление ключей. Эта функция аналогична JSONExtractRaw.

Синтаксис

JSONExtractRawCaseInsensitive(json [, indices_or_keys]...)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — Необязательный аргумент. Индексы или ключи для перехода к полю. Сопоставление ключей выполняется без учета регистра String или (U)Int*

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

Возвращает необработанную JSON-строку извлеченного элемента. String

Примеры

object

SELECT JSONExtractRawCaseInsensitive('{"Object": {"key": "value"}}', 'OBJECT')
{"key":"value"}

JSONExtractString

Добавлена в версии v20.1

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

Синтаксис

JSONExtractString(json[, indices_or_keys, ...])

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSONExtractString('{"a": "hello", "b": [-100, 200.0, 300]}', 'a') AS res;
┌─res───┐
│ hello │
└───────┘

JSONExtractStringCaseInsensitive

Появилась в версии v25.8

Разбирает JSON и извлекает строку, используя регистронезависимое сопоставление ключей. Эта функция аналогична JSONExtractString.

Синтаксис

JSONExtractStringCaseInsensitive(json [, indices_or_keys]...)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — Необязательный параметр. Индексы или ключи для перехода к полю. Ключи сопоставляются без учёта регистра String или (U)Int*

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

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

Примеры

Базовый пример

SELECT JSONExtractStringCaseInsensitive('{"ABC": "def"}', 'abc')
def

вложенный

SELECT JSONExtractStringCaseInsensitive('{"User": {"Name": "John"}}', 'user', 'name')
John

JSONExtractUInt

Появился в версии: v20.1

Анализирует JSON и извлекает значение типа UInt.

Синтаксис

JSONExtractUInt(json [, indices_or_keys, ...])

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSONExtractUInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', -1) AS res;
┌─res─┐
│ 300 │
└─────┘

JSONExtractUIntCaseInsensitive

Появилась в версии v25.8

Разбирает JSON и извлекает значение типа UInt, используя регистронезависимое сравнение ключей. Эта функция аналогична JSONExtractUInt.

Синтаксис

JSONExtractUIntCaseInsensitive(json [, indices_or_keys]...)

Аргументы

  • json — JSON-строка для разбора String
  • indices_or_keys — необязательный параметр. Индексы или ключи для перехода к полю. Ключи сопоставляются без учёта регистра String или (U)Int*

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

Возвращает извлечённое значение типа UInt, 0 — если значение не найдено или не может быть преобразовано. UInt64

Примеры

Базовый пример

SELECT JSONExtractUIntCaseInsensitive('{"COUNT": 789}', 'count')
789

JSONHas

Появилось в версии: v20.1

Проверяет наличие указанного значения (значений) в JSON-документе.

Синтаксис

JSONHas(json[ ,indices_or_keys, ...])

Аргументы

  • json — JSON-строка для разбора String
  • [ ,indices_or_keys, ...] — список, содержащий ноль или более аргументов. String или (U)Int*

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

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

Примеры

Пример использования

SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') = 1;
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 4) = 0;
1
0

JSONLength

Добавлена в версии: v20.1

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

Синтаксис

JSONLength(json [, indices_or_keys, ...])

Аргументы

  • json — JSON-строка для разбора String
  • [, indices_or_keys, ...] — Необязательный список из нуля или более аргументов. String или (U)Int8/16/32/64

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

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

Примеры

Пример использования

SELECT JSONLength('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') = 3;
SELECT JSONLength('{"a": "hello", "b": [-100, 200.0, 300]}') = 2;
1
1

JSONMergePatch

Добавлено в версии: v23.10

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

Синтаксис

jsonMergePatch(json1[, json2, ...])

Псевдонимы: jsonMergePatch

Аргументы

  • json1[, json2, ...] — Одна или несколько строк с валидным JSON. String

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

Возвращает строку объединённого JSON-объекта, если строки JSON-объектов валидны. String

Примеры

Пример использования

SELECT jsonMergePatch('{"a":1}', '{"name": "joey"}', '{"name": "tom"}', '{"name": "zoey"}') AS res;
┌─res───────────────────┐
│ {"a":1,"name":"zoey"} │
└───────────────────────┘

JSONSharedDataPaths

Введено в: v24.8

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

Синтаксис

JSONSharedDataPaths(json)

Аргументы

  • json — столбец JSON. JSON

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

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

Примеры

Пример использования

CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONSharedDataPaths(json) FROM test;
┌─json─────────────────────────────────┬─JSONSharedDataPaths(json)─┐
│ {"a":"42"}                           │ []                        │
│ {"b":"Hello"}                        │ ['b']                     │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ ['c']                     │
└──────────────────────────────────────┴───────────────────────────┘

JSONSharedDataPathsWithTypes

Появилось в: v24.8

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

Синтаксис

JSONSharedDataPathsWithTypes(json)

Аргументы

  • json — JSON-столбец. JSON

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

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

Примеры

Пример использования

CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONSharedDataPathsWithTypes(json) FROM test;
┌─json─────────────────────────────────┬─JSONSharedDataPathsWithTypes(json)─┐
│ {"a":"42"}                           │ {}                                  │
│ {"b":"Hello"}                        │ {'b':'String'}                      │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ {'c':'Date'}                        │
└──────────────────────────────────────┴─────────────────────────────────────┘

JSONType

Введена в версии: v20.1

Возвращает тип JSON-значения. Если значение отсутствует, будет возвращено Null=0.

Синтаксис

JSONType(json[, indices_or_keys, ...])

Аргументы

  • json — JSON-строка для разбора String
  • json[, indices_or_keys, ...] — список из нуля или более аргументов, каждый из которых может быть строкой или целым числом. String или (U)Int8/16/32/64

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

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

Примеры

Пример использования

SELECT JSONType('{"a": "hello", "b": [-100, 200.0, 300]}') = 'Object';
SELECT JSONType('{"a": "hello", "b": [-100, 200.0, 300]}', 'a') = 'String';
SELECT JSONType('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') = 'Array';
1
1
1

JSON_EXISTS

Появилась в версии v21.8.

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

Синтаксис

JSON_EXISTS(json, path)

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSON_EXISTS('{"hello":1}', '$.hello');
SELECT JSON_EXISTS('{"hello":{"world":1}}', '$.hello.world');
SELECT JSON_EXISTS('{"hello":["world"]}', '$.hello[*]');
SELECT JSON_EXISTS('{"hello":["world"]}', '$.hello[0]');
┌─JSON_EXISTS(⋯ '$.hello')─┐
│                        1 │
└──────────────────────────┘
┌─JSON_EXISTS(⋯llo.world')─┐
│                        1 │
└──────────────────────────┘
┌─JSON_EXISTS(⋯.hello[*]')─┐
│                        1 │
└──────────────────────────┘
┌─JSON_EXISTS(⋯.hello[0]')─┐
│                        1 │
└──────────────────────────┘

JSON_QUERY

Появилось в: v21.8

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

Синтаксис

JSON_QUERY(json, path)

Аргументы

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

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

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

Примеры

Пример использования

SELECT JSON_QUERY('{"hello":"world"}', '$.hello');
SELECT JSON_QUERY('{"array":[[0, 1, 2, 3, 4, 5], [0, -1, -2, -3, -4, -5]]}', '$.array[*][0 to 2, 4]');
SELECT JSON_QUERY('{"hello":2}', '$.hello');
SELECT toTypeName(JSON_QUERY('{"hello":2}', '$.hello'));
["world"]
[0, 1, 4, 0, -1, -4]
[2]
String

JSON_VALUE

Введена в версии: v21.11

Разбирает 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_VALUE(json, path)

Аргументы

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

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

Возвращает извлечённый JSON‑скаляр как строку или пустую строку, если значение не существует. String

Примеры

Пример использования

SELECT JSON_VALUE('{"hello":"world"}', '$.hello');
SELECT JSON_VALUE('{"array":[[0, 1, 2, 3, 4, 5], [0, -1, -2, -3, -4, -5]]}', '$.array[*][0 to 2, 4]');
SELECT JSON_VALUE('{"hello":2}', '$.hello');
SELECT JSON_VALUE('{"hello":"world"}', '$.b') settings function_json_value_return_type_allow_nullable=true;
world
0
2
ᴺᵁᴸᴸ

dynamicElement

Впервые появился в: v24.1

Извлекает столбец с указанным типом из столбца Dynamic.

Эта функция позволяет извлекать значения определённого типа из столбца Dynamic. Если строка содержит значение запрошенного типа, возвращается это значение. Если строка содержит значение другого типа или NULL, возвращается NULL для скалярных типов или пустой массив для типов массивов.

Синтаксис

dynamicElement(dynamic, type_name)

Аргументы

  • dynamic — динамический столбец, из которого выполняется извлечение. Dynamic
  • type_name — имя варианта типа, который нужно извлечь (например, 'String', 'Int64', 'Array(Int64)').

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

Возвращает значения указанного типа из динамического столбца. Возвращает NULL для несовпадающих типов (или пустой массив для типов-массивов). Any

Примеры

Извлечение различных типов из динамического столбца

CREATE TABLE test (d Dynamic) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT d, dynamicType(d), dynamicElement(d, 'String'), dynamicElement(d, 'Int64'), dynamicElement(d, 'Array(Int64)'), dynamicElement(d, 'Date'), dynamicElement(d, 'Array(String)') FROM test
┌─d─────────────┬─dynamicType(d)─┬─dynamicElement(d, 'String')─┬─dynamicElement(d, 'Int64')─┬─dynamicElement(d, 'Array(Int64)')─┬─dynamicElement(d, 'Date')─┬─dynamicElement(d, 'Array(String)')─┐
│ ᴺᵁᴸᴸ          │ None           │ ᴺᵁᴸᴸ                        │                       ᴺᵁᴸᴸ │ []                                │                      ᴺᵁᴸᴸ │ []                                 │
│ 42            │ Int64          │ ᴺᵁᴸᴸ                        │                         42 │ []                                │                      ᴺᵁᴸᴸ │ []                                 │
│ Hello, World! │ String         │ Hello, World!               │                       ᴺᵁᴸᴸ │ []                                │                      ᴺᵁᴸᴸ │ []                                 │
│ [1,2,3]       │ Array(Int64)   │ ᴺᵁᴸᴸ                        │                       ᴺᵁᴸᴸ │ [1,2,3]                           │                      ᴺᵁᴸᴸ │ []                                 │
└───────────────┴────────────────┴─────────────────────────────┴────────────────────────────┴───────────────────────────────────┴───────────────────────────┴────────────────────────────────────┘

dynamicType

Появилась в версии v24.1

Возвращает имя варианта типа для каждой строки столбца Dynamic.

Для строк, содержащих NULL, функция возвращает 'None'. Для всех остальных строк она возвращает фактический тип данных, хранящийся в этой строке столбца Dynamic (например, 'Int64', 'String', 'Array(Int64)').

Синтаксис

dynamicType(dynamic)

Аргументы

  • dynamic — столбец типа Dynamic для анализа. Dynamic

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

Возвращает имя типа значения, хранящегося в каждой строке, или «None» для значений NULL. String

Примеры

Анализ типов в столбце типа Dynamic

CREATE TABLE test (d Dynamic) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT d, dynamicType(d) FROM test;
┌─d─────────────┬─dynamicType(d)─┐
│ ᴺᵁᴸᴸ          │ None           │
│ 42            │ Int64          │
│ Hello, World! │ String         │
│ [1,2,3]       │ Array(Int64)   │
└───────────────┴────────────────┘

isDynamicElementInSharedData

Добавлена в версии v24.1

Возвращает true для строк в столбце типа Dynamic, которые хранятся в общем формате варианта (shared variant format), а не как отдельные подстолбцы.

Когда для столбца типа Dynamic задано ограничение max_types, значения, превышающие этот лимит, сохраняются в общем двоичном формате, вместо того чтобы быть разделёнными на отдельные типизированные подстолбцы. Эта функция определяет, какие строки хранятся в этом общем формате.

Синтаксис

isDynamicElementInSharedData(dynamic)

Аргументы

  • dynamic — динамический столбец для проверки. Dynamic

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

Возвращает true, если значение хранится в формате shared variant, и false, если оно хранится как отдельный подстолбец или равно NULL. Bool

Примеры

Проверка формата хранения в динамическом столбце с ограничением max_types

CREATE TABLE test (d Dynamic(max_types=2)) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT d, isDynamicElementInSharedData(d) FROM test;
┌─d─────────────┬─isDynamicElementInSharedData(d)─┐
│ ᴺᵁᴸᴸ          │ false                           │
│ 42            │ false                           │
│ Hello, World! │ true                            │
│ [1,2,3]       │ true                            │
└───────────────┴─────────────────────────────────┘

isValidJSON

Впервые появилась в версии: v20.1

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

Синтаксис

isValidJSON(json)

Аргументы

  • json — JSON-строка для проверки String

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

Возвращает 1, если строка является корректным JSON, иначе 0. UInt8

Примеры

Пример использования

SELECT isValidJSON('{"a": "hello", "b": [-100, 200.0, 300]}') = 1;
SELECT isValidJSON('not JSON') = 0;
1
0

Использование целых чисел для доступа к JSON‑массивам и JSON‑объектам

SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 0);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 1);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 2);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', -1);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', -2);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 3);
0
1
1
1
1
1
0

simpleJSONExtractBool

Добавлено в: v21.4

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

Синтаксис

simpleJSONExtractBool(json, field_name)

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

Аргументы

  • json — JSON, в котором выполняется поиск поля. String
  • field_name — имя поля, по которому выполняется поиск. const String

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

Возвращает 1, если значение поля равно true, иначе 0. Это означает, что функция вернёт 0 в том числе (но не только) в следующих случаях:

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

Примеры

Пример использования

CREATE TABLE jsons
(
    `json` String
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO jsons VALUES ('{"foo":false,"bar":true}');
INSERT INTO jsons VALUES ('{"foo":"true","qux":1}');

SELECT simpleJSONExtractBool(json, 'bar') FROM jsons ORDER BY json;
SELECT simpleJSONExtractBool(json, 'foo') FROM jsons ORDER BY json;
0
1
0
0

simpleJSONExtractFloat

Введена в версии: v21.4

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

Синтаксис

simpleJSONExtractFloat(json, field_name)

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

Аргументы

  • json — объект JSON, в котором выполняется поиск поля. String
  • field_name — имя поля, которое нужно найти. const String

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

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

Примеры

Пример использования

CREATE TABLE jsons
(
    `json` String
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO jsons VALUES ('{"foo":"-4e3"}');
INSERT INTO jsons VALUES ('{"foo":-3.4}');
INSERT INTO jsons VALUES ('{"foo":5}');
INSERT INTO jsons VALUES ('{"foo":"not1number"}');
INSERT INTO jsons VALUES ('{"baz":2}');

SELECT simpleJSONExtractFloat(json, 'foo') FROM jsons ORDER BY json;
0
-4000
0
-3.4
5

simpleJSONExtractInt

Добавлена в версии v21.4

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

Синтаксис

simpleJSONExtractInt(json, field_name)

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

Аргументы

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

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

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

Примеры

Пример использования

CREATE TABLE jsons
(
    `json` String
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO jsons VALUES ('{"foo":"-4e3"}');
INSERT INTO jsons VALUES ('{"foo":-3.4}');
INSERT INTO jsons VALUES ('{"foo":5}');
INSERT INTO jsons VALUES ('{"foo":"not1number"}');
INSERT INTO jsons VALUES ('{"baz":2}');

SELECT simpleJSONExtractInt(json, 'foo') FROM jsons ORDER BY json;
0
-4
0
-3
5

simpleJSONExtractRaw

Появилась в версии: v21.4

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

Синтаксис

simpleJSONExtractRaw(json, field_name)

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

Аргументы

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

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

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

Примеры

Пример использования

CREATE TABLE jsons
(
    `json` String
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO jsons VALUES ('{"foo":"-4e3"}');
INSERT INTO jsons VALUES ('{"foo":-3.4}');
INSERT INTO jsons VALUES ('{"foo":5}');
INSERT INTO jsons VALUES ('{"foo":{"def":[1,2,3]}}');
INSERT INTO jsons VALUES ('{"baz":2}');

SELECT simpleJSONExtractRaw(json, 'foo') FROM jsons ORDER BY json;
"-4e3"
-3.4
5
{"def":[1,2,3]}

simpleJSONExtractString

Введена в версии: v21.4

Извлекает строку типа String, заключённую в двойные кавычки, из значения поля с именем field_name.

Подробности реализации

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

Синтаксис

simpleJSONExtractString(json, field_name)

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

Аргументы

  • json — JSON, в котором выполняется поиск поля. String
  • field_name — имя поля, по которому выполняется поиск. const String

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

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

Примеры

Пример использования

CREATE TABLE jsons
(
    `json` String
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO jsons VALUES ('{"foo":"\\n\\u0000"}');
INSERT INTO jsons VALUES ('{"foo":"\\u263"}');
INSERT INTO jsons VALUES ('{"foo":"\\u263a"}');
INSERT INTO jsons VALUES ('{"foo":"hello}');

SELECT simpleJSONExtractString(json, 'foo') FROM jsons ORDER BY json;
\n\0

☺

simpleJSONExtractUInt

Добавлена в версии: v21.4

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

Синтаксис

simpleJSONExtractUInt(json, field_name)

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

Аргументы

  • json — JSON, в котором выполняется поиск поля. String
  • field_name — имя поля, по которому выполняется поиск. const String

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

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

Примеры

Пример использования

CREATE TABLE jsons
(
    `json` String
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO jsons VALUES ('{"foo":"4e3"}');
INSERT INTO jsons VALUES ('{"foo":3.4}');
INSERT INTO jsons VALUES ('{"foo":5}');
INSERT INTO jsons VALUES ('{"foo":"not1number"}');
INSERT INTO jsons VALUES ('{"baz":2}');

SELECT simpleJSONExtractUInt(json, 'foo') FROM jsons ORDER BY json;
0
4
0
3
5

simpleJSONHas

Появилась в версии: v21.4

Проверяет, существует ли поле с именем field_name.

Синтаксис

simpleJSONHas(json, field_name)

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

Аргументы

  • json — JSON, в котором выполняется поиск поля. String
  • field_name — имя поля для поиска. const String

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

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

Примеры

Пример использования

CREATE TABLE jsons
(
    `json` String
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO jsons VALUES ('{"foo":"true","qux":1}');

SELECT simpleJSONHas(json, 'foo') FROM jsons;
SELECT simpleJSONHas(json, 'bar') FROM jsons;
1
0

toJSONString

Введена в версии v21.7

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

См. также:

Синтаксис

toJSONString(value)

Аргументы

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

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

Возвращает JSON-представление значения. String

Примеры

Сериализация Map

SELECT toJSONString(map('key1', 1, 'key2', 2));
┌─toJSONString(map('key1', 1, 'key2', 2))─┐
│ {"key1":1,"key2":2}                     │
└─────────────────────────────────────────┘

Специальные значения

SELECT toJSONString(tuple(1.25, NULL, NaN, +inf, -inf, [])) SETTINGS output_format_json_quote_denormals = 1;
┌─toJSONString(tuple(1.25, NULL, NaN, plus(inf), minus(inf), []))─┐
│ [1.25,null,"nan","inf","-inf",[]]                               │
└─────────────────────────────────────────────────────────────────┘