Método value() (tipo de dados XML)

  • Artigo

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure

Executa um XQuery em XML e retorna um valor do tipo SQL. Este método retorna um valor escalar.

Este método é usado, em geral, para extrair um valor de uma instância de XML armazenada em uma coluna de tipo, um parâmetro ou uma variável xml. Dessa forma, você pode especificar SELECT consultas que combinam ou comparam dados XML com dados em colunas não XML.

Sintaxe

value ( XQuery , SQLType )

Argumentos

XQuery

A expressão XQuery , um literal de cadeia de caracteres, que recupera dados dentro da instância XML. A XQuery deve retornar no máximo um valor. Caso contrário, um erro é retornado.

SQLType

O tipo SQL preferencial, um literal de cadeia de caracteres, a ser retornado. O tipo de retorno desse método corresponde ao parâmetro SQLType. SQLType pode ser um tipo de dados SQL definido pelo usuário.

Observação

O SQLType não pode ser um dos seguintes tipos de dados: xml, image, text, ntext, sql_variant ou um tipo CLR (Common Language Runtime) definido pelo usuário.

O value() método usa o operador Transact-SQL CONVERT implicitamente. value() tenta converter o resultado da expressão XQuery, a representação de cadeia de caracteres serializada, do tipo XSD (Definição de Esquema XML) para o tipo SQL correspondente especificado pela conversão Transact-SQL. Para obter mais informações sobre regras de conversão de tipo para CONVERT, consulte CAST e CONVERT.

Por motivos de desempenho, você pode usar exist() with sql:column() em vez de usar o value() método em um predicado, para comparar com um valor relacional. Este exist() exemplo é mostrado posteriormente neste artigo.

Exemplos

Os exemplos de código do Transact-SQL deste artigo usa o banco de dados de exemplo AdventureWorks2022 ou AdventureWorksDW2022, que pode ser baixado da home page Microsoft SQL Server Samples and Community Projects.

R. Use o método value() em uma variável de tipo XML

No exemplo a seguir, uma instância XML é armazenada em uma variável do tipo xml . O método value() recupera o valor de atributo ProductID do XML. O valor é então atribuído a uma variável int .

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;

Um valor de 1 é retornado como resultado.

Embora haja apenas um ProductID atributo na instância XML, as regras de tipagem estática exigem que você especifique explicitamente que a expressão de caminho retorna um singleton. Portanto, o [1] é adicionado ao final da expressão de caminho. Para obter mais informações sobre a tipagem estática, consulte XQuery e tipagem estática.

B. Use o método value() para recuperar um valor inteiro de uma coluna do tipo XML

A consulta a seguir é especificada em uma coluna de tipo xml (CatalogDescription) no banco de dados AdventureWorks2022. A consulta recupera valores de atributo ProductModelID de cada instância de XML armazenada na coluna.

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;

Observação da consulta anterior:

  • A palavra-chave namespace é usada para definir um prefixo de namespace.

  • De acordo com as exigências de digitação estática, [1] é adicionado no final da expressão de caminho no método value() a fim de indicar explicitamente que a expressão de caminho retorna um singleton.

Veja a seguir o conjunto de resultados.

35
34
28
25
23
19

C. Use o método value() para recuperar um valor de string de uma coluna do tipo XML

A consulta a seguir é especificada na coluna de tipo xml (CatalogDescription) no AdventureWorks2022 banco de dados. A consulta recupera valores de atributo ProductModelName de cada instância de XML armazenada na coluna.

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

Observação da consulta anterior:

  • A palavra-chave namespace é usada para definir um prefixo de namespace.

  • De acordo com as exigências de digitação estática, [1] é adicionado no final da expressão de caminho no método value() a fim de indicar explicitamente que a expressão de caminho retorna um singleton.

Veja a seguir o conjunto de resultados.

Touring-2000
Touring-1000
Road-450
Road-150
Mountain-500
Mountain 100

D. Use os métodos value() e exist() para recuperar valores de uma coluna do tipo XML

O exemplo a seguir demonstra o uso do método value() e do método exist() do tipo de dados xml. O método value() é usado para recuperar valores de atributo ProductModelID do XML. O método exist() na cláusulaWHERE é usado para filtrar as linhas da tabela.

A consulta recupera IDs de modelo de produto de instâncias XML que incluem informações de garantia (o elemento <Warranty>) como um dos recursos. A condição na cláusula WHERE usa o método exist() para recuperar apenas as linhas que satisfazem esta condição.

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;

Observação da consulta anterior:

  • A coluna CatalogDescription é uma coluna XML com tipo. Isso significa que ela possui uma coleção de esquema associada ao mesmo. No Modules and Prologs – XQuery Prolog, a declaração de namespace é usada para definir o prefixo usado posteriormente no corpo da consulta.

  • Se o exist() método retornar 1 (true), isso indicará que a instância XML inclui o <Warranty> elemento filho como um dos recursos.

  • O método value() na cláusula SELECT recupera os valores de atributo ProductModelID como inteiros.

Este é o resultado parcial:

19
23
...

E. Use o método exist() em vez do método value()

Por motivos de desempenho, em vez de usar o método value() em um predicado para comparar com um valor relacional, use exist() com sql:column(). Por exemplo:

CREATE TABLE T (c1 INT, c2 VARCHAR(10), c3 XML);
GO

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

Este código pode ser reescrito da seguinte forma:

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

Conteúdo relacionado