### 12.18.5 Functions That Return JSON Value Attributes

 The functions in this section return attributes of JSON values.

* []()

  [`JSON_DEPTH(*`json_doc`*)`](json-attribute-functions.html#function_json-depth)

  []()

   Returns the maximum depth of a JSON document. Returns `NULL` if the argument is `NULL`. An error occurs if the argument is not a valid JSON document.

   An empty array, empty object, or scalar value has depth 1. A nonempty array containing only elements of depth 1 or nonempty object containing only member values of depth 1 has depth 2. Otherwise, a JSON document has depth greater than 2.

  ```
  mysql> SELECT JSON_DEPTH('{}'), JSON_DEPTH('[]'), JSON_DEPTH('true');
  +------------------+------------------+--------------------+
  | JSON_DEPTH('{}') | JSON_DEPTH('[]') | JSON_DEPTH('true') |
  +------------------+------------------+--------------------+
  |                1 |                1 |                  1 |
  +------------------+------------------+--------------------+
  mysql> SELECT JSON_DEPTH('[10, 20]'), JSON_DEPTH('[[], {}]');
  +------------------------+------------------------+
  | JSON_DEPTH('[10, 20]') | JSON_DEPTH('[[], {}]') |
  +------------------------+------------------------+
  |                      2 |                      2 |
  +------------------------+------------------------+
  mysql> SELECT JSON_DEPTH('[10, {"a": 20}]');
  +-------------------------------+
  | JSON_DEPTH('[10, {"a": 20}]') |
  +-------------------------------+
  |                             3 |
  +-------------------------------+
  ```

* []()

  [`JSON_LENGTH(*`json_doc`*[, *`path`*])`](json-attribute-functions.html#function_json-length)

  []()

   Returns the length of a JSON document, or, if a *`path`* argument is given, the length of the value within the document identified by the path. Returns `NULL` if any argument is `NULL` or the *`path`* argument does not identify a value in the document. An error occurs if the *`json_doc`* argument is not a valid JSON document or the *`path`* argument is not a valid path expression. Prior to MySQL 8.0.26, an error is also raised if the path expression contains a `*` or `**` wildcard.

   The length of a document is determined as follows:

  * The length of a scalar is 1.

  * The length of an array is the number of array elements.

  * The length of an object is the number of object members.

  * The length does not count the length of nested arrays or objects.

  ```
  mysql> SELECT JSON_LENGTH('[1, 2, {"a": 3}]');
  +---------------------------------+
  | JSON_LENGTH('[1, 2, {"a": 3}]') |
  +---------------------------------+
  |                               3 |
  +---------------------------------+
  mysql> SELECT JSON_LENGTH('{"a": 1, "b": {"c": 30}}');
  +-----------------------------------------+
  | JSON_LENGTH('{"a": 1, "b": {"c": 30}}') |
  +-----------------------------------------+
  |                                       2 |
  +-----------------------------------------+
  mysql> SELECT JSON_LENGTH('{"a": 1, "b": {"c": 30}}', '$.b');
  +------------------------------------------------+
  | JSON_LENGTH('{"a": 1, "b": {"c": 30}}', '$.b') |
  +------------------------------------------------+
  |                                              1 |
  +------------------------------------------------+
  ```

* []()

  [`JSON_TYPE(*`json_val`*)`](json-attribute-functions.html#function_json-type)

  []()

   Returns a `utf8mb4` string indicating the type of a JSON value. This can be an object, an array, or a scalar type, as shown here:

  ```
  mysql> SET @j = '{"a": [10, true]}';
  mysql> SELECT JSON_TYPE(@j);
  +---------------+
  | JSON_TYPE(@j) |
  +---------------+
  | OBJECT        |
  +---------------+
  mysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a'));
  +------------------------------------+
  | JSON_TYPE(JSON_EXTRACT(@j, '$.a')) |
  +------------------------------------+
  | ARRAY                              |
  +------------------------------------+
  mysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]'));
  +---------------------------------------+
  | JSON_TYPE(JSON_EXTRACT(@j, '$.a[0]')) |
  +---------------------------------------+
  | INTEGER                               |
  +---------------------------------------+
  mysql> SELECT JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]'));
  +---------------------------------------+
  | JSON_TYPE(JSON_EXTRACT(@j, '$.a[1]')) |
  +---------------------------------------+
  | BOOLEAN                               |
  +---------------------------------------+
  ```

  [`JSON_TYPE()`](json-attribute-functions.html#function_json-type) returns `NULL` if the argument is `NULL`:

  ```
  mysql> SELECT JSON_TYPE(NULL);
  +-----------------+
  | JSON_TYPE(NULL) |
  +-----------------+
  | NULL            |
  +-----------------+
  ```

   An error occurs if the argument is not a valid JSON value:

  ```
  mysql> SELECT JSON_TYPE(1);
  ERROR 3146 (22032): Invalid data type for JSON data in argument 1
  to function json_type; a JSON string or JSON type is required.
  ```

   For a non-`NULL`, non-error result, the following list describes the possible [`JSON_TYPE()`](json-attribute-functions.html#function_json-type) return values:

  * Purely JSON types:

    * `OBJECT`: JSON objects

    * `ARRAY`: JSON arrays

    * `BOOLEAN`: The JSON true and false literals

    * `NULL`: The JSON null literal

  * Numeric types:

    * `INTEGER`: MySQL [`TINYINT`](integer-types.html), [`SMALLINT`](integer-types.html), [`MEDIUMINT`](integer-types.html) and [`INT`](integer-types.html) and [`BIGINT`](integer-types.html) scalars

    * `DOUBLE`: MySQL [`DOUBLE`](floating-point-types.html) [`FLOAT`](floating-point-types.html) scalars

    * `DECIMAL`: MySQL [`DECIMAL`](fixed-point-types.html) and [`NUMERIC`](fixed-point-types.html) scalars

  * Temporal types:

    * `DATETIME`: MySQL [`DATETIME`](datetime.html) and [`TIMESTAMP`](datetime.html) scalars

    * `DATE`: MySQL [`DATE`](datetime.html) scalars

    * `TIME`: MySQL [`TIME`](time.html) scalars

  * String types:

    * `STRING`: MySQL `utf8` character type scalars: [`CHAR`](char.html), [`VARCHAR`](char.html), [`TEXT`](blob.html), [`ENUM`](enum.html), and [`SET`](set.html)

  * Binary types:

    * `BLOB`: MySQL binary type scalars including [`BINARY`](binary-varbinary.html), [`VARBINARY`](binary-varbinary.html), [`BLOB`](blob.html), and [`BIT`](bit-type.html)

  * All other types:

    * `OPAQUE` (raw bits)

* []()

  [`JSON_VALID(*`val`*)`](json-attribute-functions.html#function_json-valid)

  []()

   Returns 0 or 1 to indicate whether a value is valid JSON. Returns `NULL` if the argument is `NULL`.

  ```
  mysql> SELECT JSON_VALID('{"a": 1}');
  +------------------------+
  | JSON_VALID('{"a": 1}') |
  +------------------------+
  |                      1 |
  +------------------------+
  mysql> SELECT JSON_VALID('hello'), JSON_VALID('"hello"');
  +---------------------+-----------------------+
  | JSON_VALID('hello') | JSON_VALID('"hello"') |
  +---------------------+-----------------------+
  |                   0 |                     1 |
  +---------------------+-----------------------+
  ```

