Built for parsing ordinary JSON with full compatibility. These functions offer more flexibility and support for complex JSON structures.

ClickHouse function reference

isValidJSON

Checks whether a string is valid JSON.

Syntax:

isValidJSON(json)

Arguments:

  • json (String): The string to check for JSON validity.

Returns:

1 if the string is valid JSON, 0 otherwise. [UInt8]

Example:

SELECT
	isValidJSON('{"taco_filling": "carnitas", "toppings": ["onions", "cilantro"]}') AS valid_json,
	isValidJSON('not a json') AS invalid_json;

Result:

| valid_json | invalid_json |
|------------|--------------|
| 1          | 0            |

In this example, we check two strings for JSON validity. The first string is a valid JSON object representing a taco order, while the second is not valid JSON.

This function is useful for validating JSON input before processing it with other JSON functions, helping to prevent errors when working with potentially malformed data.

JSONHas

Checks if a specified value exists in a JSON document.

Syntax

JSONHas(json, indices_or_keys...)

Arguments

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int*): A list of zero or more arguments, each of which can be either a string or an integer.
    • String = access object member by key.
    • Positive integer = access the n-th member/key from the beginning.
    • Negative integer = access the n-th member/key from the end.

Returns

  • Returns 1 if the value exists in the JSON, otherwise 0. (UInt8)

Example

SELECT
  JSONHas('{"taco_fillings": ["beef", "cheese", "lettuce"]}', 'taco_fillings', 2) AS has_cheese;

Result:

| has_cheese |
|------------|
| 1          |

In this example, JSONHas checks if the second element (index 2) of the “taco_fillings” array exists, which is “cheese”. The result is 1, confirming its presence.

The minimum index of an element is 1. Thus, element 0 does not exist. You can use integers to access both JSON arrays and JSON objects.

JSONLength

Returns the length of a JSON array or a JSON object.

Syntax:

JSONLength(json [, indices_or_keys]...)

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int*): A list of zero or more arguments, each of which can be either string or integer.

indices_or_keys type:

  • String = access object member by key.
  • Positive integer = access the n-th member/key from the beginning.
  • Negative integer = access the n-th member/key from the end.

Returns:

  • Returns the length of the JSON array or JSON object. Returns 0 if the value does not exist or has the wrong type. (UInt64)

Example:

SELECT
  JSONLength('{"taco_fillings": ["beef", "cheese", "lettuce"], "sauce": "hot"}', 'taco_fillings') AS filling_count;

Result:

| filling_count |
|---------------|
| 3             |

In this example, JSONLength returns the number of elements in the “taco_fillings” array.

SELECT
  JSONLength(
    simpleJSONExtractRaw(
      '{"taco_menu": {"classic": 5.99, "supreme": 7.99, "veggie": 6.99}}',
      'taco_menu')
) AS menu_items;

Result:

| menu_items |
|------------|
| 3          |

Here, JSONLength returns the number of key-value pairs in the “taco_menu” object.

If the specified path doesn’t exist or isn’t an array or object, the function returns 0.

JSONType

Returns the type of a JSON value.

Syntax:

JSONType(json [, indices_or_keys]...)

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int*): A list of zero or more arguments, each of which can be either string or integer.

indices_or_keys type:

  • String = access object member by key.
  • Positive integer = access the n-th member/key from the beginning.
  • Negative integer = access the n-th member/key from the end.

Returns:

  • Returns the type of a JSON value as a string, otherwise if the value doesn’t exist it returns Null. (String)

Example:

SELECT
	JSONType('{"taco_filling": "carnitas", "toppings": ["salsa", "guacamole", "cheese"]}') AS json_type,
	JSONType('{"taco_filling": "carnitas", "toppings": ["salsa", "guacamole", "cheese"]}', 'taco_filling') AS filling_type,
	JSONType('{"taco_filling": "carnitas", "toppings": ["salsa", "guacamole", "cheese"]}', 'toppings') AS toppings_type;

Result:

| json_type | filling_type | toppings_type |
|-----------|--------------|---------------|
| Object    | String       | Array         |

