Important

You are viewing the archived documentation of TiDB, which no longer receives updates. It is recommended that you use the latest LTS version of the TiDB database.

JSON Functions

Warning

This is still an experimental feature. It is recommended not to use this feature in the production environment.

TiDB supports most of the JSON functions that shipped with the GA release of MySQL 5.7. Additional JSON functions were added to MySQL 5.7 after its release, and not all are available in TiDB (see unsupported functions).

Functions that create JSON values

Function Name and Syntactic Sugar	Description
JSON_ARRAY([val[, val] ...])	Evaluates a (possibly empty) list of values and returns a JSON array containing those values
JSON_OBJECT(key, val[, key, val] ...)	Evaluates a (possibly empty) list of key-value pairs and returns a JSON object containing those pairs
JSON_QUOTE(string)	Returns a string as a JSON value with quotes

Functions that search JSON values

Function Name and Syntactic Sugar	Description
JSON_CONTAINS(target, candidate[, path])	Indicates by returning 1 or 0 whether a given candidate JSON document is contained within a target JSON document
JSON_CONTAINS_PATH(json_doc, one_or_all, path[, path] ...)	Returns 0 or 1 to indicate whether a JSON document contains data at a given path or paths
JSON_EXTRACT(json_doc, path[, path] ...)	Returns data from a JSON document, selected from the parts of the document matched by the `path` arguments
->	Returns the value from a JSON column after the evaluating path; the syntactic sugar of `JSON_EXTRACT(doc, path_literal)`
->>	Returns the value from a JSON column after the evaluating path and unquoting the result; the syntactic sugar of `JSON_UNQUOTE(JSON_EXTRACT(doc, path_literal))`
JSON_KEYS(json_doc[, path])	Returns the keys from the top-level value of a JSON object as a JSON array, or, if a path argument is given, the top-level keys from the selected path
JSON_SEARCH(json_doc, one_or_all, search_string)	Search a JSON document for one or all matches of a string

Functions that modify JSON values

Function Name and Syntactic Sugar	Description
JSON_APPEND(json_doc, path, value)	An alias to `JSON_ARRAY_APPEND`
JSON_ARRAY_APPEND(json_doc, path, value)	Appends a value to the end of a JSON array at a specified path
JSON_INSERT(json_doc, path, val[, path, val] ...)	Inserts data into a JSON document and returns the result
JSON_MERGE(json_doc, json_doc[, json_doc] ...)	A deprecated alias for `JSON_MERGE_PRESERVE`
JSON_MERGE_PRESERVE(json_doc, json_doc[, json_doc] ...)	Merges two or more JSON documents and returns the merged result
JSON_REMOVE(json_doc, path[, path] ...)	Removes data from a JSON document and returns the result
JSON_REPLACE(json_doc, path, val[, path, val] ...)	Replaces existing values in a JSON document and returns the result
JSON_SET(json_doc, path, val[, path, val] ...)	Inserts or updates data in a JSON document and returns the result
JSON_UNQUOTE(json_val)	Unquotes a JSON value and returns the result as a string

Functions that return JSON value attributes

Function Name and Syntactic Sugar	Description
JSON_DEPTH(json_doc)	Returns the maximum depth of a JSON document
JSON_LENGTH(json_doc[, path])	Returns the length of a JSON document, or, if a path argument is given, the length of the value within the path
JSON_TYPE(json_val)	Returns a string indicating the type of a JSON value

Unsupported functions

The following JSON functions are unsupported in TiDB. You can track the progress in adding them in TiDB #7546:

JSON_ARRAY_INSERT
JSON_MERGE_PATCH
JSON_PRETTY
JSON_STORAGE_SIZE
JSON_VALID
JSON_ARRAYAGG
JSON_OBJECTAGG