SELECT – Cláusula FOR (Transact-SQL)SELECT - FOR Clause (Transact-SQL)

APLICA-SE A: simSQL Server simBanco de Dados SQL do Azure nãoSQL Data Warehouse do Azure nãoParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Use a cláusula FOR para especificar uma das opções a seguir para os resultados da consulta.Use the FOR clause to specify one of the following options for query results.

  • Permita atualizações ao exibir os resultados da consulta em um cursor de modo de procura, especificando FOR BROWSE.Allow updates while viewing query results in a browse mode cursor by specifying FOR BROWSE.

  • Formate os resultados da consulta como XML, especificando FOR XML.Format query results as XML by specifying FOR XML.

  • Formate os resultados da consulta como JSON, especificando FOR JSON.Format query results as JSON by specifying FOR JSON.

Ícone de link do tópico Convenções de sintaxe de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

[ 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 BROWSEFOR BROWSE

BROWSEBROWSE
Especifica que as atualizações são permitidas ao exibir os dados em um cursor do modo de procura DB-Library.Specifies that updates be allowed while viewing the data in a DB-Library browse mode cursor. 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 ServerSQL Server.A table can be browsed in an application if the table includes a timestamp column, the table has a unique index, and the FOR BROWSE option is at the end of the SELECT statements sent to an instance of SQL ServerSQL Server.

Observação

Não é possível usar <lock_hint> HOLDLOCK em uma instrução SELECT que inclua a opção FOR BROWSE.You cannot use the <lock_hint> HOLDLOCK in a SELECT statement that includes the FOR BROWSE option.

FOR BROWSE não pode se aparecer em instruções SELECT que sejam unidas pelo operador UNION.FOR BROWSE cannot appear in SELECT statements that are joined by the UNION operator.

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.When the unique index key columns of a table are nullable, and the table is on the inner side of an outer join, the index is not supported by browse mode.

O modo de busca lhe permite verificar as linhas na tabela do SQL ServerSQL Server e atualizar os dados uma linha de cada vez na tabela.The browse mode lets you scan the rows in your SQL ServerSQL Server table and update the data in your table one row at a time. Para acessar uma tabela do SQL ServerSQL Server em seu aplicativo no modo de procura, use uma das duas opções a seguir:To access a SQL ServerSQL Server table in your application in the browse mode, you must use one of the following two options:

  • A instrução SELECT usada para acessar os dados na tabela SQL ServerSQL Server precisa terminar com as palavras-chave FOR BROWSE.The SELECT statement that you use to access the data from your SQL ServerSQL Server table must end with the keywords FOR BROWSE. Quando você ativa a opção FOR BROWSE para usar o modo de procura, são criadas tabelas temporárias.When you turn on the FOR BROWSE option to use browse mode, temporary tables are created.

  • Você precisa executar a seguinte instrução Transact-SQLTransact-SQL para ativar o modo de procura usando a opção NO_BROWSETABLE:You must run the following Transact-SQLTransact-SQL statement to turn on the browse mode by using the NO_BROWSETABLE option:

    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.When you turn on the NO_BROWSETABLE option, all the SELECT statements behave as if the FOR BROWSE option is appended to the statements. 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.However, the NO_BROWSETABLE option does not create the temporary tables that the FOR BROWSE option generally uses to send the results to your application.

Quando você tenta acessar os dados de tabelas do SQL ServerSQL 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.When you try to access the data from SQL ServerSQL Server tables in browse mode by using a SELECT query that involves an outer join statement, and when a unique index is defined on the table that is present on the inner side of an outer join statement, the browse mode does not support the unique index. O modo de busca somente dá suporte ao índice exclusivo quando todas as colunas de chave do índice exclusivo podem aceitar valores nulos.The browse mode supports the unique index only when all the unique index key columns can accept null values. O modo de busca não dará suporte ao índice exclusivo se as seguintes condições forem verdadeiras:The browse mode does not support the unique index if the following conditions are true:

  • Você tenta acessar os dados de tabelas do SQL ServerSQL Server no modo de procura usando uma consulta SELECT que envolve uma instrução de junção externa.You try to access the data from SQL ServerSQL Server tables in browse mode by using a SELECT query that involves an outer join statement.

  • Um índice exclusivo está definido na tabela presente no interior de uma instrução de junção externa.A unique index is defined on the table that is present on the inner side of an outer join statement.

Para reproduzir esse comportamento no modo de busca, siga estas etapas:To reproduce this behavior in the browse mode, follow these steps:

  1. No SQL Server Management StudioSQL Server Management Studio, crie um banco de dados denominado SampleDB.In SQL Server Management StudioSQL Server Management Studio, create a database, named SampleDB.

  2. No banco de dados SampleDB, crie uma tabela tleft e uma tabela tright com uma única coluna denominada c1.In the SampleDB database, create a tleft table and a tright table that both contain a single column that is named c1. Defina um índice exclusivo na coluna c1 na tabela tleft e defina a coluna para aceitar valores nulos.Define a unique index on the c1 column in the tleft table, and set the column to accept null values. Para fazer isso, execute as seguintes instruções Transact-SQLTransact-SQL em uma janela de consulta apropriada:To do this, run the following Transact-SQLTransact-SQL statements in an appropriate query window:

    CREATE TABLE tleft(c1 INT NULL UNIQUE) ;  
    GO   
    CREATE TABLE tright(c1 INT NULL) ;  
    GO  
    
  3. Insira vários valores nas tabelas tleft e tright.Insert several values in the tleft table and the tright table. Verifique se você inseriu um valor nulo na tabela tleft.Make sure that you insert a null value in the tleft table. Para fazer isso, execute as seguintes instruções Transact-SQLTransact-SQL na janela de consulta:To do this, run the following Transact-SQLTransact-SQL statements in the query window:

    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. Ative a opção NO_BROWSETABLE.Turn on the NO_BROWSETABLE option. Para fazer isso, execute as seguintes instruções Transact-SQLTransact-SQL na janela de consulta:To do this, run the following Transact-SQLTransact-SQL statements in the query window:

    SET NO_BROWSETABLE ON ;  
    GO  
    
  5. Acesse os dados nas tabelas tleft e tright usando uma instrução de junção externa na consulta SELECT.Access the data in the tleft table and the tright table by using an outer join statement in the SELECT query. Verifique se a tabela tleft está dentro da instrução de junção externa.Make sure that the tleft table is on the inner side of the outer join statement. Para fazer isso, execute as seguintes instruções Transact-SQLTransact-SQL na janela de consulta:To do this, run the following Transact-SQLTransact-SQL statements in the query window:

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

    Observe a seguinte saída no painel de Resultados:Notice the following output in the Results pane:

    c1c1

    ----

    NULLNULL

    NULLNULL

Depois que você executar a consulta SELECT para acessar as tabelas no modo de busca, o conjunto de resultados da consulta SELECT conterá dois valores nulos da coluna c1 na tabela tleft devido à definição da instrução de junção externa direita.After you run the SELECT query to access the tables in the browse mode, the result set of the SELECT query contains two null values for the c1 column in the tleft table because of the definition of the right outer join statement. Assim, no conjunto de resultados, não é possível distinguir entre os valores nulos provenientes da tabela e os valores nulos introduzidos pela instrução de junção externa.Therefore, in the result set, you cannot distinguish between the null values that came from the table and the null values that the right outer join statement introduced. Talvez você receba resultados incorretos se ignorar os valores nulos do conjunto de resultados.You might receive incorrect results if you must ignore the null values from the result set.

Observação

Se as colunas incluídas no índice exclusivo não aceitarem valores nulos, todos os valores nulos no conjunto de resultados foram introduzidos pela instrução de junção externa direita.If the columns that are included in the unique index do not accept null values, all the null values in the result set were introduced by the right outer join statement.

FOR XMLFOR XML

XMLXML
Especifica que os resultados de uma consulta serão retornados como um documento XML.Specifies that the results of a query are to be returned as an XML document. Um dos seguintes modos XML precisa ser especificado: RAW, AUTO, EXPLICIT.One of the following XML modes must be specified: RAW, AUTO, EXPLICIT. Para obter mais informações sobre dados XML e o SQL ServerSQL Server, confira FOR XML (SQL Server).For more information about XML data and SQL ServerSQL Server, see FOR XML (SQL Server).

RAW [ (' ElementName ') ]RAW [ ('ElementName') ]
Obtém o resultado da consulta e transforma cada linha do conjunto de resultados em um elemento XML com um identificador genérico <row /> como a marcação do elemento.Takes the query result and transforms each row in the result set into an XML element with a generic identifier <row /> as the element tag. Opcionalmente, é possível especificar um nome para o elemento de linha.You can optionally specify a name for the row element. A saída XML resultante usa o ElementName especificado como o elemento de linha gerado para cada linha.The resulting XML output uses the specified ElementName as the row element generated for each row. Para obter mais informações, consulte Usar modo RAW com FOR XML.For more information, see Use RAW Mode with FOR XML.

AUTOAUTO
Retorna os resultados da consulta em uma árvore XML simples e aninhada.Returns query results in a simple, nested XML tree. Cada tabela na cláusula FROM, para a qual pelo menos uma coluna esteja listada na cláusula SELECT, é representada como um elemento XML.Each table in the FROM clause, for which at least one column is listed in the SELECT clause, is represented as an XML element. As colunas listadas na cláusula SELECT são mapeadas para os atributos apropriados do elemento.The columns listed in the SELECT clause are mapped to the appropriate element attributes. Para obter mais informações, consulte Usar modo AUTO com FOR XML.For more information, see Use AUTO Mode with FOR XML.

EXPLICITEXPLICIT
Especifica que a forma da árvore XML resultante está explicitamente definida.Specifies that the shape of the resulting XML tree is defined explicitly. 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.Using this mode, queries must be written in a particular way so that additional information about the desired nesting is specified explicitly. Para obter mais informações, consulte Usar modo EXPLICIT com FOR XML.For more information, see Use EXPLICIT Mode with FOR XML.

XMLDATAXMLDATA
Retorna o esquema XDR embutido, mas não adiciona o elemento raiz ao resultado.Returns inline XDR schema, but does not add the root element to the result. Se XMLDATA for especificado, o esquema XDR será anexado ao documento.If XMLDATA is specified, XDR schema is appended to the document.

Importante

A diretiva XMLDATA foi preterida.The XMLDATA directive is deprecated. Use geração de XSD no caso dos modos RAW e AUTO.Use XSD generation in the case of RAW and AUTO modes. Não há substituição para a diretiva XMLDATA no modo EXPLICIT.There is no replacement for the XMLDATA directive in EXPLICIT mode. Este recurso está em modo de manutenção e talvez seja removido em uma versão futura do Microsoft SQL Server.This feature is in maintenance mode and may be removed in a future version of Microsoft SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam.Avoid using this feature in new development work, and plan to modify applications that currently use this feature.

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.Suppress unwanted line breaks: You might use SQL Server Management Studio (SSMS) to issue a query that uses the FOR XML clause. Às vezes, uma grande quantidade de XML é retornada e exibida na célula de uma grade.Sometimes a large amount of XML is returned and displayed in one grid cell. A cadeia de caracteres XML pode ser mais longa que uma célula de grade do SSMS e reter em uma única linha.The XML string could be longer than one SSMS grid cell can hold on a single line. Nesses casos, o SSMS pode inserir caracteres de quebra de linha entre segmentos longos de toda a cadeia de caracteres XML.In these cases, SSMS might insert line break characters between long segments of the whole XML string. Essas quebras de linha podem ocorrer no meio de uma subcadeia de caracteres que não deve ser dividida entre linhas.Such line breaks might occur in the middle of a substring that should not be split across lines. Você pode impedir quebras de linha usando uma conversão como XMLDATA.You can prevent the line breaks by using a cast AS XMLDATA. Essa solução também pode se aplicar ao usar FOR JSON PATH.This solution can also apply when you use FOR JSON PATH. A técnica é discutida no Stack Overflow e é mostrada na seguinte instrução SELECT de exemplo do Transact-SQL:The technique is discussed on Stack Overflow, and is shown in the following Transact-SQL sample SELECT statement:

XMLSCHEMA [ (' TargetNameSpaceURI ') ]XMLSCHEMA [ ('TargetNameSpaceURI') ]
Retorna o esquema XSD embutido.Returns inline XSD schema. Opcionalmente, você pode especificar um URI de namespace de destino ao especificar esta diretiva, o que retorna o namespace especificado no esquema.You can optionally specify a target namespace URI when you specify this directive, which returns the specified namespace in the schema. Para obter mais informações, consulte Gerar um esquema XSD embutido.For more information, see Generate an Inline XSD Schema.

ELEMENTSELEMENTS
Especifica que as colunas são retornadas como subelementos.Specifies that the columns are returned as subelements. Caso contrário, elas serão mapeadas para atributos XML.Otherwise, they are mapped to XML attributes. O suporte a esta opção é oferecido somente nos modos RAW, AUTO e PATH.This option is supported in RAW, AUTO and PATH modes only. Para obter mais informações, consulte Usar modo RAW com FOR XML.For more information, see Use RAW Mode with FOR XML.

XSINILXSINIL
Especifica que um elemento com o atributo xsi:nil definido como True será criado para valores de coluna NULL.Specifies that an element with xsi:nil attribute set to True be created for NULL column values. Esta opção pode ser especificada somente com a diretiva ELEMENTS.This option can only be specified with ELEMENTS directive. Para obter mais informações, consulte:For more information, see:

ABSENTABSENT
Indica que para valores de coluna nulos, os elementos XML correspondentes não serão adicionados ao resultado do XML.Indicates that for null column values, corresponding XML elements will not be added in the XML result. Especifique esta opção somente com ELEMENTS.Specify this option only with ELEMENTS.

PATH [ (' ElementName ') ]PATH [ ('ElementName') ]
Gera um wrapper de elemento <row> para cada linha no conjunto de resultados.Generates a <row> element wrapper for each row in the result set. Opcionalmente, você pode especificar um nome de elemento para o wrapper de elemento <row>.You can optionally specify an element name for the <row> element wrapper. Se uma cadeia de caracteres vazia for fornecida, como FOR XML PATH ( '' ) ), um elemento de wrapper não será gerado.If an empty string is provided, such as FOR XML PATH ('') ), a wrapper element is not generated. O uso de PATH pode fornecer uma alternativa mais simples a consultas escritas com o uso da diretiva EXPLICIT.Using PATH may provide a simpler alternative to queries written using the EXPLICIT directive. Para obter mais informações, consulte Usar modo PATH com FOR XML.For more information, see Use PATH Mode with FOR XML.

