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

Функции 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 — строка с допустимым 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))

Примеры

базовый

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

Введено в: v23.10

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

Синтаксис

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

Аргументы

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

Введено в: v

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

Синтаксис

dynamicElement(dynamic, type_name)

Аргументы

  • dynamic — динамическая колонка - type_name — имя варианта типа для извлечения

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

Примеры

Пример

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

Введено в: v

Возвращает имя варианта типа для каждой строки динамической колонки. Если строка содержит NULL, для нее возвращается 'None'.

Синтаксис

dynamicType(dynamic)

Аргументы

  • 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

Введено в: v

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

Синтаксис

isDynamicElementInSharedData(dynamic)

Аргументы

  • dynamic — динамическая колонка

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

Примеры

Пример

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)

Аргументы

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

Аргументы

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

Аргументы

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

Аргументы

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

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

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

Синтаксис

simpleJSONExtractString(json, field_name)

Аргументы

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

Аргументы

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

Аргументы

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

variantElement

Представлено в: v

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

Синтаксис

variantElement(variant, type_name, [, default_value])

Аргументы

  • variant — колонка Variant
  • type_name — имя типа варианта, который нужно извлечь
  • default_value — значение по умолчанию, которое будет использоваться, если вариант не содержит варианта с указанным типом. Может быть любого типа. Необязательный параметр

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

Примеры

Пример

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

variantType

Представлено в: v

Возвращает имя типа варианта для каждой строки колонки Variant. Если строка содержит NULL, то для неё возвращается 'None'.

Синтаксис

variantType(variant)

Аргументы

  • variant — колонка Variant

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

Примеры

Пример

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;
┌─variantType(v)─┐
│ None           │
│ UInt64         │
│ String         │
│ Array(UInt64)  │
└────────────────┘