XQuery dans SQL Server 2005

XQuery est basé sur XPath 2.0, un langage permettant de parcourir le document pour retrouver un nœud ou une valeur atomique. Vous pouvez très simplement dessiner un chemin d'élément à sous-élément et filtrer le nœud recherché. Le filtrage se fait à l'aide d'un prédicat contenu entre crochets [], qui applique son contenu (une expression évaluée à vrai ou faux) au contexte du chemin.
Par exemple, dans notre XML, le chemin pour trouver le premier coup du troisième pion blanc peut être exprimé en XPath ainsi :

/echiquier/blancs/pieces/pion[@numero = "3"]/historique/coup[@sequence = "1"]

Un chemin est composé d'une suite de nœuds (des étapes) séparés par des /. Chaque étape comporte un axe, qui spécifie la direction du mouvement, un test de nœud (le QName de l'élément ou de l'attribut) et peut introduire des expressions de filtre, nommées qualificateurs d'étapes (step qualifiers). L'axe peut être explicite, ou abrégé. Ainsi, l'exemple ci-dessus avec axes explicites donne :

self : :node()/child : :echiquier/child::blancs/child::pieces/child::pion[attribute::numero = "3"]
/child::historique/child::coup[attribute::sequence = "1"]

:: étant le séparateur d'axe. Vous avez compris que child est l'axe par défaut, et que attribute : : s'abrège « @ ». Le nœud parent s'abrège « .. », et le nœud actuel (le nœud de contexte), « . ».

Vous pouvez également sauter des étapes et chercher des sous-nœuds dans tous les enfants, en utilisant la syntaxe // (déconseillée pour des raisons de performance, et les risques encourus en cas de changement de structure). Pour retourner des nœuds au même niveau mais portant des QNames différents, vous pouvez utiliser le caractère générique *.

