JSONExtract functions
Parse ordinary JSON with full compatibility.
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:
Arguments:
json
(String
): The string to check for JSON validity.
Returns:
1
if the string is valid JSON, 0
otherwise. [UInt8
]
Example:
Result:
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
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
Result:
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:
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:
Result:
In this example, JSONLength
returns the number of elements in the “taco_fillings” array.
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
Result:
In this example, JSONExtractKeys
extracts the top-level keys from the JSON object representing a taco order.
To extract keys from a nested object:
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
Result:
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:
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:
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:
Result:
This example extracts the “taco_fillings” array from the JSON object.
Result:
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.
Result:
JSON_VALUE
Parses a JSON and extracts a value as a JSON scalar.
Syntax:
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:
Result:
In this example, we extract the filling
and quantity
values from a JSON string representing a taco order.
Additional Examples:
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:
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
andinf
are replaced withnull
. - When serializing an
Enum
value, the function outputs its name.
Example:
Result:
In this example:
taco_toppings
shows serialization of aMap
.taco_data
demonstrates serialization of various special values wrapped in aTuple
.
JSONArrayLength
Returns the number of elements in the outermost JSON array.
Syntax:
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:
Result:
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:
Arguments:
json1
,json2
, … (String
): Strings containing valid JSON objects.
Returns:
- A merged JSON object string if all input JSON strings are valid. (
String
)
Example:
Result:
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.
Was this page helpful?