SELECT – Cláusula FOR (Transact-SQL)

Artigo
03/13/2025

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Ponto de extremidade de análise de SQL no Microsoft Fabric Warehouse no Microsoft Fabric Bancode dados SQL no Microsoft Fabric

Use a cláusula FOR para especificar uma das opções a seguir para os resultados da consulta.

Permitir atualizações ao exibir os resultados da consulta em um cursor de modo de navegação especificando FOR BROWSE.
Formate os resultados da consulta como XML especificando FOR XML.
Formate os resultados da consulta como JSON especificando FOR JSON.

Convenções de sintaxe de Transact-SQL

Sintaxe

[ 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

Especifica que as atualizações são permitidas ao exibir os dados em um cursor do modo de procura DB-Library. Será possível procurar em uma tabela em um aplicativo se ela incluir uma coluna timestamp, se ela tiver um índice exclusivo e a se opção FOR BROWSE estiver no final das instruções SELECT enviadas para uma instância do SQL Server.

Observação

Não é possível usar <lock_hint> HOLDLOCK em uma instrução SELECT que inclua a opção FOR BROWSE.

FOR BROWSE não pode se aparecer em instruções SELECT que sejam unidas pelo operador UNION.

Observação

Quando as colunas de chaves de índice exclusivo de uma tabela permitirem valor nulo e a tabela estiver no lado interno de uma junção externa, o modo de procura não oferece suporte para o índice.

O modo de busca lhe permite verificar as linhas na tabela do SQL Server e atualizar os dados uma linha de cada vez na tabela. Para acessar uma tabela do SQL Server em seu aplicativo no modo de procura, use uma das duas opções a seguir:

A instrução SELECT usada para acessar os dados na tabela SQL Server precisa terminar com as palavras-chave FOR BROWSE. Quando você ativa a opção FOR BROWSE para usar o modo de procura, são criadas tabelas temporárias.
Você precisa executar a seguinte instrução Transact-SQL para ativar o modo de procura usando a opção NO_BROWSETABLE:
```
SET NO_BROWSETABLE ON  
```
Quando você ativa a opção NO_BROWSETABLE, todas as instruções SELECT se comportam como se a opção FOR BROWSE estivesse acrescentada a elas. No entanto, a opção NO_BROWSETABLE não cria as tabelas temporárias que a opção FOR BROWSE geralmente usa para enviar os resultados para o aplicativo.

Quando você tenta acessar os dados de tabelas do SQL Server no modo de procura usando uma consulta SELECT que envolve uma instrução de junção externa e quando um índice exclusivo está definido na tabela presente no interior de uma instrução de junção externa, o modo de procura não permite o índice exclusivo. O modo de navegação dá suporte ao índice exclusivo somente quando todas as colunas de chave de índice exclusivas podem aceitar valores NULL. O modo de busca não dará suporte ao índice exclusivo se as seguintes condições forem verdadeiras:

Você tenta acessar os dados de tabelas do SQL Server no modo de procura usando uma consulta SELECT que envolve uma instrução de junção externa.
Um índice exclusivo está definido na tabela presente no interior de uma instrução de junção externa.

Para reproduzir esse comportamento no modo de busca, siga estas etapas:

No SQL Server Management Studio, crie um banco de dados chamado SampleDB.
No banco de dados SampleDB, crie uma tabela de tleft e uma tabela tright que contêm uma única coluna chamada c1. Defina um índice exclusivo na coluna c1 na tabela tleft e defina a coluna para aceitar valores NULL. Para fazer isso, execute as seguintes instruções Transact-SQL em uma janela de consulta apropriada:
```
CREATE TABLE tleft(c1 INT NULL UNIQUE) ;  
GO   
CREATE TABLE tright(c1 INT NULL) ;  
GO  
```

Insira vários valores na tabela tleft e na tabela tright. Insira um valor NULL na tabela tleft. Para fazer isso, execute as seguintes instruções Transact-SQL na janela de consulta:

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

Ative a opção NO_BROWSETABLE. Para fazer isso, execute as seguintes instruções Transact-SQL na janela de consulta:
```
SET NO_BROWSETABLE ON ;  
GO  
```
Acesse os dados na tabela tleft e na tabela tright usando uma instrução de junção externa na consulta SELECT. Verifique se a tabela tleft está no lado interno da instrução de junção externa. Para fazer isso, execute as seguintes instruções Transact-SQL na janela de consulta:
```
SELECT tleft.c1   
FROM tleft   
RIGHT JOIN tright   
ON tleft.c1 = tright.c1   
WHERE tright.c1 <> 2 ;
```
Observe a seguinte saída no painel resultados do:
```
c1  
---
NULL  
NULL  
```

Depois de executar a consulta SELECT para acessar as tabelas no modo de navegação, o conjunto de resultados da consulta SELECT contém dois valores NULL para a coluna c1 na tabela tleft devido à definição da instrução de junção externa direita. Portanto, no conjunto de resultados, você não pode distinguir entre os valores NULL provenientes da tabela e os valores NULL que a instrução de junção externa direita introduziu. Você poderá receber resultados incorretos se precisar ignorar os valores de NULL do conjunto de resultados.

Observação

Se as colunas incluídas no índice exclusivo não aceitarem valores NULL, todos os valores de NULL no conjunto de resultados serão introduzidos pela instrução de junção externa direita.

FOR XML

XML

Especifica que os resultados de uma consulta serão retornados como um documento XML. Um dos seguintes modos XML deve ser especificado: RAW, AUTO, EXPLICIT. Para obter mais informações sobre dados XML e o SQL Server, confira FOR XML (SQL Server).

RAW [ ('ElementName') ]

Usa o resultado da consulta e transforma cada linha no conjunto de resultados em um elemento XML com um identificador genérico <row /> como a marca de elemento. Opcionalmente, é possível especificar um nome para o elemento de linha. A saída XML resultante usa o ElementName especificado como o elemento de linha gerado para cada linha. Para obter mais informações, consulte Usar modo RAW com FOR XML.

AUTO

Retorna os resultados da consulta em uma árvore XML simples e aninhada. Cada tabela na cláusula FROM, para a qual pelo menos uma coluna está listada na cláusula SELECT, é representada como um elemento XML. As colunas listadas na cláusula SELECT são mapeadas para os atributos de elemento apropriados. Para obter mais informações, consulte Usar modo AUTO com FOR XML.

EXPLICIT

Especifica que a forma da árvore XML resultante está explicitamente definida. Ao usar este modo, as consultas devem ser gravadas de uma maneira específica para que as informações adicionais sobre o aninhamento desejado sejam especificadas explicitamente. Para obter mais informações, consulte Usar modo EXPLICIT com FOR XML.

XMLDATA

Retorna o esquema XDR embutido, mas não adiciona o elemento raiz ao resultado. Se XMLDATA for especificado, o esquema XDR será acrescentado ao documento.

Importante

A diretiva XMLDATA é preterida. Use geração de XSD no caso dos modos RAW e AUTO. Não há substituição para a diretiva XMLDATA no modo EXPLICIT. Esse recurso será removido em uma versão futura do SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam.

Suprimir quebras de linha indesejadas: Você pode usar o SSMS (SQL Server Management Studio) para emitir uma consulta que usa a cláusula FOR XML. Às vezes, uma grande quantidade de XML é retornada e exibida na célula de uma grade. A cadeia de caracteres XML pode ser mais longa que uma célula de grade do SSMS e reter em uma única linha. Nesses casos, o SSMS pode inserir caracteres de quebra de linha entre segmentos longos de toda a cadeia de caracteres XML. Essas quebras de linha podem ocorrer no meio de uma subcadeia de caracteres que não deve ser dividida entre linhas. Você pode impedir as quebras de linha usando um AS XMLDATAde conversão. Essa solução também pode ser aplicada quando você usa FOR JSON PATH, como na seguinte instrução SELECT de exemplo Transact-SQL:

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

XMLSCHEMA [ ('TargetNameSpaceURI') ]

Retorna o esquema XSD embutido. Opcionalmente, você pode especificar um URI de namespace de destino ao especificar esta diretiva, o que retorna o namespace especificado no esquema. Para obter mais informações, consulte Gerar um esquema XSD embutido.

ELEMENTS

Especifica que as colunas são retornadas como subelementos. Caso contrário, elas serão mapeadas para atributos XML. Essa opção tem suporte apenas nos modos RAW, AUTO e PATH. Para obter mais informações, consulte Usar modo RAW com FOR XML.

XSINIL

Especifica que um elemento com xsi:nil atributo definido como True ser criado para NULL valores de coluna. Essa opção só pode ser especificada com ELEMENTS diretiva. Para obter mais informações, consulte:

ABSENT

Indica que, para NULL valores de coluna, os elementos XML correspondentes não serão adicionados no resultado XML. Especifique esta opção somente com ELEMENTS.

PATH [ ('ElementName') ]

Gera um wrapper de elemento <row> para cada linha no conjunto de resultados. Opcionalmente, você pode especificar um nome de elemento para o wrapper de elemento <row>. Se uma cadeia de caracteres vazia for fornecida, como FOR XML PATH ('') ), um elemento wrapper não será gerado. Usar PATH pode fornecer uma alternativa mais simples para consultas escritas usando a diretiva EXPLICIT. Para obter mais informações, consulte Usar modo PATH com FOR XML.

