12.18.5 JSON 値属性を返す関数

JSON_DEPTH(json_doc)

JSON ドキュメントの最大深度を返します。引数が NULL の場合、NULL を返します。引数が有効な JSON ドキュメントでない場合は、エラーが発生します。

空の配列、空のオブジェクトまたはスカラー値の深さは 1 です。深さ 1 の要素のみを含む空でない配列、または深さ 1 のメンバー値のみを含む空でないオブジェクトは深さ 2 です。それ以外の場合、JSON ドキュメントの深さは 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 ドキュメントの長さを戻します。path 引数が指定されている場合は、パスで識別されるドキュメント内の値の長さを戻します。いずれかの引数が NULL の場合、または path 引数がドキュメント内の値を識別しない場合、NULL を返します。 json_doc 引数が有効な JSON ドキュメントでないか、path 引数が有効なパス式でないか、* または ** ワイルドカードが含まれている場合、エラーが発生します。

ドキュメントの長さは次のように決定されます:

スカラーの長さは 1 です。
配列の長さは配列要素の数です。
オブジェクトの長さは、オブジェクトメンバーの数です。
長さは、ネストされた配列またはオブジェクトの長さをカウントしません。

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 値のタイプを示す utf8mb4 文字列を返します。次に示すように、オブジェクト型、配列型またはスカラー型を指定できます:

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                               |
+---------------------------------------+

引数が NULL の場合、JSON_TYPE() は NULL を返します:

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

引数が有効な JSON 値でない場合は、エラーが発生します:

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.

NULL 以外のエラー以外の結果の場合、次のリストに、考えられる JSON_TYPE() の戻り値を示します:

純粋な JSON 型:
- OBJECT: JSON オブジェクト
- ARRAY: JSON 配列
- BOOLEAN: JSON true および false リテラル
- NULL: JSON null リテラル
数値型:
- INTEGER: MySQL TINYINT, SMALLINT, MEDIUMINT および INT と BIGINT のスカラー
- DOUBLE: MySQL DOUBLE FLOAT スカラー
- DECIMAL: MySQL DECIMAL および NUMERIC スカラー
時間型:
- DATETIME: MySQL DATETIME および TIMESTAMP スカラー
- DATE: MySQL DATE スカラー
- TIME: MySQL TIME スカラー
文字列型:
- STRING: MySQL utf8 文字型スカラー: CHAR, VARCHAR, TEXT, ENUM および SET
バイナリ型:
- BLOB: BINARY, VARBINARY, BLOB および BIT を含む MySQL バイナリ型スカラー
他のすべてのタイプ:
- OPAQUE (raw ビット)

JSON_VALID(val)

値が有効な JSON かどうかを示す 0 または 1 を返します。引数が NULL の場合、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 |
+---------------------+-----------------------+