value(), méthode (Type de données xml)value() Method (xml Data Type)

CETTE RUBRIQUE S’APPLIQUE À :ouiSQL Server (à partir de la version 2008)ouiAzure SQL DatabasenonAzure SQL Data Warehouse nonParallel Data Warehouse THIS TOPIC APPLIES TO:yesSQL Server (starting with 2008)yesAzure SQL DatabasenoAzure SQL Data Warehouse noParallel Data Warehouse

Exécute une requête XQuery sur le code XML et retourne une valeur de type SQL.Performs an XQuery against the XML and returns a value of SQL type. Cette méthode retourne une valeur scalaire.This method returns a scalar value.

Vous utilisez généralement cette méthode pour extraire une valeur d’une instance XML stockée dans une xml colonne de type, paramètre ou variable.You typically use this method to extract a value from an XML instance stored in an xml type column, parameter, or variable. Vous pouvez ainsi spécifier des requêtes SELECT qui combinent ou comparent des données XML avec des données de colonnes non-XML.In this way, you can specify SELECT queries that combine or compare XML data with data in non-XML columns.

SyntaxeSyntax


value (XQuery, SQLType)  

ArgumentsArguments

XQueryXQuery
Est la XQuery expression, un littéral de chaîne, qui Récupère des données à l’intérieur de l’instance XML.Is the XQuery expression, a string literal, that retrieves data inside the XML instance. La requête XQuery doit retourner au plus une valeur.The XQuery must return at most one value. Sinon, une erreur est retournée.Otherwise, an error is returned.

SQLTypeSQLType
Type SQL préféré (littéral de chaîne) à retourner.Is the preferred SQL type, a string literal, to be returned. Le type de retour de cette méthode correspond à la SQLType paramètre.The return type of this method matches the SQLType parameter. SQLType ne peut pas être un xml type de données, un type common language runtime (CLR) définis par l’utilisateur, image, texte, ntext, ou sql_variant type de données.SQLType cannot be an xml data type, a common language runtime (CLR) user-defined type, image, text, ntext, or sql_variant data type. SQLType peut être un SQL, le type de données défini par l’utilisateur.SQLType can be an SQL, user-defined data type.

Le value() utilise le Transact-SQLTransact-SQL opérateur de convertir implicitement et essaie de convertir le résultat de l’expression XQuery, la représentation sous forme de chaîne sérialisée, du type XSD au type SQL correspondant spécifié par Transact-SQLTransact-SQL conversion.The value() method uses the Transact-SQLTransact-SQL CONVERT operator implicitly and tries to convert the result of the XQuery expression, the serialized string representation, from XSD type to the corresponding SQL type specified by Transact-SQLTransact-SQL conversion. Pour plus d’informations sur les règles de conversion de type pour CONVERT, consultez CAST et CONVERT ( Transact-SQL ) .For more information about type casting rules for CONVERT, see CAST and CONVERT (Transact-SQL).

Note

Pour des raisons de performances, au lieu d’utiliser le value() méthode dans un prédicat de comparaison avec une valeur relationnelle, utilisez exist() avec SQL :Column().For performance reasons, instead of using the value() method in a predicate to compare with a relational value, use exist() with sql:column(). L'exemple D vous en donne l'illustration.This is shown in example D that follows.

ExemplesExamples

A.A. Utilisation de la méthode value() sur une variable de type xmlUsing the value() method against an xml type variable

Dans l'exemple suivant, une instance XML est stockée dans une variable de type xml.In the following example, an XML instance is stored in a variable of xml type. La méthode value() récupère la valeur d'attribut ProductID à partir du code XML.The value() method retrieves the ProductID attribute value from the XML. La valeur est ensuite assignée à une variable int.The value is then assigned to an int variable.

DECLARE @myDoc xml  
DECLARE @ProdID int  
SET @myDoc = '<Root>  
<ProductDescription ProductID="1" ProductName="Road Bike">  
<Features>  
  <Warranty>1 year parts and labor</Warranty>  
  <Maintenance>3 year parts and labor extended maintenance is available</Maintenance>  
</Features>  
</ProductDescription>  
</Root>'  

SET @ProdID =  @myDoc.value('(/Root/ProductDescription/@ProductID)[1]', 'int' )  
SELECT @ProdID  

La valeur 1 est retournée comme résultat.Value 1 is returned as a result.

Bien qu'il n'y ait qu'un seul attribut ProductID dans l'instance XML, les règles de types statiques exigent que vous spécifiiez de manière explicite que l'expression de chemin d'accès retourne un singleton.Although there is only one ProductID attribute in the XML instance, the static typing rules require you to explicitly specify that the path expression returns a singleton. Par conséquent, le [1] supplémentaire est spécifié à la fin de l'expression de chemin d'accès.Therefore, the additional [1] is specified at the end of the path expression. Pour plus d’informations sur les types statiques, consultez XQuery et le typage statique.For more information about static typing, see XQuery and Static Typing.

B.B. Utilisation de la méthode value() pour récupérer une valeur à partir d'une colonne de type xmlUsing the value() method to retrieve a value from an xml type column

