Utiliser le mode EXPLICIT avec FOR XML

  • Article

S’applique à :SQL ServerAzure SQL DatabaseAzure SQL Managed Instance

Comme décrit dans l’article, la construction de CODE XML à l’aide du mode FOR XML, RAW et AUTO n’offre pas beaucoup de contrôle sur la forme du code XML généré à partir d’un résultat de requête. Toutefois, le mode EXPLICIT offre la plus grande souplesse pour générer le document XML à partir du résultat d'une requête.

La requête en mode EXPLICIT doit être écrite de telle sorte que les informations supplémentaires sur le document XML, telles que l'imbrication attendue dans celui-ci, soient explicitement spécifiées comme une partie de la requête. Suivant le document XML demandé, l'écriture de requêtes en mode EXPLICIT peut s'avérer peu pratique. L’ utilisation du mode PATH avec imbrication peut vous apparaître comme une solution plus simple pour écrire des requêtes en mode EXPLICIT.

Étant donné que vous décrivez en mode EXPLICIT le document XML souhaité dans le cadre de la requête, vous devez veiller à ce que sa forme générée soit correcte et valide.

Traitement de l’ensemble de lignes en mode EXPLICIT

Le mode EXPLICIT transforme l'ensemble de lignes issu de l'exécution de la requête en un document XML. Pour cela, l'ensemble de lignes doit être d'un format spécifique. Cela suppose que vous écriviez la requête SELECT qui génère l’ensemble de lignes, la table universelle, dans un format spécifique afin que la logique de traitement puisse produire le document XML souhaité.

Dans un premier temps, la requête doit générer les deux colonnes de métadonnées suivantes :

  • La première colonne doit fournir le numéro de balise, de type entier, de l’élément actuel et le nom de la colonne doit être Tag. La requête doit fournir un numéro de balise unique pour chaque élément à construire à partir de l'ensemble de lignes.

  • La seconde colonne doit fournir un numéro de balise de l’élément parent et porter le nom Parent. Ainsi, les colonnes Tag et Parent fournissent les informations de hiérarchie.

Ces valeurs de colonnes de métadonnées, associées aux informations des noms de colonnes, permettent de générer le document XML souhaité. Votre requête doit fournir des noms de colonnes d’une manière spécifique. En outre, la valeur 0 ou NULL dans la colonne Parent . indique que l’élément correspondant n’a pas de parent. L'élément est ajouté au document XML en tant qu'élément de niveau supérieur.

Pour comprendre comment la table universelle générée par une requête est traitée en vue de produire un document XML, supposons que vous ayez écrit une requête qui génère la table universelle suivante :

Sample universal table.

Notez les points suivants à propos de cette table universelle :

  • Les deux premières colonnes sont Tag et Parent et sont des colonnes de métadonnées. Ces valeurs déterminent la hiérarchie.

  • Les noms de colonnes sont spécifiés d’une certaine manière, comme décrit plus loin dans cet article.

  • Lors de la génération du document XML à partir de cette table universelle, les données de celle-ci sont partitionnées verticalement en groupes de colonnes. Le regroupement est déterminé en fonction de la valeur Tag et des noms de colonnes. Lors de la construction du document XML, la logique de traitement sélectionne un groupe de colonnes par ligne et construit un élément. Cet exemple repose sur les données suivantes :

    • Pour la valeur de colonne Tag 1 de la première ligne, les colonnes dont le nom comprend le même numéro de balise, Customer!1!cid et Customer!1!name, forment un groupe. Ces colonnes sont utilisées pour traiter la ligne et vous avez peut-être remarqué que la forme de l’élément généré est <Customer id=... name=...>. Le format de nom de colonne est décrit plus loin dans cet article.

    • Pour les lignes avec la valeur de colonne balise 2, les colonnes Order!2!id et Order!2!date forment un groupe qui est ensuite utilisé dans la construction d’éléments. <Order id=... date=... />

    • Pour les lignes possédant la valeur de colonne Tag 3, les colonnes OrderDetail!3!id!id et OrderDetail!3!pid!idref forment un groupe. Chacune de ces lignes génère un élément, <OrderDetail id=... pid=...>à partir de ces colonnes.

  • Dans la génération de la hiérarchie XML, les lignes sont traitées dans l’ordre. La hiérarchie XML est déterminée comme suit :

    • La première ligne spécifie la valeur Tag 1 et la valeur Parent NULL. Par conséquent, l’élément correspondant, <Customer> élément, est ajouté en tant qu’élément de niveau supérieur dans le code XML.

      <Customer cid="C1" name="Janine">

    • La deuxième ligne identifie la valeur Tag 2 et la valeur Parent 1. Par conséquent, l’élément, <Order> élément, est ajouté en tant qu’enfant de l’élément <Customer> .

      <Customer cid="C1" name="Janine">
   <Order id="O1" date="1/20/1996">

    • La ligne suivante identifie la valeur Tag 3 et la valeur Parent 2. Par conséquent, les deux éléments, <OrderDetail> éléments, sont ajoutés en tant qu’enfants de l’élément <Order> .

      <Customer cid="C1" name="Janine">
   <Order id="O1" date="1/20/1996">
      <OrderDetail id="OD1" pid="P1"/>
      <OrderDetail id="OD2" pid="P2"/>

    • La dernière ligne identifie la valeur 2 comme numéro Tag et la valeur 1 comme numéro de balise Parent . Par conséquent, un autre <Order> enfant d’élément est ajouté à l’élément <Customer> parent.

      <Customer cid="C1" name="Janine">
   <Order id="O1" date="1/20/1996">
      <OrderDetail id="OD1" pid="P1"/>
      <OrderDetail id="OD2" pid="P2"/>
   </Order>
   <Order id="O2" date="3/29/1997">
