SELECT - Clause FOR (Transact-SQL)

Article
05/23/2023

S’applique à : point de terminaison d’analytique SQL Azure SQL Database Azure SQL Database dans Microsoft Fabric Warehouse

La clause FOR vous permet de spécifier l’une des options suivantes pour les résultats de la requête.

Autoriser les mises à jour pendant la consultation des données de la requête dans un curseur de mode de navigation en spécifiant FOR BROWSE.
Mettre les résultats de la requête au format XML en spécifiant FOR XML.
Mettre les résultats de la requête au format JSON en spécifiant FOR JSON.

Conventions de la syntaxe Transact-SQL

Syntaxe

[ FOR { BROWSE | <XML> | <JSON>} ]  
  
<XML> ::=  
XML   
{   
    { RAW [ ( 'ElementName' ) ] | AUTO }   
    [   
        <CommonDirectivesForXML>   
        [ , { XMLDATA | XMLSCHEMA [ ( 'TargetNameSpaceURI' ) ] } ]   
        [ , ELEMENTS [ XSINIL | ABSENT ]   
    ]  
  | EXPLICIT   
    [   
        <CommonDirectivesForXML>   
        [ , XMLDATA ]   
    ]  
  | PATH [ ( 'ElementName' ) ]   
    [  
        <CommonDirectivesForXML>   
        [ , ELEMENTS [ XSINIL | ABSENT ] ]  
    ]  
}   
  
<CommonDirectivesForXML> ::=   
[ , BINARY BASE64 ]  
[ , TYPE ]  
[ , ROOT [ ( 'RootName' ) ] ]  
  
<JSON> ::=  
JSON   
{   
    { AUTO | PATH }   
    [   
        [ , ROOT [ ( 'RootName' ) ] ]  
        [ , INCLUDE_NULL_VALUES ]  
        [ , WITHOUT_ARRAY_WRAPPER ]  
    ]  
  
}

FOR BROWSE

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.

Notes

Il est impossible d’utiliser le HOLDLOCK <lock_hint> 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.

Notes

Lorsque les colonnes clés 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 utilisée pour accéder aux données de la table SQL Server doit se terminer par les mots clés FOR BROWSE. Quand 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  
```
Quand vous activez l’option NO_BROWSETABLE, toutes les instructions SELECT se comportent comme si elles incluaient l’option FOR BROWSE. 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 à votre application.

Lorsque vous essayez d’accéder aux données de tables SQL Server en mode de navigation à l’aide d’une requête SELECT contenant une instruction de jointure externe, et qu’un index unique est défini sur la table présente sur le côté interne 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 clés 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 contient 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 :

Dans SQL Server Management Studio, créez une base de données appelée SampleDB.
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  
```
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  
```
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  
```
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.

Notes

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.

FOR XML

XML
Spécifie que les résultats d'une requête doivent être retournés sous la forme d'un document XML. L’un des modes XML suivants doit être indiqué : RAW, AUTO, EXPLICIT. Pour plus d’informations sur les données XML et sur SQL Server, consultez FOR XML (SQL Server).

RAW [ ('ElementName') ]
Prend le résultat de la requête et transforme chaque ligne du jeu de résultats en un élément XML avec 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 de code XML utilise le nom ElementName spécifié pour identifier l’élément de ligne généré pour chaque ligne. Pour plus d’informations, consultez Utiliser le mode RAW avec FOR XML.

AUTO
Renvoie les résultats de la requête dans une arborescence XML simple et imbriquée. Chaque table dans la clause FROM pour laquelle au moins une colonne existe dans la clause SELECT est représentée comme un élément XML. Les colonnes listées dans la clause SELECT sont mappées vers les attributs d'éléments appropriés. Pour plus d’informations, consultez Utiliser le mode AUTO avec FOR XML.

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 Utiliser le mode EXPLICIT avec FOR XML.

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.

Important

La directive XMLDATA est dépréciée. Utilisez la génération XSD en mode RAW et AUTO. Il n'y a aucun remplacement pour la directive XMLDATA en mode EXPLICIT. Cette fonctionnalité sera supprimée dans une version future de 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é.

Supprimer les sauts de ligne indésirables : vous pouvez utiliser SSMS (SQL Server Management Studio) pour émettre une requête qui utilise la clause FOR XML. Il est arrive parfois qu’une grande chaîne XML soit retournée et affichée dans une cellule de grille. La longueur de cette chaîne XML peut être supérieure à celle d’une ligne unique dans une cellule de grille SSMS. Dans ce cas, SSMS peut insérer des caractères de fin de ligne entre les longs segments de la chaîne XML. De tels sauts de ligne peuvent se produire au milieu d’une sous-chaîne qui n’est pas censée être scindée en plusieurs lignes. Pour empêcher les sauts de ligne, vous pouvez utiliser un cast AS XMLDATA. Cette solution s’applique également quand vous utilisez FOR JSON PATH. La technique est décrite sur Stack Overflow et est indiquée dans l’instruction SELECT de l’exemple Transact-SQL suivant :

Using SQL Server FOR XML: Convert Result Datatype to Text/varchar/string whatever?

SELECT CAST(
    (SELECT column1, column2
        FROM my_table
        FOR XML PATH('')
    )
        AS VARCHAR(MAX)
) AS XMLDATA ;

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érer un schéma XSD Inline.

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 Utiliser le mode RAW avec FOR XML.

XSINIL
Spécifie qu’un élément ayant un attribut xsi:nil défini à True doit être créé pour les valeurs de colonne NULL. Cette option peut uniquement être spécifiée avec la directive ELEMENTS. Pour plus d'informations, consultez les pages suivantes :

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 wrapper d’élément <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 Utiliser le mode PATH avec FOR XML.

BINARY BASE64
Spécifie que la requête retourne les données binaires au format binaire encodé 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, si vous le souhaitez, spécifier le nom d'é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é.

Pour plus d’informations, consultez FOR XML (SQL Server).

Exemple FOR XML

L'exemple suivant spécifie FOR XML AUTO avec les options TYPE et XMLSCHEMA. Comme l’option TYPE a été spécifiée, 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 AdventureWorks2022;  
GO  
SELECT p.BusinessEntityID, FirstName, LastName, PhoneNumber AS Phone  
FROM Person.Person AS p  
JOIN Person.PersonPhone AS pph ON p.BusinessEntityID  = pph.BusinessEntityID  
WHERE LastName LIKE 'G%'  
ORDER BY LastName, FirstName   
FOR XML AUTO, TYPE, XMLSCHEMA, ELEMENTS XSINIL;

FOR JSON

JSON
Spécifiez FOR JSON pour retourner les résultats d’une requête au format texte JSON. Vous devez également spécifier l’un des modes JSON suivants : AUTO ou PATH. Pour plus d’informations sur la clause FOR JSON, consultez Mettre les résultats de requête au format JSON avec FOR JSON (SQL Server).

AUTO
Mettez la sortie JSON automatiquement en forme en fonction de la structure de l’instruction SELECT
en spécifiant FOR JSON AUTO. Pour obtenir plus d’informations et des exemples, consultez Mettre en forme automatiquement la sortie JSON avec le mode AUTO (SQL Server).

PATH
Gardez le contrôle total du format de la sortie JSON en spécifiant
FOR JSON PATH. Le modePATH vous permet de créer des objets wrapper et d’imbriquer des propriétés complexes. Pour obtenir plus d’informations et des exemples, consultez Mettre en forme la sortie JSON imbriquée avec le mode PATH (SQL Server).

INCLUDE_NULL_VALUES
Incluez les valeurs NULL dans la sortie JSON en spécifiant l’option INCLUDE_NULL_VALUES avec la clause FOR JSON. Si vous ne spécifiez pas cette option, la sortie n’inclut pas les propriétés JSON pour les valeurs NULL dans les résultats de la requête. Pour obtenir plus d’informations et des exemples, consultezInclure des valeurs NULL dans une sortie JSON avec l’option INCLUDE_NULL_VALUES (SQL Server).

ROOT [ ('RootName') ]
Ajoutez un élément racine unique à la sortie JSON en spécifiant l’option ROOT avec la clause FOR JSON. Si vous ne spécifiez pas l’option ROOT , la sortie JSON n'aura pas d’élément racine. Pour obtenir plus d’informations et des exemples, consultez Ajouter un nœud racine à la sortie JSON avec l’option ROOT (SQL Server).

WITHOUT_ARRAY_WRAPPER
Supprimez les crochets qui entourent par défaut la sortie JSON en spécifiant l’option WITHOUT_ARRAY_WRAPPER avec la clause FOR JSON. Si vous ne spécifiez pas cette option, la sortie JSON est placée entre crochets. Utilisez l’option WITHOUT_ARRAY_WRAPPER pour générer un seul objet JSON en sortie. Pour plus d’informations, consultez Supprimer les crochets de la sortie JSON avec l’option WITHOUT_ARRAY_WRAPPER (SQL Server).

Pour plus d’informations, consultez Mettre les résultats de requête au format JSON avec FOR JSON (SQL Server).

Voir aussi

SELECT (Transact-SQL)

Partager via

SELECT - Clause FOR (Transact-SQL)

Syntaxe

FOR BROWSE

FOR XML

FOR JSON

Voir aussi

Commentaires

Ressources supplémentaires