$sql.insert¶

Description¶

Exécute une requête de type INSERT et retourne une table contenant les clés primaires des nouvelles entrées

1
2

$sql.insert(`insert into Destination(Col1, col2)
             select Col1, Col2 from Source`::T);

1
2
3

insert into Destination(Col1, col2)
select Col1, Col2 from Source
RETURNING ROWID INTO :1

Syntaxe¶

$sql.insert( query [ , data [ , options ] ] )

Paramètres¶

query string

Requête à évaluer

data array / map / string / number / date / time / timestamp / file

Jeu de données à passer à la requête (dans le cas où la requête utilise la notation des prepared statements - ce qui est recommandé)

Le paramètre peut prendre plusieurs formes en fonction de la requête sur laquelle il doit s'appliquer:

• Valeur null: La requête n'attend pas de paramètre ou n'utilise pas la syntaxe des prepared statement
• Valeur litérale unique: La requête n'attend qu'un seul paramètre de type simple (string, number, date, time, timestamp ou file)
• Tableau 1D: Dans ce cas, les valeurs du tableau sont reprises dans l'ordre comme valeurs pour le prepared statement.
• Tableau 2D (tableau de tableau 1D) : La méthode comprend que l'on souhaite évaluer plusieurs fois la requête. Elle boucle sur les lots de données dans l'ordre et évalue la requête avec chacun des lots disponibles. Par exemple, si le tableau vaut [[1,2],[3,4]], la méthode va évaluer la requête 2 fois : la première fois avec les valeurs 1 et 2, et la seconde fois avec les valeur 3 et 4.
• Map : Ce cas s'applique si la requête référence des paramètres nommés.
• Tableau de map : Cette syntaxe permet de passer plusieurs jeux de données à la fois, en utilisant la notation avec des paramètres nommés. Dans ce cas, la méthode est évaluée autant de fois qu'il y a de maps dans le tableau.

Veuillez prendre connaissance de la note traitant de la valeur null dans la documentation de $sql.select.

options map

Map d'options supplémentaires. Les options reconnues sont:

batch boolean

Demande à la méthode d'exécuter le statement en tant que batch, avec auto-commit désactivé (un commit global est réalisé à la fin de traitement du batch).

Ce mode apporte un gain de performances significatif lorsqu'il s'agit d'insérer de grandes quantités de données (voir l'exemple 2 donné plus bas).

Par contre les data ne peuvent être fournis que sous la forme d'une matrice (c-à-d. un tableau de tableaux). Si les données contiennent des maps, le traitement ne sera pas effectué sous forme de batch.

En outre, la valeur de retour ne fournira pas de détail sur les insertions effectuées. La méthode retourne simplement true.

timeout number

Temps maximum (en secondes) autorisé pour l'exécution de la requête

connection string

Nom de connexion de laquelle tirer les paramètres de connexion. Doit référencer une connexion définie dans le fichier de configuration

dumpLevel string

Cette option permet d'afficher la requête dans le log. La valeur de l'option doit désigner un niveau de log parmi (trace, debug, info, warn ou error)

Retour¶

Matrice contenant les valeurs des clés générées. Retourne true si le mode batch est activé.

⚠️ Attention, le retour de la méthode peut varier selon le type de SGBD utilisé. Ainsi sur SQLite, la valeur de retour est un array ayant la forme suivante:

[{"last_insert_rowid()":2431}]

Cette valeur ne constitue pas la clé primaire de la table, mais elle permet de retrouver le tuple généré au moyen d'une requête du genre

select pk1, pk2, ... from table where rowid=?

où pk1, pk2, etc. sont les colonnes contenant la clé primaire et table est le nom de la table sur laquelle l'insertion a été faite.

Exemple¶

Exemple 1¶

1
2
3

$sql.insert("insert into sample(col1, col2) values(?, ?)",
            [ 1, "o'reilly" ],
            { dumpLevel: 'warn' });

Le code ci-dessus génère la trace de log suivante (peut varier en fonction de la configuration du logger) et effectue une insertion dans la table indiquée:

WARN  - ch.epilogic.ewt.scripts.library.EwtScriptLibSql.log():238 - insert into sample(col1, col2) values(1, 'o''reilly')

Exemple 2¶

Le code ci-dessous donne un exemple qui compare le temps d'exécution pour l'insertion de 20'000 entrées sur une table.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// préparation du dataset
var data = [];
for (var i = 0; i < 20000; ++i) {
    data += [ 'Lastname-${i}', 'Firstname-${i}' ];
}

try {
    $sql.update(`create table test_batch(lastname varchar(20), firstname varchar(20))`);

    // exécution standard
    var beg = $cal.timestamp();
    $sql.insert(`insert into test_batch(lastname, firstname) values(?,?)`,
                data, { batch: false });
    $logger.info("Exécution standard: " & $cal.diff(beg, $cal.timestamp(), "ms") & " ms");

    $sql.update(`truncate table test_batch`);

    // exécution batch
    beg = $cal.timestamp();
    $sql.insert(`insert into test_batch(lastname, firstname) values(?,?)`,
                data, { batch: true });
    $logger.info("Exécution batch: " & $cal.diff(beg, $cal.timestamp(), "ms") & " ms");
}
finally {
    $sql.update(`drop table if exists test_batch`);
}

Le script génère les traces suivantes:

Exécution standard: 32052 ms
Exécution batch: 156 ms