BINARY BASE64BINARY BASE64
Especifica que a consulta retorna os dados binários em formato binário codificado em base64.Specifies that the query returns the binary data in binary base64-encoded format. Ao recuperar dados binários usando o modo RAW e EXPLICIT, esta opção deve ser especificada.When you retrieve binary data by using RAW and EXPLICIT mode, this option must be specified. Este é o padrão no modo AUTO.This is the default in AUTO mode.

TYPETYPE
Especifica que a consulta retorna os resultados como um tipo XML.Specifies that the query returns results as xml type. Para obter mais informações, consulte Diretiva TYPE em consultas FOR XML.For more information, see TYPE Directive in FOR XML Queries.

ROOT [ (' RootName ') ]ROOT [ ('RootName') ]
Especifica que um único elemento de nível superior seja adicionado ao XML resultante.Specifies that a single top-level element be added to the resulting XML. Opcionalmente, é possível especificar o nome do elemento raiz a ser gerado.You can optionally specify the root element name to generate. Se o nome da raiz opcional não for especificado, o elemento padrão <root> será adicionado.If the optional root name is not specified, the default <root> element is added.

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

Exemplo de FOR XMLFOR XML Example

O exemplo a seguir especifica FOR XML AUTO com as opções TYPE e XMLSCHEMA.The following example specifies FOR XML AUTO with the TYPE and XMLSCHEMA options. Por causa da opção TYPE, o conjunto de resultados é retornado ao cliente como um tipo XML.Because of the TYPE option, the result set is returned to the client as an xml type. 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.The XMLSCHEMA option specifies that the inline XSD schema is included in the XML data returned, and the ELEMENTS option specifies that the XML result is element-centric.

