MariaDB JSON_INSERT() explicado

En MariaDB, JSON_INSERT() es una función integrada que inserta datos en un documento JSON y devuelve el resultado.

Sintaxis

La sintaxis es así:

JSON_INSERT(json_doc, path, val[, path, val] ...)

Donde json_doc es el documento JSON, path es la ruta donde se deben insertar los datos, y val es el valor que se insertará en esa ruta.

Ejemplo

Aquí hay un ejemplo para demostrarlo.

SET @json_document = '
    { 
        "name": "Wag"
    }
';
SELECT JSON_INSERT(@json_document, '$.type', "Dog");

Resultado:

+----------------------------------------------+
| JSON_INSERT(@json_document, '$.type', "Dog") |
+----------------------------------------------+
| {"name": "Wag", "type": "Dog"}               |
+----------------------------------------------+

Aquí inserté "type": "Dog" en el documento.

En este caso, usé $.type como el camino. Por lo tanto, type es la llave y Dog es el valor.

Cuando la ruta ya existe

Al pasar una ruta que ya existe en el documento JSON, el documento original se devuelve sin cambios.

Ejemplo:

SET @json_document = '
    { 
        "name": "Wag"
    }
';
SELECT JSON_INSERT(@json_document, '$.name', "Bark");

Resultado:

+-----------------------------------------------+
| JSON_INSERT(@json_document, '$.name', "Bark") |
+-----------------------------------------------+
| {"name": "Wag"}                               |
+-----------------------------------------------+

Inserción de matrices

Aquí hay un ejemplo de cómo insertar una matriz en un documento JSON:

SET @json_document = '
    { 
        "name" : "Wag"
    }
';
SELECT JSON_INSERT(@json_document, '$.scores', '[ 8, 7, 9 ]');

Resultado:

+--------------------------------------------------------+
| JSON_INSERT(@json_document, '$.scores', '[ 8, 7, 9 ]') |
+--------------------------------------------------------+
| {"name": "Wag", "scores": "[ 8, 7, 9 ]"}               |
+--------------------------------------------------------+

Adjuntar a matrices

Aquí hay un ejemplo del uso de JSON_INSERT() para agregar datos a una matriz:

SET @json_document = '
    { 
        "_id" : 1, 
        "awards" : [ "Top Dog", "Best Dog" ] 
    }
';
SELECT JSON_INSERT(@json_document, '$.awards[2]', "Biggest Dog");

Resultado:

+--------------------------------------------------------------+
| JSON_INSERT(@json_document, '$.awards[2]', "Biggest Dog")    |
+--------------------------------------------------------------+
| {"_id": 1, "awards": ["Top Dog", "Best Dog", "Biggest Dog"]} |
+--------------------------------------------------------------+

Sin embargo, aunque funcionó bien para este ejemplo, fácilmente podría haber fallado. Por ejemplo, si intentamos insertar el valor en un lugar diferente de la matriz, no funciona:

SET @json_document = '
    { 
        "_id" : 1, 
        "awards" : [ "Top Dog", "Best Dog" ] 
    }
';
SELECT JSON_INSERT(@json_document, '$.awards[1]', "Biggest Dog");

Resultado:

+-----------------------------------------------------------+
| JSON_INSERT(@json_document, '$.awards[1]', "Biggest Dog") |
+-----------------------------------------------------------+
| {"_id": 1, "awards": ["Top Dog", "Best Dog"]}             |
+-----------------------------------------------------------+

Para insertar valores en una matriz, use JSON_ARRAY_INSERT() función en su lugar.

Además, aunque pudimos agregar un valor a una matriz en el ejemplo anterior, probablemente sea mejor que use JSON_ARRAY_APPEND() función, ya que está diseñado específicamente para ese propósito.

Objetos anidados

Aquí hay un ejemplo de cómo insertar un valor en un objeto anidado dentro de otro objeto:

SET @json_document = '
    { 
        "_id" : 1, 
        "name" : "Wag", 
        "details" : {
            "type" : "Dog", 
            "weight" : 20,
            "awards" : { 
                "Florida Dog Awards" : "Top Dog", 
                "New York Marathon" : "Fastest Dog"
            }
        }
    }
';
SELECT JSON_INSERT(
    @json_document, 
    '$.details.awards.Sumo 2020',
    'Biggest Dog'
    );

Resultado:

{"_id": 1, "name": "Wag", "details": {"type": "Dog", "weight": 20, "awards": {"Florida Dog Awards": "Top Dog", "New York Marathon": "Fastest Dog", "Sumo 2020": "Biggest Dog"}}}

Embellece el resultado

Podemos usar el JSON_DETAILED() función para que el resultado sea más fácil de leer:

SET @json_document = '
    { 
        "_id" : 1, 
        "name" : "Wag", 
        "details" : {
            "type" : "Dog", 
            "weight" : 20,
            "awards" : { 
                "Florida Dog Awards" : "Top Dog", 
                "New York Marathon" : "Fastest Dog"
            }
        }
    }
';
SELECT 
    JSON_DETAILED(
        JSON_INSERT(
            @json_document, 
            '$.details.awards.Sumo 2020',
            'Biggest Dog'
        )
    );

Resultado:

{
    "_id": 1,
    "name": "Wag",
    "details": 
    {
        "type": "Dog",
        "weight": 20,
        "awards": 
        {
            "Florida Dog Awards": "Top Dog",
            "New York Marathon": "Fastest Dog",
            "Sumo 2020": "Biggest Dog"
        }
    }
}

Argumentos nulos

Si alguno de los json_document o path los argumentos son NULL , el resultado es NULL :

SELECT 
    JSON_INSERT(null, '$.type', 'Dog'),
    JSON_INSERT('{"a":1}', null, 'Dog');

Resultado:

+------------------------------------+-------------------------------------+
| JSON_INSERT(null, '$.type', 'Dog') | JSON_INSERT('{"a":1}', null, 'Dog') |
+------------------------------------+-------------------------------------+
| NULL                               | NULL                                |
+------------------------------------+-------------------------------------+

Sin embargo, si el value el argumento es NULL , la clave se agrega en la ruta especificada, con un valor de null :

SELECT JSON_INSERT('{"a":1}', '$.type', null);

Resultado:

+----------------------------------------+
| JSON_INSERT('{"a":1}', '$.type', null) |
+----------------------------------------+
| {"a": 1, "type": null}                 |
+----------------------------------------+

Recuento de parámetros incorrecto

No proporcionar argumentos da como resultado un error:

SELECT JSON_INSERT();

Resultado:

ERROR 1582 (42000): Incorrect parameter count in the call to native function 'JSON_INSERT'

Es lo mismo cuando proporciona muy pocos o demasiados argumentos:

SELECT JSON_INSERT('{ "a": 1}');

Resultado:

ERROR 1582 (42000): Incorrect parameter count in the call to native function 'JSON_INSERT'

Funciones similares

El JSON_REPLACE() La función puede actualizar los datos existentes.

El JSON_SET() La función puede actualizar los datos existentes e insertar nuevos datos. Entonces JSON_SET() es como JSON_INSERT() y JSON_REPLACE() en una función.