In this example:

  • json_type shows the type of the entire JSON structure (Object).
  • filling_type shows the type of the “taco_filling” value (String).
  • toppings_type shows the type of the “toppings” value (Array).

This function is useful for determining the structure of JSON data, especially when dealing with dynamic or unknown JSON schemas in your datasets.

JSONExtractUInt

Parses JSON and extracts an unsigned integer value.

Syntax:

JSONExtractUInt(json [, indices_or_keys]...)

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int, optional): A list of zero or more arguments, each of which can be either a string or an integer.

indices_or_keys types:

  • String = access object member by key.
  • Positive integer = access the n-th member/key from the beginning.
  • Negative integer = access the n-th member/key from the end.

Returns:

  • Returns an unsigned integer value if it exists, otherwise it returns 0. (UInt64)

Example:

SELECT
	JSONExtractUInt('{"taco_id": 42, "toppings": ["cheese", "salsa"]}', 'taco_id') AS taco_number;

Result:

| taco_number |
|-------------|
| 42          |

In this example, JSONExtractUInt extracts the value of the “taco_id” field from the JSON string, returning the unsigned integer 42.

If the JSON field contains a non-integer value or doesn’t exist, the function returns 0.

JSONExtractInt

Parses JSON and extracts an integer value.

Syntax:

JSONExtractInt(json [, indices_or_keys]...)

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int*): A list of zero or more arguments, each of which can be either string or integer.

indices_or_keys type:

  • String = access object member by key.
  • Positive integer = access the n-th member/key from the beginning.
  • Negative integer = access the n-th member/key from the end.

Returns:

  • Returns an Int64 value if it exists, otherwise it returns 0.

Example:

SELECT
	JSONExtractInt('{"taco_order": {"id": 42, "items": [-100, 200, 300]}}', 'taco_order', 'id') AS order_id,
	JSONExtractInt('{"taco_order": {"id": 42, "items": [-100, 200, 300]}}', 'taco_order', 'items', 2) AS second_item;

Result:

| order_id | second_item |
|----------|-------------|
| 42       | 200         |

In this example:

  • order_id extracts the ‘id’ from the ‘taco_order’ object.
  • second_item extracts the second element (index 2) from the ‘items’ array within the ‘taco_order’ object.

This function is useful for extracting integer values from nested JSON structures, such as order IDs or numerical item data in a taco ordering system.

JSONExtractFloat

Parses JSON and extracts a floating-point value.

Syntax:

JSONExtractFloat(json [, indices_or_keys]...)

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int, optional): A list of zero or more arguments, each of which can be either a string or an integer.

indices_or_keys types:

  • String = access object member by key.
  • Positive integer = access the n-th member/key from the beginning.
  • Negative integer = access the n-th member/key from the end.

Returns:

  • Returns a Float64 value if it exists, otherwise it returns 0.

Example:

SELECT
	JSONExtractFloat('{"taco_price": 9.99, "toppings": ["cheese", "salsa"]}', 'taco_price') AS price;

Result:

| price |
|-------|
| 9.99  |

In this example, JSONExtractFloat extracts the taco_price value from the JSON string. If the taco_price field didn’t exist or wasn’t a number, the function would return 0.

This function is part of a family of JSON parsing functions in ClickHouse. For more complex JSON operations, consider using JSONExtract with a specified return type.

JSONExtractBool

Parses JSON and extracts a boolean value.

Syntax:

JSONExtractBool(json [, indices_or_keys]...)

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int*): A list of zero or more arguments, each of which can be either string or integer.

indices_or_keys type:

  • String = access object member by key.
  • Positive integer = access the n-th member/key from the beginning.
  • Negative integer = access the n-th member/key from the end.

Returns:

  • Returns a Boolean value if it exists, otherwise it returns 0. (Bool)

Example:

SELECT
	JSONExtractBool(
    '{"is_spicy": true, "taco_fillings": ["beef", "lettuce", "cheese"]}',
    'is_spicy'
  ) AS spicy_taco;

Result:

| spicy_taco |
|------------|
| 1          |

In this example, JSONExtractBool extracts the boolean value of the “is_spicy” field from the JSON string. The result 1 indicates that the taco is indeed spicy.

