`$sql.select`¶

Description¶

Exécute une requête SQL de type SELECT sur la base de données et retourne la toute première valeur du resultset (pour autant que la requête retourne des résultats).

Peut également être utilisé dans le cas de requêtes INSERT ayant une clause RETURNING.

Syntaxe¶

$sql.select( query [ , data [ , option ] ] )

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 litérale: La requête n'attend pas de paramètre ou n'utilise pas la syntaxe des prepared statement
Valeur null calculée: La valeur null est passée comme paramètre unique au statement (voir remarque ci-dessous)
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.

Valeur null

Remarque préliminaire : cette note ne concerne que le cas où le second paramètre est une valeur unique; elle ne concerne pas le cas où le paramètre est un array ou un map.

Comme indiqué ci-dessus, le moteur interprète différemment une valeur null passée en second paramètre selon qu'elle est litérale ou calculée.

Dans le cas d'une valeur litérale (c'est-à-dire si on écrit explicitement null dans le code ewts), le moteur ignorera la valeur et ne passera aucun paramètre au statement. En effet, le moteur considère que cette valeur sert uniquement à pouvoir passer un troisième paramètre à la méthode, comme dans l'exemple suivant:

$sql.select("select 'a'", null, { defval: 'b' });

Si le statement attend un paramètre et qu'on passe la valeur litérale null, cela provoquera une erreur:

$sql.select("select ?", null, { defval: 'b' });
// --> provoque une erreur SQL

Par contre, si la valeur null passée en second paramètre est le résultat d'un calcul, le moteur considère qu'il s'agit d'un paramètre à fournir au statement. Ainsi, le code suivant ne provoquera pas d'erreur:

$sql.select(`select ?`,
            $session.getPersistentObject("variable_inexistante"),
            { defval: "defval" });

Pour éviter les mauvaises interprétations, il est recommandé de toujours passer un array ou un map en 2e paramètre. Ainsi, les exemples précédents pourraient être réécris ainsi:

$sql.select("select 'a'", [], { defval: 'b' });
$sql.select("select ?", [ null ], { defval: 'b' });
$sql.select(`select ?`,
            [ $session.getPersistentObject("variable_inexistante") ],
            { defval: "defval" });

Veuillez noter que le fait de passer une valeur null en paramètre de statement n'est pas toujours correct. Par exemple, l'exemple suivant n'est pas correct car il ne respecte pas la syntaxe SQL:

$sql.select("select count(*) from Tbl where col1 = ?", [ null ]});

Le statement devra être changé en

$sql.select("select count(*) from Tbl where col1 is null");

options map

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

timeout number: Temps maximum (en secondes) autorisé pour l'exécution de la requête
nullSubst any: Valeur à retourner si le résultat de la requête est null
errorSubst any: Valeur à retourner dans le cas où la requête génère une erreur ou part en timeout
defval any: Cette option cumule les effets de nullSubst et de errorSubst: elle permet de spécifier la valeur par défaut à retourner dans le cas où la requête génère une erreur, part en timeout ou engendre un résultat null. En cas de conflit entre les propriétés, nullSubst et errorSubst priment sur defval.
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¶

Valeur de la première valeur (première colonne de la première ligne) du resultset retourné par la requête.

Exemple¶

$sql.select("select count(*) from Personne where nom=?", [ 'Dupont' ])

$sql.select¶