`$sql.mselect`¶

Description¶

Exécute une requête SQL de type SELECT sur la base de données et retourne une matrice des résultats.

La méthode est une variante de $sql.msql spécifique aux requêtes de type SELECT.

Syntaxe¶

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

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.

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:

timeout number

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

defval any

Valeur par défaut à retourner dans le cas où la requête génère une erreur ou part en timeout

format string

Format de sortie; les formats disponibles sont:

matrix

Mode par défaut. Retourne une matrice, c'est-à-dire un tableau de tableau (ou plus exactement, un array d'array). La valeur de retour aura donc la forme [ [ u1, u2, ... ] , [ v1, v2, ... ] , ... ]

array

Retourne un tableau 1D, ou, dit autrement, un tableau ne contenant qu'une seule colonne. Les colonnes 2 et suivantes du result set sont ignorées. La valeur de retour aura donc la forme [ u1, v1, ... ]

object (ou maps)

Retourne un tableau de map dans lequel les propriétés correspondent aux colonnes du résultat. La valeur de retour sera donc un objet que l'on peut représenter ainsi: [ { u1: ..., u2: ..., ... }, { v1: ..., v2: ..., ... }, ... ].

Par défaut, les propriétés sont nommées col0, col1, etc. Il est possible de reprendre les noms de colonnes en spécifiant l'option header: true (voir ci-dessous). À noter que dans ce cas les noms sont forcés en minuscules.

xml

Retourne un arbre xml

html

Retourne une table html (les valeurs sont échappées selon la syntaxe html, par exemple un "é" sera échappé en "é")

xhtml

Retourne une table html (les valeurs sont échappées selon la syntaxe une syntaxe compatible xml, ainsi un "é" sera échappé en "é")

json

Retourne un arbre JSON

csv

Retourne les données au format CSV

text

Retourne une représentation de la table sous forme de chaîne de caractère structurée en forme de table.

Le format est en fait un raccourci qui effectue un appel à $array.stringify.

auto

Retourne une matrice lorsque les données contiennent plusieurs lignes ou plusieurs colonnes, ou une valeur unique dans le cas où le résultat se limite à une seule valeur

header string / boolean

Cette option joue un rôle différent selon le format de sortie (selon valeur de format ci-dessus):

auto : Sans effet (l'option est ignorée)
matrix : Valeur true/false indiquant s'il faut reprendre les noms de colonnes à la première ligne
array : Valeur true/false indiquant s'il faut reprendre les noms de colonnes à la première ligne
object : Valeur true/false indiquant s'il faut reprendre les noms de colonnes en tant que nom de propriétés
xml : Si la valeur de header est true, alors la méthode reprend les noms de colonnes comme noms de balises (à la place des col0, col1, etc.)

Si la valeur est préfixée par head:, alors la méthode ajoute un bloc d'entête portant le nom indiqué après head: et y spécifie les noms de colonnes

Si la valeur header est préfixée par attr:, alors la méthode ajoute sur chaque élément col0, col1, etc. un attribut ayant pour nom la valeur indiquée après attr: et pour valeur le nom de la colonne
html : header est alors interprété comme un flag dont la valeur true/false indique s'il faut reprendre les noms de colonnes dans une ligne d'entête.
xhtml : Identique au cas où format vaut html
json : Pour le format json, si la valeur vaut true, alors les valeurs sont retournées sous la forme d'un objet où la clé reprend le nom de colonne; sinon les valeurs sont retournées dans un tableau.

Si la valeur est préfixée par head:, alors la méthode ajoute un élément décrivant les noms de colonnes; l'élément en question est nommé selon la valeur indiquée après head:.

Si la valeur est une valeur numérique, la méthode génère un map au format json en reprenant la valeur de la colonne indiquée en tant que clé. Les autres valeurs sont reprises sous forme de table ou de valeur simple dans le cas où le resultset ne contient que deux colonnes. Les indices de colonnes sont 0-based.
csv : Pour le format csv, la valeur header est considérée comme un flag true/false indiquant s'il faut reprendre les noms de colonne à la première ligne.

headercase string

Casse à appliquer aux noms de colonnes reprises dans le header.

Par défaut les noms de colonnes sont repris dans la casse fournie par le serveur de base de données. Cela peut être un problème si votre application doit utiliser deux systèmes de base de données différents (par exemple pour le dev et la prod). Il peut donc être intéressant de forcer les noms de colonnes à toujours être repris dans une même casse. Il est possible de forcer une conversion avec l'une des valeurs suivantes:

lower: les noms de colonnes sont convertis en minuscules
upper: les noms de colonnes sont convertis en majuscules

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.

escape boolean

Flag true/false indiquant si les valeurs doivent être échappeés. L'option est active par défaut pour les formats xml, html et xhtml, mais sans effet pour les autres formats.

sanitize string / map / pojo

Règle de nettoyage de valeur. La valeur de la propriété peut être soit:

une string, auquel cas Ewt s'attend à ce que la valeur utilise la même syntaxe que pour les règles de validation de champs de type "rule", par exemple "FORMATTING|BLOCKS"

un objet map ou array décrivant des règles, par exemple:

[
    { allowAttributes: "class", onElements: "i" },
    { requireRelNofollowOnLinks: true },
    { allowElements: [ "i" ] }
]

un objet java (pojo) référençant des règles; l'objet en question peut être construit à l'aide de la méthode $secu.buildSanitizePolicy

Exemple:

var sanitizePolicy = $secu.buildSanitizePolicy(
    [
        { allowAttributes: "class", onElements: "i" }
    ]
);

return $sql.mselect(query, [ input ],
                    { format: "xhtml", escape: false,
                      sanitize: sanitizePolicy });

Le paramètre peut être null, auquel cas la méthode applique un mode par défaut qui englobe tous les types d'éléments html standards.

Ne s'applique qu'aux formats xml, html et xhtml.

attributes map

Cette option permet d'indiquer un ou plusieurs attributs à reprendre dans l'élément racine créé dans le cas des formats xml, html ou xhtml. L'objet doit se présenter sous la forme d'un dictionnaire représentant les noms et valeurs d'attributs (p.ex: { "class": "search-result" })

Remarque : les options escape et sanitize s'appliquent aux valeurs des attributs (mais pas aux noms d'attributs)

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¶

Par défaut: matrice (ou tableau de tableaux) contenant le résultat.

Le type de sortie dépend grandement des options passées lors de l'appel.

Exemple¶

var res = $sql.mselect(`select ${queryParts.select}
                        from ${queryParts.from}
                        where ${queryParts.where}
                        order by ${queryParts.order}
                        limit ${this.options.rowNumber}
                        offset ${this.options.rowOffset}`,
                       queryParts.inputs,
                       { format: "xml", header: "attr:name",
                         escape: true, sanitize: this.options.sanitizePolicy });

$sql.mselect¶