JSONExtractString

Parses JSON and extracts a string value.

Syntax:

JSONExtractString(json [, indices_or_keys]...)

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int, optional): A list of zero or more arguments, each of which can be either string or integer.

indices_or_keys type:

  • String = access object member by key.
  • Positive integer = access the n-th member/key from the beginning.
  • Negative integer = access the n-th member/key from the end.

Returns:

Returns an unescaped string from JSON. If unescaping failed, if the value does not exist or if it has a wrong type then it returns an empty string. (String)

Example:

SELECT
	JSONExtractString(
    '{"taco_fillings": ["carne asada", "pollo", "carnitas"]}',
    'taco_fillings',
    2
  ) AS second_filling;

Result:

| second_filling |
|----------------|
| pollo          |

In this example, we extract the second element from the “taco_fillings” array in the JSON string.

This function is similar to simpleJSONExtractString, but it supports more complex JSON structures and nested access using indices or keys.

JSONExtract

Parses JSON and extracts a value of the specified ClickHouse data type.

Syntax:

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

Arguments:

  • json (String): JSON string to parse.
  • return_type (String): The ClickHouse data type to extract.
  • indices_or_keys (String, Int*, optional): Optional list of zero or more arguments, each of which can be either a string or an integer.
    • String = access object member by key
    • Positive integer = access the n-th member/key from the beginning
    • Negative integer = access the n-th member/key from the end

Returns:

  • Returns a value of the specified return_type if it exists, otherwise returns a default value (0, NULL, or empty string) depending on the specified return type.

Example:

SELECT
    JSONExtract(JSONExtractRaw('{"taco_fillings": ["carnitas", "pollo", "carne asada"]}', 'taco_fillings'), 'Array(String)') AS fillings,
    JSONExtract(JSONExtractRaw('{"spice_level": 3}', 'spice_level'), 'UInt8') AS spice_level,
    JSONExtract(JSONExtractRaw('{"taco_price": 2.50}', 'taco_price'), 'Float64') AS price;

Result:

| fillings                           | spice_level | price |
|------------------------------------|-------------|-------|
| ['carnitas','pollo','carne asada'] | 3           | 2.5   |

This example demonstrates extracting different types of data from JSON:

  • An array of strings for taco fillings
  • An unsigned 8-bit integer for spice level
  • A 64-bit float for taco price

JSONExtract is a versatile function that can handle various ClickHouse data types, including complex types like Arrays, Tuples, and Maps.

This function is a generalized version of type-specific functions like JSONExtractString, JSONExtractFloat, etc. It provides more flexibility in handling different data types within JSON structures.

JSONExtractKeysAndValues

Parses key-value pairs from JSON where the values are of the given ClickHouse data type.

Syntax:

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

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int*, optional): A list of zero or more arguments, each of which can be either string or integer.
  • value_type (String): A string specifying the type of the value to extract.

indices_or_keys type:

  • String = access object member by key.
  • Positive integer = access the n-th member/key from the beginning.
  • Negative integer = access the n-th member/key from the end.

Returns:

  • Returns an array of parsed key-value pairs. (Array(Tuple(String, value_type)))

Example:

SELECT
	JSONExtractKeysAndValues(
    '{"taco_fillings": {"meat": "carnitas", "toppings": ["salsa", "guacamole"]}}',
    'taco_fillings',
    'String'
  ) AS taco_ingredients;

Result:

| taco_ingredients                                                |
|-----------------------------------------------------------------|
| [('meat','carnitas'),('toppings','["salsa","guacamole"]')]      |

In this example, we extract the key-value pairs from the taco_fillings object. The meat field is extracted as a string, while the toppings array is extracted as a JSON string.

The function extracts values based on the specified value_type. If a value doesn’t match the specified type, it may be converted or returned as a string representation.

JSONExtractKeys

Parses a JSON string and extracts the keys.

Syntax:

JSONExtractKeys(json[, indices_or_keys...])

Arguments:

  • json (String): A string containing valid JSON.
  • indices_or_keys (optional): A list of zero or more arguments specifying the path to an inner field in a nested JSON object. Each argument can be either:
    • A string to access an object member by key.
    • A positive integer to access the n-th member/key from the beginning (1-based).
    • A negative integer to access the n-th member/key from the end.

