Clause FOR (Transact-SQL)

La clause FOR est utilisée pour spécifier l'option BROWSE ou l'option XML. BROWSE et XML sont des options non liées.

Important

La directive XMLDATA de l'option FOR XML est désapprouvée. Utilisez la génération XSD en mode RAW et AUTO. Il n'existe aucune solution de remplacement pour la directive XMLDATA en mode EXPLICIT. Cette fonctionnalité sera supprimée dans une prochaine version de Microsoft SQL Server. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité.

Conventions de la syntaxe de Transact-SQL

Syntaxe

[ FOR { BROWSE | <XML> } ]
<XML> ::=
XML 
{ 
    { RAW [ ( 'ElementName' ) ] | AUTO } 
    [ 
        <CommonDirectives> 
        [ , { XMLDATA | XMLSCHEMA [ ( 'TargetNameSpaceURI' ) ] } ] 
        [ , ELEMENTS [ XSINIL | ABSENT ] 
    ]
  | EXPLICIT 
    [ 
        <CommonDirectives> 
        [ , XMLDATA ] 
    ]
  | PATH [ ( 'ElementName' ) ] 
    [
        <CommonDirectives> 
        [ , ELEMENTS [ XSINIL | ABSENT ] ]
    ]
} 

<CommonDirectives> ::= 
[ , BINARY BASE64 ]
[ , TYPE ]
[ , ROOT [ ( 'RootName' ) ] ]

Arguments

• BROWSE
  Indique que des mises à jour sont autorisées pendant la consultation des données dans un curseur de mode de navigation DB-Library. Il est possible de naviguer dans une table d'une application si la table inclut une colonne timestamp, si elle possède un index unique, et si l'option FOR BROWSE se trouve à la fin des instructions SELECT envoyées à une instance de SQL Server.

  [!REMARQUE]

  Il est impossible d'utiliser <lock_hint> HOLDLOCK dans une instruction SELECT qui comporte l'option FOR BROWSE.

  FOR BROWSE ne peut pas apparaître dans des instructions SELECT qui sont jointes par l'opérateur UNION.

  [!REMARQUE]

  Lorsque les colonnes de clé d'index unique d'une table peuvent accepter les valeurs NULL, et si la table se trouve sur le côté intérieur d'une jointure externe, l'index n'est pas pris en charge par le mode de navigation.

  Le mode de navigation vous permet d'analyser les lignes de la table SQL Server et d'y mettre à jour les données, une ligne après l'autre. Pour accéder à une table SQL Server dans votre application, en mode de navigation, vous devez utiliser l'une des deux options suivantes :

  • L'instruction SELECT qui vous permet d'accéder aux données de la table SQL Server doit se terminer par les mots clés FOR BROWSE. Lorsque vous activez l'option FOR BROWSE pour utiliser le mode de navigation, des tables temporaires sont créées.

  • Vous devez exécuter l'instruction Transact-SQL suivante pour activer le mode de navigation en utilisant l'option NO_BROWSETABLE :

    SET NO_BROWSETABLE ON
    

    Lorsque vous activez l'option NO_BROWSETABLE, toutes les instructions SELECT se comportent comme si l'option FOR BROWSE était ajoutée à celles-ci. Toutefois, l'option NO_BROWSETABLE ne crée pas les tables temporaires que l'option FOR BROWSE utilise généralement pour envoyer les résultats de votre application.

  Lorsque vous essayez d'accéder aux données de tables SQL Server en mode de navigation en utilisant une requête SELECT qui implique une instruction de jointure externe, et lorsqu'un index unique est défini sur la table présente sur le côté intérieur d'une instruction de jointure externe, le mode de navigation ne prend pas en charge l'index unique. Le mode de navigation prend en charge l'index unique uniquement lorsque toutes les colonnes de clé d'index unique peuvent accepter les valeurs NULL. Le mode de navigation ne prend pas en charge l'index unique si les conditions suivantes sont remplies :

  • Vous essayez d'accéder aux données de tables SQL Server en mode de navigation en utilisant une requête SELECT qui implique une instruction de jointure externe.

  • Un index unique est défini sur la table qui est présente sur le côté intérieur d'une instruction de jointure externe.

  Pour reproduire ce comportement en mode de navigation, procédez comme suit :

  1. Dans SQL Server Management Studio, créez une base de données appelée SampleDB.

  2. Dans la base de données SampleDB, créez une table tleft et une table tright contenant une seule colonne nommée c1. Définissez un index unique sur la colonne c1 dans la table tleft et configurez la colonne pour qu'elle accepte les valeurs NULL. Pour cela, exécutez les instructions Transact-SQL suivantes dans une fenêtre de requête appropriée :

     CREATE TABLE tleft(c1 INT NULL UNIQUE) ;
     GO 
     CREATE TABLE tright(c1 INT NULL) ;
     GO
     

  3. Insérez plusieurs valeurs dans la table tleft et la table tright. Veillez à insérer une valeur NULL dans la table tleft. Pour cela, exécutez les instructions Transact-SQL suivantes dans la fenêtre de requête :

     INSERT INTO tleft VALUES(2) ;
     INSERT INTO tleft VALUES(NULL) ;
     INSERT INTO tright VALUES(1) ;
     INSERT INTO tright VALUES(3) ;
     INSERT INTO tright VALUES(NULL) ;
     GO
     

  4. Activez l'option NO_BROWSETABLE. Pour cela, exécutez les instructions Transact-SQL suivantes dans la fenêtre de requête :

     SET NO_BROWSETABLE ON ;
     GO
     

  5. Accédez aux données des tables tleft et tright en utilisant une instruction de jointure externe dans la requête SELECT. Vérifiez que la table tleft se trouve sur le côté intérieur de l'instruction de jointure externe. Pour cela, exécutez les instructions Transact-SQL suivantes dans la fenêtre de requête :

     SELECT tleft.c1 
     FROM tleft 
     RIGHT JOIN tright 
     ON tleft.c1 = tright.c1 
     WHERE tright.c1 <> 2 ;
     

     Remarquez la sortie suivante dans le volet Résultats :

     c1

     ----

     NULL

     NULL

  Après avoir exécuté la requête SELECT pour accéder aux tables en mode de navigation, le jeu de résultats de la requête SELECT contient deux valeurs NULL pour la colonne c1 dans la table tleft à cause de la définition de l'instruction de jointure externe droite. Par conséquent, dans le jeu de résultats, vous ne pouvez pas distinguer les valeurs NULL provenant de la table de celles introduites par l'instruction de jointure externe droite. Vous pouvez recevoir des résultats incorrects si vous devez ignorer les valeurs NULL du jeu de résultats.

  [!REMARQUE]

  Si les colonnes incluses dans l'index unique n'acceptent pas de valeurs NULL, toutes les valeurs NULL contenues dans le jeu de résultats ont été introduites par l'instruction de jointure externe droite.

• XML
  Spécifie que les résultats d'une requête doivent être retournés sous la forme d'un document XML. Un des modes XML suivants doit être spécifié : RAW, AUTO ou EXPLICIT. Pour plus d'informations sur les données XML et sur SQL Server, consultez Construction de code XML à l'aide de FOR XML.

• RAW [ ('ElementName') ]
  Prend le résultat de la requête et transforme chaque ligne du jeu de résultats en un élément XML comportant un identificateur générique <row /> comme balise d'élément. Vous pouvez éventuellement spécifier un nom pour l'élément de ligne. La sortie XML utilise le paramètre ElementName spécifié comme élément de ligne généré pour chaque ligne. Pour plus d'informations, consultez Utilisation du mode RAW et Utilisation du mode RAW.

• AUTO
  Retourne les résultats de la requête dans une arborescence XML simple et imbriquée. Chaque table de la clause FROM, dont au moins une colonne est répertoriée dans la clause SELECT, est représentée sous la forme d'un élément XML. Les colonnes figurant dans la clause SELECT sont mappées vers les attributs d'éléments appropriés. Pour plus d'informations, consultez Utilisation du mode AUTO.

• EXPLICIT
  Spécifie que la forme de l'arborescence XML résultante est définie de manière explicite. L'utilisation de ce mode nécessite toutefois que les requêtes soient écrites d'une manière particulière, de sorte que les informations complémentaires sur l'imbrication souhaitée soient spécifiées de manière explicite. Pour plus d'informations, consultez Utilisation du mode EXPLICIT.

• XMLDATA
  Retourne un schéma XDR inclus, mais n'ajoute pas l'élément racine au résultat. Si XMLDATA est spécifié, le schéma XDR est ajouté au document.

• XMLSCHEMA [ ('TargetNameSpaceURI') ]
  Retourne le schéma XSD inclus. Lorsque vous spécifiez cette directive, vous pouvez éventuellement spécifier un URI d'espace de noms cible, qui retourne l'espace de noms spécifié dans le schéma. Pour plus d'informations, consultez Génération de schéma XSD en ligne.

• ELEMENTS
  Spécifie que les colonnes sont retournées sous la forme de sous-éléments. Sinon, elles sont mappées avec des attributs XML. Cette option est prise en charge dans les modes RAW, AUTO et PATH uniquement. Pour plus d'informations, consultez Utilisation du mode RAW.

• XSINIL
  Spécifie qu'un élément ayant un attribut xsi:nil défini à True soit créé pour les valeurs de colonne NULL. Cette option peut uniquement être spécifiée avec la directive ELEMENTS. Pour plus d'informations, consultez Génération d'éléments pour des valeurs NULL à l'aide du paramètre XSINIL.

• ABSENT
  Indique que pour les valeurs de colonne NULL, les éléments XML correspondants ne seront pas ajoutés dans le résultat XML. Vous ne devez spécifier cette option qu'avec ELEMENTS.

• PATH [ ('ElementName') ]
  Génère un élément wrapper <row> pour chaque ligne du jeu de résultats. Vous pouvez éventuellement spécifier un nom d'élément pour l'élément wrapper <row>. Si une chaîne vide est fournie, comme FOR XML PATH ('') ), aucun élément wrapper n'est généré. L'utilisation de PATH peut constituer une solution plus simple pour les requêtes écrites à l'aide de la directive EXPLICIT. Pour plus d'informations, consultez Utilisation du mode PATH.