USE AdventureWorks2012;  
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 JSONFOR JSON

JSONJSON
Especifique FOR JSON para retornar os resultados de uma consulta formatados como texto JSON.Specify FOR JSON to return the results of a query formatted as JSON text. Especifique também um dos seguintes modos JSON: AUTO ou PATH.You also have to specify one of the following JSON modes : AUTO or PATH. Para obter mais informações sobre a cláusula FOR JSON, confira Formatar os resultados da consulta como JSON com o FOR JSON (SQL Server).For more information about the FOR JSON clause, see Format Query Results as JSON with FOR JSON (SQL Server).

AUTOAUTO
Formatar a saída JSON automaticamente com base na estrutura da instrução SELECTFormat the JSON output automatically based on the structure of the SELECT statement
especificando FOR JSON AUTO.by specifying FOR JSON AUTO. Para mais informações e exemplos, consulte Formatar a saída JSON automaticamente com o modo AUTO (SQL Server).For more info and examples, see Format JSON Output Automatically with AUTO Mode (SQL Server).

PATHPATH
Obter controle total sobre o formato da saída JSON especificandoGet full control over the format of the JSON output by specifying
FOR JSON PATH.FOR JSON PATH. O modoPATH permite criar objetos wrapper e aninhar propriedades complexas.PATH mode lets you create wrapper objects and nest complex properties. Para mais informações e exemplos, consulte Formatar a saída JSON aninhada com modo PATH (SQL Server).For more info and examples, see Format Nested JSON Output with PATH Mode (SQL Server).