Returns:

An array containing the keys of the JSON object. (Array(String))

Example:

SELECT
  JSONExtractKeys(
    '{"salsa": "mild", "guacamole": {"spiciness": 7, "ingredients": ["avocado", "lime"]}}'
  );

Result:

| JSONExtractKeys('{"salsa": "mild", "guacamole": {"spiciness": 7, "ingredients": ["avocado", "lime"]}}')  |
|----------------------------------------------------------------------------------------------------------|
| ['salsa','guacamole']                                                                                    |

In this example, JSONExtractKeys extracts the top-level keys from the JSON object representing a taco order.

To extract keys from a nested object:

SELECT
  JSONExtractKeys(
    '{"salsa": "mild", "guacamole": {"spiciness": 7, "ingredients": ["avocado", "lime"]}}',
    'guacamole'
  );

Result:

| JSONExtractKeys('{"salsa": "mild", "guacamole": {"spiciness": 7, "ingredients": ["avocado", "lime"]}}', 'guacamole')   |
|------------------------------------------------------------------------------------------------------------------------|
| ['spiciness','ingredients']                                                                                            |

This extracts the keys from the nested ‘guacamole’ object.

If the specified path doesn’t exist or doesn’t point to a JSON object, an empty array is returned.

JSONExtractRaw

Returns part of the JSON as an unparsed string.

Syntax:

JSONExtractRaw(json [, indices_or_keys]...)

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int*): A list of zero or more arguments, each of which can be either string or integer.

indices_or_keys type:

  • String = access object member by key.
  • Positive integer = access the n-th member/key from the beginning.
  • Negative integer = access the n-th member/key from the end.

Returns:

Returns part of the JSON as an unparsed string. If the part does not exist or has the wrong type, an empty string is returned. (String)

Example:

SELECT JSONExtractRaw(
  '{"taco_fillings":["beef","cheese","lettuce"]}',
  'taco_fillings'
) AS taco_fillings;

Result:

| taco_fillings                  |
|--------------------------------|
| ["beef","cheese","lettuce"]    |

In this example, JSONExtractRaw extracts the taco_fillings array as a raw string, preserving its JSON structure.

This function is useful when you need to extract a portion of a JSON document without parsing it, maintaining its original structure including nested objects and arrays.

JSONExtractArrayRaw

Extracts elements from a JSON array as an array of unparsed strings.

Syntax:

JSONExtractArrayRaw(json [, indices_or_keys]...)

Arguments:

  • json (String): JSON string to parse.
  • indices_or_keys (String, Int, optional): Optional list of arguments, each of which can be either a string or an integer.
    • String = access object member by key
    • Positive integer = access the n-th member/key from the beginning
    • Negative integer = access the n-th member/key from the end

Returns:

  • An array with elements of the JSON array, each represented as an unparsed string. Returns an empty array if the specified part does not exist or is not an array. (Array(String))

Example:

SELECT
  JSONExtractArrayRaw(
    '{"taco_fillings": ["beef", "cheese", "lettuce"]}',
    'taco_fillings'
  ) AS fillings;

Result:

| fillings                           |
|------------------------------------|
| ['"beef"','cheese','lettuce']      |

In this example, JSONExtractArrayRaw extracts the “taco_fillings” array from the JSON string. Each element is returned as an unparsed string, preserving the original JSON formatting.

This function is useful when you need to extract array elements while maintaining their original JSON representation, including any nested structures or special characters.

Syntax:

JSONExtractKeysAndValuesRaw(json[, indices_or_keys...])

Arguments:

  • json (String): A string containing valid JSON.
  • indices_or_keys (String, Int, optional): A list of zero or more arguments, each of which can be either a string or an integer.
    • String = access object member by key.
    • Positive integer = access the n-th member/key from the beginning.
    • Negative integer = access the n-th member/key from the end.

Returns:

  • An array of (‘key’, ‘value’) tuples. Both tuple members are strings. (Array(Tuple(String, String)))
  • An empty array if the requested object does not exist or the input JSON is invalid.

