ClickHouse function reference
isValidJSON
Checks whether a string is valid JSON. Syntax:json
(String
): The string to check for JSON validity.
1
if the string is valid JSON, 0
otherwise. [UInt8
]
Example:
JSONHas
Checks if a specified value exists in a JSON document. Syntaxjson
(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 1 if the value exists in the JSON, otherwise 0. (
UInt8
)
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: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.
- 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 the length of the JSON array or JSON object. Returns 0 if the value does not exist or has the wrong type. (
UInt64
)
JSONLength
returns the number of elements in the “taco_fillings” array.
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: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.
- 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 the type of a JSON value as a string, otherwise if the value doesn’t exist it returns Null. (
String
)
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).
JSONExtractUInt
Parses JSON and extracts an unsigned integer value. Syntax: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.
- 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 unsigned integer value if it exists, otherwise it returns 0. (
UInt64
)
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: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.
- 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
Int64
value if it exists, otherwise it returns 0.
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.
JSONExtractFloat
Parses JSON and extracts a floating-point value. Syntax: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.
- 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 a
Float64
value if it exists, otherwise it returns 0.
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: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.
- 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 a Boolean value if it exists, otherwise it returns 0. (
Bool
)
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: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.
- 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.
String
)
Example:
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: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 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.
- An array of strings for taco fillings
- An unsigned 8-bit integer for spice level
- A 64-bit float for taco price
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: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 an array of parsed key-value pairs. (
Array(Tuple(String, value_type))
)
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: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.
Array(String)
)
Example:
JSONExtractKeys
extracts the top-level keys from the JSON object representing a taco order.
To extract keys from a nested 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: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.
- 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.
String
)
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: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
- 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)
)
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.
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.
- 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.
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
(String
): A string containing valid JSON.path
(String
): A string representing the JSON path to search.
1
if the value exists in the JSON document,0
otherwise. [UInt8
]
JSON_EXISTS
checks if the taco_fillings
array exists in the JSON document. The result 1
indicates that it does exist.
Additional Examples:
JSON_QUERY
Parses a JSON and extracts a value as a JSON array or JSON object. Syntax:json
(String
): A string containing valid JSON.path
(String
): A string representing the JSON path.
String
]
Example:
- 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.
JSON_VALUE
Parses a JSON and extracts a value as a JSON scalar. Syntax:json
(String
): A string containing valid JSON.path
(String
): A string representing the JSON path.
- Returns the extracted value as a JSON scalar if it exists, otherwise an empty string. (
String
)
filling
and quantity
values from a JSON string representing a taco order.
Additional Examples:
toJSONString
Serializes a value to its JSON representation. Syntax:value
— Value to serialize. Can be of any data type.
- 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.
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:- JSON_ARRAY_LENGTH(json)
json
(String
): A string containing valid JSON.
- If
json
is a valid JSON array string, returns the number of array elements. Otherwise, returns NULL. [Nullable(UInt64)
]
- 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:json1
,json2
, … (String
): Strings containing valid JSON objects.
- A merged JSON object string if all input JSON strings are valid. (
String
)
taco_toppings
array from the last object containing that key is used in the final result.