MySQL JSON_STORAGE_FREE() 函数

MySQL JSON_STORAGE_FREE() 函数返回一个 JSON 列在被 JSON_SET()、JSON_REPLACE() 或 JSON_REMOVE() 更新后所释放的空间。

JSON_STORAGE_FREE() 语法

这里是 MySQL JSON_STORAGE_FREE() 的语法：

JSON_STORAGE_FREE(json)

参数

json

必需的。一个 JSON 文档。它可以是一个 JSON 字符串，或者一个 JSON 列。

返回值

MySQL JSON_STORAGE_FREE() 函数返回一个 JSON 列在被 JSON_SET()、JSON_REPLACE() 或 JSON_REMOVE() 更新后所释放的空间。它可以接受一个 JSON 字符串，或者一个 JSON 列作为参数。

如果参数是一个 JSON 字符串，JSON_STORAGE_FREE() 函数返回 0。

如果参数是一个 JSON 列，JSON_STORAGE_FREE() 函数按如下规则返回：

• 如果列被 JSON_SET()、JSON_REPLACE() 或 JSON_REMOVE() 部分更新，它返回更新后释放的空间。
• 如果列没有被更新过，或者不是使用 JSON_SET()、JSON_REPLACE() 或 JSON_REMOVE() 部分更新，它返回 0.
• 如果列的内容在更新后变的更大了，它返回 0.

如果参数为 NULl， JSON_STORAGE_FREE() 函数返回 NULL。

如果参数 json 不是有效的 JSON 文档，MySQL 将会给出错误。您可以使用 JSON_VALID() 验证 JSON 文档的有效性。

JSON_STORAGE_FREE() 示例

本示例说明了 JSON_STORAGE_FREE() 的用法，以及它和 JSON_STORAGE_SIZE() 的区别。

首先，让我们先创建一个表 test_json_storage_free：

DROP TABLE IF EXISTS test_json_storage_free;
CREATE TABLE test_json_storage_free (
    json_col JSON NOT NULL
);

然后，让我们插入 1 行数据以供测试使用：

INSERT INTO test_json_storage_free
VALUES ('{"x": 1, "y": "abcd"}');

然后，让我们看一下 JSON_STORAGE_SIZE() 和 JSON_STORAGE_FREE() 的返回值：

SELECT
    json_col,
    JSON_STORAGE_SIZE(json_col) AS JSON_STORAGE_SIZE,
    JSON_STORAGE_FREE(json_col) AS JSON_STORAGE_FREE
FROM
    test_json_storage_free;

+-----------------------+-------------------+-------------------+
| json_col              | JSON_STORAGE_SIZE | JSON_STORAGE_FREE |
+-----------------------+-------------------+-------------------+
| {"x": 1, "y": "abcd"} |                26 |                 0 |
+-----------------------+-------------------+-------------------+

我们可以看到，由于数据刚刚插入，也未进行任何更新，因此 JSON_STORAGE_FREE() 函数返回了 0，而 JSON_STORAGE_SIZE 函数返回了占用的空间。

接着，让我们修改一下 JSON 列的值：

UPDATE test_json_storage_free
SET json_col = '{"x": 1, "y": "abcd", "z": 3}';

然后，让我们看一下 JSON_STORAGE_SIZE() 和 JSON_STORAGE_FREE() 的返回值：

SELECT
    json_col,
    JSON_STORAGE_SIZE(json_col) AS JSON_STORAGE_SIZE,
    JSON_STORAGE_FREE(json_col) AS JSON_STORAGE_FREE
FROM
    test_json_storage_free;

+-------------------------------+-------------------+-------------------+
| json_col                      | JSON_STORAGE_SIZE | JSON_STORAGE_FREE |
+-------------------------------+-------------------+-------------------+
| {"x": 1, "y": "abcd", "z": 3} |                34 |                 0 |
+-------------------------------+-------------------+-------------------+

我们可以看到，由于 json_col 列的内容变了，因此 JSON_STORAGE_SIZE() 返回值发生了变化。但是 JSON_STORAGE_FREE() 函数仍然返回了 0，这是因为没有使用 JSON_SET()、JSON_REPLACE() 或 JSON_REMOVE() 更新 json_col 列。

然后，让我们使用 JSON_REMOVE() 删除 json_col 列中的成员 z：

UPDATE test_json_storage_free
SET json_col = JSON_REMOVE(json_col, '$.z');

然后，让我们看一下 JSON_STORAGE_SIZE() 和 JSON_STORAGE_FREE() 的返回值：

SELECT
    json_col,
    JSON_STORAGE_SIZE(json_col) AS JSON_STORAGE_SIZE,
    JSON_STORAGE_FREE(json_col) AS JSON_STORAGE_FREE
FROM
    test_json_storage_free;

+-----------------------+-------------------+-------------------+
| json_col              | JSON_STORAGE_SIZE | JSON_STORAGE_FREE |
+-----------------------+-------------------+-------------------+
| {"x": 1, "y": "abcd"} |                34 |                 8 |
+-----------------------+-------------------+-------------------+

我们可以看到，由于使用 JSON_REPLACE() 更新了 json_col 列的内容，因此 JSON_STORAGE_FREE() 函数返回了 8。