Example:

SELECT
  JSONExtractKeysAndValuesRaw(
    '{"taco_fillings": ["beef", "cheese"], "salsa": {"spiciness": "hot"}}',
    'salsa'
  );

Result:

| JSONExtractKeysAndValuesRaw('{"taco_fillings": ["beef", "cheese"], "salsa": {"spiciness": "hot"}}', 'salsa') |
|--------------------------------------------------------------------------------------------------------------|
| [('spiciness','"hot"')]                                                                                      |

In this example, the function extracts the key-value pair from the ‘salsa’ object within the JSON string. The result is an array containing a single tuple with the key ‘spiciness’ and the value ‘“hot”’ (including the quotes as it’s a raw extraction).

This function is useful when you need to preserve the original JSON representation of values, including string quotes and formatting of nested objects or arrays.

JSON_EXISTS

Checks if a specified value exists in a JSON document.

Syntax:

JSON_EXISTS(json, path)

Arguments:

  • json (String): A string containing valid JSON.
  • path (String): A string representing the JSON path to search.

Returns:

  • 1 if the value exists in the JSON document, 0 otherwise. [UInt8]

Example:

SELECT JSON_EXISTS('{"taco_fillings": ["beef", "lettuce", "cheese"]}', '$.taco_fillings[*]');

Result:

| JSON_EXISTS('{"taco_fillings": ["beef", "lettuce", "cheese"]}', '$.taco_fillings[*]')  |
|----------------------------------------------------------------------------------------|
| 1                                                                                      |

In this example, JSON_EXISTS checks if the taco_fillings array exists in the JSON document. The result 1 indicates that it does exist.

Additional Examples:

SELECT JSON_EXISTS('{"taco_price": 5.99}', '$.taco_price');

SELECT JSON_EXISTS('{"taco_special": {"name": "Taco Tuesday", "discount": 0.2}}', '$.taco_special.discount');

SELECT JSON_EXISTS('{"taco_toppings": ["salsa", "guacamole"]}', '$.taco_toppings[1]');

This function is useful for checking the presence of specific elements or structures within JSON data, which is particularly helpful when working with dynamic or nested JSON content in your datasets.

JSON_QUERY

Parses a JSON and extracts a value as a JSON array or JSON object.

Syntax:

JSON_QUERY(json, path)

Arguments:

  • json (String): A string containing valid JSON.
  • path (String): A string representing the JSON path.

Returns:

The extracted value as a JSON array or JSON object. Returns an empty string if the value does not exist. [String]

Example:

SELECT JSON_QUERY('{"taco_fillings": ["beef", "lettuce", "cheese"]}', '$.taco_fillings');

Result:

| JSON_QUERY('{"taco_fillings": ["beef", "lettuce", "cheese"]}', '$.taco_fillings') |
|-----------------------------------------------------------------------------------|
| ["beef", "lettuce", "cheese"]                                                     |

This example extracts the “taco_fillings” array from the JSON object.

SELECT JSON_QUERY('{"taco_order": {"id": 123, "items": ["Crunchy Taco", "Burrito Supreme"]}}', '$.taco_order');

Result:

| JSON_QUERY('{"taco_order": {"id": 123, "items": ["Crunchy Taco", "Burrito Supreme"]}}', '$.taco_order') |
|---------------------------------------------------------------------------------------------------------|
| {"id": 123, "items": ["Crunchy Taco", "Burrito Supreme"]}                                               |

This example extracts the entire “taco_order” object from the JSON.

  • The function returns the extracted value as a JSON string, even for scalar values.
  • If the extracted value is not a JSON array or object, it will be wrapped in square brackets.
SELECT JSON_QUERY('{"spice_level": "hot"}', '$.spice_level');

Result:

| JSON_QUERY('{"spice_level": "hot"}', '$.spice_level') |
|-------------------------------------------------------|
| ["hot"]                                               |

JSON_VALUE

Parses a JSON and extracts a value as a JSON scalar.

Syntax:

JSON_VALUE(json, path)

Arguments:

  • json (String): A string containing valid JSON.
  • path (String): A string representing the JSON path.

