Catégories :

Fonctions de données semi-structurées et structurées (tableau/objet)

ARRAY_INSERT

Renvoie un tableau contenant tous les éléments du tableau source ainsi que le nouvel élément.

Syntaxe

ARRAY_INSERT( <array> , <pos> , <new_element> )
Copy
Voir aussi :

ARRAY_APPEND , ARRAY_PREPEND

Arguments

array

Le tableau source.

pos

Une position (basée sur zéro) dans le tableau source. Le nouvel élément est inséré à cette position. L’élément d’origine à partir de cette position (le cas échéant) et tous les éléments suivants (le cas échéant) sont décalés d’une position vers la droite dans le tableau résultant (l’insertion à la position 0 a le même effet que l’utilisation de ARRAY_PREPEND).

Une position négative est interprétée comme un index à l’arrière du tableau (par exemple, -1 entraîne l’insertion avant le dernier élément du tableau).

new_element

L’élément à insérer. Le nouvel élément est situé à la position pos. L’ordre relatif des autres éléments du tableau source est préservé.

Renvoie

Le type de données de la valeur renvoyée est ARRAY.

Notes sur l’utilisation

  • Lorsque vous transmettez un ARRAY structuré à la fonction, celle-ci renvoie un ARRAY structuré du même type.

  • Si array est un ARRAY structuré, le type du nouvel élément doit être coercible (pouvoir être contraint à se transformer) dans le type du ARRAY.

  • Si la valeur absolue de pos dépasse le nombre d’éléments du array, des éléments vides supplémentaires sont insérés entre le nouvel élément et les éléments du tableau source.

  • Pour ajouter ou préfixer des éléments à un tableau, vous devez utiliser ARRAY_APPEND ou ARRAY_PREPEND.

Exemples

Ceci montre un exemple simple d’insertion dans un tableau :

SELECT ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),2,'hello');
+--------------------------------------------------+
| ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),2,'HELLO') |
|--------------------------------------------------|
| [                                                |
|   0,                                             |
|   1,                                             |
|   "hello",                                       |
|   2,                                             |
|   3                                              |
| ]                                                |
+--------------------------------------------------+
Copy

Ceci montre une insertion qui utilise un index supérieur au nombre d’éléments existants dans le tableau.

SELECT ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),5,'hello');
+--------------------------------------------------+
| ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),5,'HELLO') |
|--------------------------------------------------|
| [                                                |
|   0,                                             |
|   1,                                             |
|   2,                                             |
|   3,                                             |
|   undefined,                                     |
|   "hello"                                        |
| ]                                                |
+--------------------------------------------------+
Copy

Cela montre une insertion qui utilise un index négatif.

SELECT ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),-1,'hello');
+---------------------------------------------------+
| ARRAY_INSERT(ARRAY_CONSTRUCT(0,1,2,3),-1,'HELLO') |
|---------------------------------------------------|
| [                                                 |
|   0,                                              |
|   1,                                              |
|   2,                                              |
|   "hello",                                        |
|   3                                               |
| ]                                                 |
+---------------------------------------------------+
Copy