Skip to content

$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 / pojo
Requête à évaluer OU référence de prepared statement obtenue par $sql.prepareStatement.
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.

Valeur null

Comme indiqué ci-dessus, le fait de passer la valeur null comme paramètre indique que l'on ne souhaite pas passer de paramètre du tout. En général on pourra se passer de spécifier le 2e paramètre tant qu'on ne veut pas passer d'options (3e paramètre).

Ainsi, dans l'appel suivant

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

le 2e paramètre ne désigne pas une valeur null que l'on voudrait passer comme paramètre au statement, mais il s'agit uniquement d'une valeur à ignorer, mais nécessaire pour permettre de passer le 3e paramètre à la méthode. On pourrait dans ce cas également passer un tableau ou un map vide comme 2e paramètre:

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

Cependant, comment passer une valeur null statement ? Dans ce cas, on spécifiera la valeur null via un tableau, comme dans l'exemple suivant:

1
$sql.select("insert into Tbl(col1) values(?)", [ null ]});

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:

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

Le statement devra être changé en

1
$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

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