Returns:

  • Returns the extracted value as a JSON scalar if it exists, otherwise an empty string. (String)

Example:

SELECT
	JSON_VALUE('{"taco_order": {"filling": "carnitas", "quantity": 3}}', '$.taco_order.filling') AS filling,
	JSON_VALUE('{"taco_order": {"filling": "carnitas", "quantity": 3}}', '$.taco_order.quantity') AS quantity;

Result:

| filling  | quantity |
|----------|----------|
| carnitas | 3        |

In this example, we extract the filling and quantity values from a JSON string representing a taco order.

Additional Examples:

-- Extracting a non-existent value (returns empty string by default)
SELECT
	JSON_VALUE('{"taco_order": {"filling": "carnitas"}}', '$.taco_order.sauce') AS sauce;

-- Extracting a complex value (returns empty string by default)
SELECT
	JSON_VALUE('{"taco_order": {"toppings": ["onion", "cilantro"]}}', '$.taco_order.toppings') AS toppings;

This function is particularly useful when you need to extract specific scalar values from JSON data in your queries, especially when working with nested JSON structures.

toJSONString

Serializes a value to its JSON representation.

Syntax:

toJSONString(value)

Arguments:

  • value — Value to serialize. Can be of any data type.

Returns:

  • JSON representation of the value as a String.
  • Supports various data types and nested structures.
  • 64-bit integers or larger (e.g., UInt64, Int128) are enclosed in quotes by default.
  • Special values NaN and inf are replaced with null.
  • When serializing an Enum value, the function outputs its name.

Example:

SELECT
	toJSONString(map('salsa', 'mild', 'guacamole', 'spicy')) AS taco_toppings,
	toJSONString(tuple(3.14, NULL, NaN, +inf, -inf, ['cheese', 'lettuce'])) AS taco_data

Result:

| taco_toppings                           | taco_data                                                  |
|-----------------------------------------|------------------------------------------------------------|
| {"salsa":"mild","guacamole":"spicy"}    | [3.14,null,"nan","inf","-inf",["cheese","lettuce"]]        |

In this example:

  • taco_toppings shows serialization of a Map.
  • taco_data demonstrates serialization of various special values wrapped in a Tuple.

JSONArrayLength

Returns the number of elements in the outermost JSON array.

Syntax:

JSONArrayLength(json)

Alias:

  • JSON_ARRAY_LENGTH(json)

Arguments:

  • json (String): A string containing valid JSON.

Returns:

  • If json is a valid JSON array string, returns the number of array elements. Otherwise, returns NULL. [Nullable(UInt64)]

Example:

SELECT
	JSONArrayLength('') AS empty,
	JSONArrayLength('[1,2,3]') AS array,
	JSONArrayLength('{"taco":"al pastor","toppings":["onion","cilantro","pineapple"]}') AS object

Result:

| empty | array | object |
|-------|-------|--------|
| NULL  | 3     | NULL   |

In this example:

  • An empty string returns NULL.
  • A JSON array [1,2,3] returns 3.
  • A JSON object returns NULL, as it’s not an array.

This function only counts elements in the outermost array. It does not recursively count elements in nested arrays.

jsonMergePatch

Merges multiple JSON objects into a single JSON object string.

Syntax:

jsonMergePatch(json1, json2, ...)

Arguments:

  • json1, json2, … (String): Strings containing valid JSON objects.

Returns:

  • A merged JSON object string if all input JSON strings are valid. (String)

Example:

SELECT
	jsonMergePatch(
		'{"taco_filling":"beef"}',
		'{"taco_toppings": ["cheese", "lettuce"]}',
		'{"taco_toppings": ["salsa", "guacamole"]}',
		'{"taco_sauce": "hot"}'
	) AS merged_taco_json;

Result:

| merged_taco_json                                                                   |
|------------------------------------------------------------------------------------|
| {"taco_filling":"beef","taco_toppings":["salsa","guacamole"],"taco_sauce":"hot"}   |

In this example, we merge multiple JSON objects describing a taco. The function combines all the objects, with later arguments overwriting earlier ones for duplicate keys. Note how the taco_toppings array from the last object containing that key is used in the final result.