INCLUDE_NULL_VALUESINCLUDE_NULL_VALUES
Inclua valores nulos na saída JSON especificando a opção INCLUDE_NULL_VALUES com a cláusula FOR JSON.Include null values in the JSON output by specifying the INCLUDE_NULL_VALUES option with the FOR JSON clause. Se você não especificar essa opção, a saída não incluirá as propriedades JSON para valores nulo nos resultados da consulta.If you don't specify this option, the output does not include JSON properties for null values in the query results. Para obter mais informações e exemplos, confira Incluir valores nulos com a opção JSON INCLUDE_NULL_VALUES (SQL Server).For more info and examples, see Include Null Values in JSON Output with the INCLUDE_NULL_VALUES Option (SQL Server).

ROOT [ (' RootName ') ]ROOT [ ('RootName') ]
Adicione um único elemento de nível superior à saída JSON especificando a opção ROOT com a cláusula FOR JSON.Add a single, top-level element to the JSON output by specifying the ROOT option with the FOR JSON clause. Se você não especificar a opção ROOT , a saída JSON não terá um elemento raiz.If you don't specify the ROOT option, the JSON output doesn't have a root element. Para obter mais informações e exemplos, confira Adicionar um nó raiz à saída JSON com a opção ROOT (SQL Server).For more info and examples, see Add a Root Node to JSON Output with the ROOT Option (SQL Server).