La requête suivante porte sur une xml colonne de type (CatalogDescription) dans le AdventureWorks base de données.The following query is specified against an xml type column (CatalogDescription) in the AdventureWorks database. La requête récupère des valeurs d'attributs ProductModelID à partir de chaque instance XML stockée dans la colonne.The query retrieves ProductModelID attribute values from each XML instance stored in the column.

SELECT CatalogDescription.value('             
    declare namespace PD="http://schemas.microsoft.com/sqlserver/2004/07/adventure-works/ProductModelDescription";             
       (/PD:ProductDescription/@ProductModelID)[1]', 'int') AS Result             
FROM Production.ProductModel             
WHERE CatalogDescription IS NOT NULL             
ORDER BY Result desc             

Notez les points suivants dans la requête précédente :Note the following from the previous query:

  • Le mot clé namespace est utilisé pour définir un préfixe d'espace de noms.The namespace keyword is used to define a namespace prefix.

  • Conformément aux exigences de type statique, [1] est ajouté à la fin de l'expression de chemin d'accès dans la méthode value() afin d'indiquer de manière explicite que l'expression de chemin d'accès retourne un singleton.Per static typing requirements, [1] is added at the end of the path expression in the value() method to explicitly indicate that the path expression returns a singleton.

    Voici le résultat partiel :This is the partial result:

-----------  
35           
34           
...  

C.C. Utilisation des méthodes value() et exist() pour récupérer des valeurs à partir d'une colonne de type xmlUsing the value() and exist() methods to retrieve values from an xml type column

L’exemple suivant illustre l’utilisation à la fois le value() (méthode) et le méthode exist() de la xml type de données.The following example shows using both the value() method and the exist() method of the xml data type. La méthode value() est utilisée pour récupérer des valeurs d'attributs ProductModelID à partir du code XML.The value() method is used to retrieve ProductModelID attribute values from the XML. La méthode exist() de la clause WHERE est utilisée pour filtrer les lignes de la table.The exist() method in the WHERE clause is used to filter the rows from the table.

La requête récupère des ID de modèle de produit à partir d'instances XML qui incluent des informations de garantie (l'élément <Warranty>) comme caractéristiques.The query retrieves product model IDs from XML instances that include warranty information (the <Warranty> element) as one of the features. La condition de la clause WHERE utilise la méthode exist() pour récupérer uniquement les lignes qui satisfont cette condition.The condition in the WHERE clause uses the exist() method to retrieve only the rows satisfying this condition.

SELECT CatalogDescription.value('  
     declare namespace PD="http://schemas.microsoft.com/sqlserver/2004/07/adventure-works/ProductModelDescription";  
           (/PD:ProductDescription/@ProductModelID)[1] ', 'int') as Result  
FROM  Production.ProductModel  
WHERE CatalogDescription.exist('  
     declare namespace PD="http://schemas.microsoft.com/sqlserver/2004/07/adventure-works/ProductModelDescription";  
     declare namespace wm="http://schemas.microsoft.com/sqlserver/2004/07/adventure-works/ProductModelWarrAndMain";  

     /PD:ProductDescription/PD:Features/wm:Warranty ') = 1  

Notez les points suivants dans la requête précédente :Note the following from the previous query:

  • La colonne CatalogDescription est une colonne XML typée.The CatalogDescription column is a typed XML column. Cela signifie qu'une collection de schémas lui est associée.This means that it has a schema collection associated with it. Dans le prologue XQuery, la déclaration d’espace de noms est utilisée pour définir le préfixe utilisé plus loin dans le corps de la requête.In the XQuery Prolog, the namespace declaration is used to define the prefix that is used later in the query body.

  • Si la méthode exist() retourne un 1 (True), cela indique que l'instance XML contient l'élément enfant <Warranty> comme caractéristique.If the exist() method returns a 1 (True), it indicates that the XML instance includes the <Warranty> child element as one of the features.

  • La méthode value() de la clause SELECT récupère ensuite les valeurs d'attributs ProductModelID comme entiers.The value() method in the SELECT clause then retrieves the ProductModelID attribute values as integers.

    Voici le résultat partiel :This is the partial result:

Result       
-----------  
19           
23           
...  

D.D. Utilisation de la méthode exist() au lieu de la méthode value()Using the exist() method instead of the value() method

Pour des raisons de performances, au lieu d'utiliser la méthode value() dans un prédicat pour comparer avec une valeur relationnelle, utilisez exist() avec sql:column().For performance reasons, instead of using the value() method in a predicate to compare with a relational value, use exist() with sql:column(). Exemple :For example:

CREATE TABLE T (c1 int, c2 varchar(10), c3 xml)  
GO  

SELECT c1, c2, c3   
FROM T  
WHERE c3.value( '/root[1]/@a', 'integer') = c1  
GO  

Cela peut être écrit de la manière suivante :This can be written in the following way:

SELECT c1, c2, c3   
FROM T  
WHERE c3.exist( '/root[@a=sql:column("c1")]') = 1  
GO  

Voir aussiSee Also

Ajouter des espaces de noms aux requêtes avec WITH XMLNAMESPACES Add Namespaces to Queries with WITH XMLNAMESPACES
Comparer du XML typé et du XML non typé Compare Typed XML to Untyped XML
Créer des instances de données XML Create Instances of XML Data
méthodes de type de données xml xml Data Type Methods
XML Data Modification Language ( XML DML )XML Data Modification Language (XML DML)