• BINARY BASE64
  Spécifie que la requête retourne les données binaires au format binaire codé base64. Cette option doit être spécifiée lors de l'extraction de données binaires en mode RAW et EXPLICIT. Cette option est utilisée par défaut en mode AUTO.

• TYPE
  Spécifie que la requête retourne des résultats de type xml. Pour plus d'informations, consultez Directive TYPE dans les requêtes FOR XML.

• ROOT [ ('RootName') ]
  Spécifie qu'un élément de premier niveau unique doit être ajouté au XML résultant. Vous pouvez éventuellement spécifier le nom de l'élément racine à générer. Si le nom de racine facultatif n'est pas spécifié, l'élément <root> par défaut est ajouté.

Exemple

L'exemple suivant spécifie FOR XML AUTO avec les options TYPE et XMLSCHEMA. En raison de la présence de l'option TYPE, le jeu de résultats est retourné au client comme un type xml. L'option XMLSCHEMA spécifie que le schéma XSD inclus est intégré aux données XML retournées, et l'option ELEMENTS spécifie que le résultat XML est centré sur les éléments.

USE AdventureWorks;
GO
SELECT ContactID, FirstName, LastName, Phone
FROM Person.Contact
WHERE LastName LIKE 'G%'
ORDER BY LastName, FirstName 
FOR XML AUTO, TYPE, XMLSCHEMA, ELEMENTS XSINIL;

Voir aussi

Référence

SELECT (Transact-SQL)

Construction de code XML à l'aide de FOR XML