WITHOUT_ARRAY_WRAPPERWITHOUT_ARRAY_WRAPPER
Remova os colchetes que envolvem a saída JSON por padrão, especificando a opção WITHOUT_ARRAY_WRAPPER com a cláusula FOR JSON.Remove the square brackets that surround the JSON output by default by specifying the WITHOUT_ARRAY_WRAPPER option with the FOR JSON clause. Se você não especificar essa opção, a saída JSON será colocada entre colchetes.If you don't specify this option, the JSON output is enclosed within square brackets. Use a opção WITHOUT_ARRAY_WRAPPER para gerar um único objeto JSON como saída.Use the WITHOUT_ARRAY_WRAPPER option to generate a single JSON object as output. Para obter mais informações, consulte Remove Square Brackets from JSON Output with the WITHOUT_ARRAY_WRAPPER Option (SQL Server) (Remover os colchetes da saída JSON com a opção WITHOUT_ARRAY_WRAPPER (SQL Server)).For more info, see Remove Square Brackets from JSON Output with the WITHOUT_ARRAY_WRAPPER Option (SQL Server).

Para obter mais informações, veja Formatar resultados da consulta como JSON com FOR JSON (SQL Server).For more info, see Format Query Results as JSON with FOR JSON (SQL Server).

Consulte TambémSee Also

SELECT (Transact-SQL)SELECT (Transact-SQL)