BINARY BASE64

Especifica que a consulta retorna os dados binários em formato binário codificado em base64. Quando você recupera dados binários usando RAW e EXPLICIT modo, essa opção deve ser especificada. Esse é o padrão no modo AUTO.

TYPE

Especifica que a consulta retorna os resultados como um tipo XML. Para obter mais informações, consulte Diretiva TYPE em consultas FOR XML.

ROOT [ ('RootName') ]

Especifica que um único elemento de nível superior seja adicionado ao XML resultante. Opcionalmente, é possível especificar o nome do elemento raiz a ser gerado. Se o nome raiz opcional não for especificado, o elemento <root> padrão será adicionado.

Para obter mais informações, confira FOR XML (SQL Server).

Exemplo

O exemplo a seguir especifica FOR XML AUTO com as opções TYPE e XMLSCHEMA. Por causa da opção TYPE, o conjunto de resultados é retornado ao cliente como um tipo XML. A opção XMLSCHEMA especifica que o esquema XSD embutido é incluído nos dados XML retornados e a opção ELEMENTS especifica que o resultado XML é centrado em elemento.

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

Observações

No Fabric Data Warehouse, FOR JSON deve ser o último operador na consulta e, portanto, não é permitido dentro de subconsultas.

JSON

Especifique FOR JSON para retornar os resultados de uma consulta formatados como texto JSON. Especifique também um dos seguintes modos JSON: AUTO ou PATH. Para obter mais informações sobre a cláusula FOR JSON, consulte Formatar Resultados da Consulta como JSON com FOR JSON (SQL Server).