</Customer>

En résumé, les valeurs des colonnes de métadonnées Tag et Parent , les informations fournies dans les noms de colonnes et le classement correct des lignes génèrent le document XML souhaité lorsque vous utilisez le mode EXPLICIT.

Classement des lignes de table universelle

Lors de la construction du document XML, les lignes de la table universelle sont traitées dans l'ordre. Par conséquent, pour extraire les instances enfants adéquates associées à leur parent, vous devez trier les lignes de l'ensemble de lignes de manière à ce que chaque nœud parent soit immédiatement suivi de ses enfants.

Spécifier des noms de colonnes dans une table universelle

Lors de l'écriture des requêtes en mode EXPLICIT, les noms de colonnes de l'ensemble de lignes obtenu doivent être spécifiés à l'aide du format ci-après. Ils fournissent des informations de transformation, dont les noms d'éléments et d'attributs, spécifiées à l'aide de directives.

Voici le format général :

ElementName!TagNumber!AttributeName!Directive

Voici la description des parties du format :

  • ElementName

    Identificateur générique résultant de l’élément. Par exemple, si Customers est spécifié en tant que ElementName, l’élément <Customers> est généré.

  • TagNumber

    Valeur d’étiquette unique affectée à un élément. Cette valeur, associée aux deux colonnes de métadonnées Tag et Parent, détermine l’imbrication des éléments dans le document XML obtenu.

  • AttributeName

    Fournit le nom de l’attribut à construire dans l’option ElementNamespécifiée. Il s’agit du comportement si la directive n’est pas spécifiée.

    Si l’option Directive est spécifiée et que sa valeur est xml, cdataou element, cette valeur est utilisée pour construire un élément enfant de ElementNameet la valeur de la colonne est ajoutée à cet élément.

    Si vous spécifiez l’option Directive, l’option AttributeName peut être vide. Par exemple, ElementName!TagNumber!!Directive. Dans ce cas, la valeur de la colonne est directement contenue dans l’option ElementName.

  • Directive

    L’optionDirective est facultative et permet de fournir des informations supplémentaires pour la construction du document XML. La finalité deDirective est double.

    • D'une part, elle permet d'encoder les valeurs sous la forme de mots clés ID, IDREF et IDREFS. Vous pouvez spécifier les mots clés ID, IDREFet IDREFS en tant que Directives. Ces directives remplacent les types d'attributs. Cela vous permet de créer des liens à l'intérieur du document.

    • D’autre part, l’option Directive vous permet d’indiquer comment vous souhaitez mapper les données de chaîne au document XML. Les mots clés hide, element, elementxsinil, xml, xmltextet cdata peuvent être utilisés comme Directive. La directive hide masque le nœud. Cela est utile lorsque vous récupérez des valeurs uniquement à des fins de tri, mais que vous ne les souhaitez pas dans le code XML résultant.

    La directive element génère un élément contenu au lieu d’un attribut. Les données contenues sont encodées comme une entité. Par exemple, le caractère < devient <. Dans le cas des valeurs de colonne NULL, aucun élément n'est généré. Si vous souhaitez qu’un élément soit généré pour les valeurs de colonne NULL, vous pouvez spécifier la directive elementxsinil . Cette opération génère un élément ayant l'attribut xsi:nil=TRUE.

    La directive xml est identique à une directive element , sauf qu’aucun encodage d’entité ne se produit. La directive d’élément peut être combinée avec ID, IDREF ou IDREFS, tandis que la directive xml n’est autorisée avec aucune autre directive, sauf masquer.

    La directive cdata englobe les données à l’aide d’une section CDATA. Le contenu n’est pas codé en entité. Le type de données d’origine doit être un type texte tel que varchar, nvarchar, textou ntext. Cette directive ne peut être utilisée qu’avec hide. Quand cette directive est utilisée, AttributeName ne doit pas être spécifié.

    La combinaison de directives entre ces deux groupes est autorisée dans la plupart des cas, mais la combinaison entre elles n’est pas autorisée.

Si Directive et AttributeName ne sont pas spécifiés, par exemple, Customer!1, une directive d’élément est implicite, telle que Customer!1!! les données d’élément et de colonne sont contenues dans ElementName.

Si la directive xmltext est spécifiée, le contenu des colonnes est englobé dans une balise unique intégrée au reste du document. Cette directive est utile pour extraire des données XML non consommées, en excès, stockées dans une colonne à l'aide de OPENXML. Pour plus d’informations, consultez OPENXML (SQL Server).

Si l’option AttributeName est définie, le nom de balise est remplacé par le nom spécifié. Sinon, l'attribut est ajouté à la liste actuelle des attributs des éléments d'encadrement par placement du contenu au début de l'imbrication sans encodage d'entité. La colonne à laquelle cette directive est associée doit être d’un type texte, tel que varchar, nvarchar, char, nchar, textou ntext. Cette directive ne peut être utilisée qu’avec hide. Elle est utile pour extraire des données en excès stockées dans une colonne. Si le contenu n’est pas un xml bien formé, le comportement n’est pas défini.

Étapes suivantes

Les exemples suivants illustrent l'utilisation du mode EXPLICIT.

Voir aussi