Le type XML supporte les espaces de noms (namespaces, recommandation W3C http://www.w3.org/TR/REC-xml-names/), qui sont des identificateurs de vocabulaire, permettant d'attribuer un nœud à un vocabulaire. Si le contenu de la colonne ou de la variable les utilise, la requête XQuery doit déclarer les namespaces avec lesquels elle va travailler. Cette déclaration peut se faire en ligne - à l'intérieur de la requête Xquery - à l'aide d'un prologue, ou en préfixe à la requête SQL (au SELECT) dans laquelle on va écrire des requêtes XQuery. Cette deuxième solution est à préférer pour améliorer la lisibilité du code, et pour éviter une redéclaration dans les diverses requêtes. La recommandation W3C indique que le prologue contient une suite de déclarations diverses séparées par des points-virgules. En SQL Server, il ne peut contenir que des déclarations d'espaces de noms.

Exemple avec une déclaration de namespaces en prologue :

SELECT joueurs.query('
    declare namespace ecj="http://www.babaluga.com/xmlnamespaces/echecs/joueur";
    /joueurs/ecj:joueur[@position = "blancs"]')
FROM #partie

La déclaration en préfixe de la requête utilise la syntaxe SQL suivante :

WITH XMLNAMESPACES ('urn' as alias, 'urn2' as alias2)...

Exemple :

WITH XMLNAMESPACES ('http://www.babaluga.com/xmlnamespaces/echecs/joueur' as e)
SELECT joueurs.query('/joueurs/e:joueur[@position = "blancs"]')
FROM #partie

Le mot-clé WITH étant déjà utilisé dans la syntaxe T-SQL pour spécifier des options de requête par exemple, l'utilisation de WITH XMLNAMESPACES dans un lot de requêtes doit être précédée de la fermeture de l'instruction précédente par un ;.

XQuery permet plusieurs types d'expressions. Outre les expressions primaires, comme les nœuds ou les séquences, et les chemins XPath, vous pouvez évidemment utiliser des opérateurs de comparaison, des opérateurs logiques (or et and) et arithmétiques, des branchements conditionnels (if then else), des quantificateurs (some, every), qui permettent de tester les séquences, ainsi que la structure FLWOR.

La vraie richesse de XQuery fleurit grâce à la syntaxe FLWOR. FLWOR, qu'on prononce flower, permet d'exprimer une requête d'extraction complexe des nœuds XML, un peu à l'image du langage SQL. Il s'agit d'une abréviation mnémotechnique qui indique quel mot-clé peut être utilisé à quelle position dans la requête.
Détaillons l'abréviation :

Les clauses WHERE et ORDER BY sont optionnelles. A minima, une instruction FLWOR est une instruction FR.

Exemple de FLWOR complet, qui retrouve toutes les pièces blanches actuellement dans la colonne B de l'échiquier (dans notre exemple, le roi) :

SELECT echiquier.query('
    for $piece in (/echiquier/blancs/pieces/*)
    where contains($piece/@position,"B")
    order by $piece/@position
    return $piece')
FROM #partie;

Vous noterez que le signe $ est utilisé pour indiquer une variable.

En XQuery, une séquence est une liste de chemins. Une expression XPath qui retourne plusieurs nœuds génère une séquence. Vous pouvez aussi indiquer explicitement une séquence en utilisant un constructeur, c'est-à-dire une liste entre parenthèses contenant des chemins séparés par des virgules. Exemple :

SELECT echiquier.query('
    for $piece in (/echiquier/blancs/pieces/pion, /echiquier/blancs/pieces/roi)
    return $piece')
FROM #partie;

Ce qui est équivalent à :

SELECT echiquier.query('(
/echiquier/blancs/pieces/pion, /echiquier/blancs/pieces/roi)')
FROM #partie;

Une séquence contenant un seul item est nommée un singleton. Parfois, une séquence peut être passée, par exemple dans le for, comme nous venons de le voir, ou comme paramètre de fonction d'agrégation. À d'autres endroits, un singleton est attendu, par exemple en paramètre d'une fonction de chaîne, ou dans la méthode value().

XQuery 1.0 n'offre aucune construction pour modifier le contenu du document XML. Cette possibilité est en travail et sera ajoutée dans une version future. SQL Server implémente sa propre syntaxe additionnelle, nommée XML-DML. De plus, un certain nombre de constructions XQuery ne sont pas supportées (par exemple les opérateurs ensemblistes comme union). Ces limitations sont indiquées dans les Books Online.

query() permet d'appliquer toute la richesse de la syntaxe XQuery pour extraire un nouveau fragment XML du document original. Nous en avons déjà vu des exemples. Voici quelques applications pratiques, montrant les possibilités du langage.

Vous pouvez générer un nouveau fragment XML à la volée, simplement en écrivant des chevrons en littéraux dans votre return, ou dans n'importe quelle expression de retour XQuery. Si vous voulez interpoler le résultat d'une expression, encadrez-la par {}.

SELECT echiquier.query('{/echiquier/blancs/pieces/roi/@position}')
FROM #partie;

Vous noterez en essayant ce code, que le résultat retourne la position en attribut. Ici, /echiquier/blancs/pieces/roi/@position retourne un nœud, qui est un attribut. Or, si vous voulez le « mapper » en élément, vous avez besoin d'extraire la valeur atomique du nœud position, par un processus qu'on appelle atomisation. La fonction d'atomisation est data() :

SELECT echiquier.query('{data(/echiquier/blancs/pieces/roi/@position)}')
FROM #partie;

Dans certains cas, XQuery atomise le résultat par défaut (par exemple en paramètre de fonctions). Parfois, comme ici, nous devons le faire explicitement.

Voyons également l'utilisation des agrégations (sum, min, max, count, avg). Ici un count() :

SELECT echiquier.query('{ count(/echiquier/blancs//historique/coup) }')
FROM #partie;

Vous pouvez au besoin transtyper vos valeurs atomiques en types XML (du namespace xs), en utilisant la syntaxe « cast as type? ». Attention, vous ne pouvez transtyper que des singletons :

SELECT echiquier.query('
(/echiquier/blancs/pieces/pion[@numero = "3"]/historique/coup[@sequence = "1"]/source)[1] cast as xs:string?')
FROM #partie;

Vous pouvez également insérer des valeurs de colonne ou de variable du jeu de résultat relationnel « externe » au type XML, en utilisant les fonctions sql:column() et sql:variable()

SELECT echiquier.query('{sql:column("PartieId")}')
FROM #partie;

Attention, certains types comme datetime et smalldatetime ne sont pas supportés, vous devez les convertir avant de les utiliser dans XQuery.

value() permet d'extraire une valeur de nœud, et de la retourner dans un type de données SQL, spécifié en paramètre. Le chemin doit permettre de retourner une seule valeur. Pour indiquer le singleton de votre chemin, utilisez cette syntaxe : (chemin)[n° de position] (ce qu'on appelle un prédicat de position). Exemple sur un attribut, avec recherche dans le chemin :

SELECT echiquier.value('(/echiquier/blancs/pieces/pion[@numero = "3"]/@position)[1]', 'char(2)')
FROM #partie;

Pour un élément :

SELECT echiquier.value('(/echiquier/blancs/pieces/pion[@numero = "3"]/historique/coup[@sequence = "1"]/source)[1]', 'char(2)')
FROM #partie;

Puisqu'il vous retourne une valeur, value() sera utile dans un SELECT. Pour un test dans une clause WHERE, préférez-lui exist(), les performances sont meilleures.

exist() vous permet, dans une clause WHERE, de tester une existence à l'aide d'une instruction XPath. Un bit vous est retourné.

Test de valeur atomique :

SELECT echiquier.query('/echiquier/blancs/pieces/piece[@position = "B3"]')
FROM #partie
WHERE echiquier.exist('/echiquier/blancs/pieces/piece[@position = "B3"]') = 1;

Exemple de recherche avec deux critères d'attribut :

SELECT echiquier.query('/echiquier/blancs/pieces/pion[@numero = "2"]')
FROM #partie
WHERE echiquier.exist('/echiquier/blancs/pieces/pion[@numero = "2" and @position = "B3"]') = 1;

Autre syntaxe possible :

SELECT echiquier.query('/echiquier/blancs/pieces/pion[@numero = "2"]')
FROM #partie
WHERE echiquier.exist('/echiquier/blancs/pieces/pion[@numero = "2"][@position = "B3"]') = 1;

Présence d'un élément :

SELECT echiquier.query('/echiquier/blancs/pieces/roi')
FROM #partie
WHERE echiquier.exist('/echiquier/blancs/pieces/roi') = 1;

nodes() extrait des nœuds, créant pour chacun une ligne de résultat. À utiliser dans la clause FROM. Pour spécifier une colonne, vous devez utiliser l'opérateur CROSS APPLY avec cette syntaxe :

FROM table
CROSS APPLY colonnexml.nodes('XQuery') as aliastable(aliascolonne)

Exemple avec une liste :

SELECT col.query('.')
FROM #partie p
CROSS APPLY echiquier.nodes('(/echiquier/blancs/pieces/pion, /echiquier/blancs/pieces/pion/historique/coup)') tbl(col);

modify() vous permet d'appliquer une modification au contenu du document, en utilisant une extension créée par Microsoft au langage XQuery, nommée XML-DML.

Exemple :

UPDATE #partie
SET echiquier.modify('           
  replace value of (/echiquier/blancs/pieces/pion[@position = "C5"]/@position)[1]
  with     "pris!"') 
WHERE echiquier.exist('/echiquier/blancs/pieces/pion[@position = "C5"]') = 1

SELECT echiquier.query('/echiquier/blancs/pieces/pion[@position = "pris !"]') 
FROM #partie