AUTO

Formate a saída JSON automaticamente com base na estrutura da instrução SELECT especificando FOR JSON AUTO. Para mais informações e exemplos, confira Formatar a Saída JSON Automaticamente com o Modo AUTO (SQL Server).

PATH

Obtenha controle total sobre o formato da saída JSON especificando FOR JSON PATH. PATH modo permite criar objetos wrapper e aninhar propriedades complexas. Para mais informações e exemplos, confira Formatar a Saída JSON Aninhada com Modo PATH (SQL Server).

INCLUDE_NULL_VALUES

Inclua NULL valores na saída JSON especificando a opção INCLUDE_NULL_VALUES com a cláusula FOR JSON. Se você não especificar essa opção, a saída não inclui propriedades JSON para valores NULL nos resultados da consulta. Para obter mais informações e exemplos, confira Incluir Valores Nulos com a Opção JSON INCLUDE_NULL_VALUES (SQL Server).

ROOT [ ('RootName') ]

Adicione um único elemento de nível superior à saída JSON especificando a opção ROOT com a cláusula FOR JSON. Se você não especificar a opção ROOT, a saída JSON não terá um elemento raiz. Para obter mais informações e exemplos, confira Adicionar um Nó Raiz à Saída JSON com a Opção ROOT (SQL Server).

WITHOUT_ARRAY_WRAPPER

Remova os colchetes que cercam a saída JSON por padrão especificando a opção WITHOUT_ARRAY_WRAPPER com a cláusula FOR JSON. Se você não especificar essa opção, a saída JSON será colocada entre colchetes. Use a opção WITHOUT_ARRAY_WRAPPER para gerar um único objeto JSON como saída. Para obter mais informações, confira Remover os Colchetes da Saída JSON com a Opção WITHOUT_ARRAY_WRAPPER (SQL Server).

Para obter mais informações, confira Formatar Resultados da Consulta como JSON com FOR JSON (SQL Server).

Compartilhar via

SELECT – Cláusula FOR (Transact-SQL)

Sintaxe

FOR BROWSE

BROWSE

FOR XML

XML

RAW [ ('ElementName') ]

AUTO

EXPLICIT

XMLDATA

XMLSCHEMA [ ('TargetNameSpaceURI') ]

ELEMENTS

XSINIL

ABSENT

PATH [ ('ElementName') ]

BINARY BASE64

TYPE

ROOT [ ('RootName') ]

Exemplo

FOR JSON

Observações

JSON

AUTO

PATH

INCLUDE_NULL_VALUES

ROOT [ ('RootName') ]

WITHOUT_ARRAY_WRAPPER

Comentários

Recursos adicionais

Compartilhar via

SELECT – Cláusula FOR (Transact-SQL)

Sintaxe

FOR BROWSE

BROWSE

FOR XML

XML

RAW [ ('ElementName') ]

AUTO

EXPLICIT

XMLDATA

XMLSCHEMA [ ('TargetNameSpaceURI') ]

ELEMENTS

XSINIL

ABSENT

PATH [ ('ElementName') ]

BINARY BASE64

TYPE

ROOT [ ('RootName') ]

Exemplo

FOR JSON

Observações

JSON

AUTO

PATH

INCLUDE_NULL_VALUES

ROOT [ ('RootName') ]

WITHOUT_ARRAY_WRAPPER

Conteúdo relacionado

Comentários

Recursos adicionais