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

Функции 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, return_type[, indices_or_keys, ...])

Аргументы

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

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

Возвращает значение указанного типа данных 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*

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

Возвращает извлечённое значение Float, 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─┐
│ 200 │
└─────┘

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, value_type[, indices_or_keys, ...])

Аргументы

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

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

Возвращает массив кортежей с разобранными парами ключ-значение. 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))

Примеры

basic

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

Примеры

объект

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

Introduced in: 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-скаляр. Если значение не существует, по умолчанию возвращается пустая строка.

Работа этой функции управляется следующими настройками:

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

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

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

Примеры

Извлечение различных типов из сто��бца Dynamic

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, которые хранятся в общем формате вариантов, а не в виде отдельных подстолбцов.

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

Синтаксис

isDynamicElementInSharedData(dynamic)

Аргументы

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

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

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

Примеры

Проверка формата хранения в столбце Dynamic с ограничением 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

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

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

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

Синтаксис

simpleJSONExtractString(json, field_name)

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

Аргументы

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

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

Возвращает значение поля в виде строки с обработанными escape-последовательностями, включая разделители. Возвращается пустая строка, если поле не содержит строку в двойных кавычках, если обработка escape-последовательностей завершилась неудачей или если поле не существует. 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

Introduced in: 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",[]]                               │
└─────────────────────────────────────────────────────────────────┘