cláusula OUTPUT (Transact-SQL)OUTPUT Clause (Transact-SQL)

APLICA-SE A: simSQL Server simBanco de Dados SQL do Azure nãoAzure Synapse Analytics (SQL DW) nãoParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database noAzure Synapse Analytics (SQL DW) noParallel Data Warehouse

Retorna informações ou expressões baseadas em cada linha afetada por uma instrução INSERT, UPDATE, DELETE ou MERGE.Returns information from, or expressions based on, each row affected by an INSERT, UPDATE, DELETE, or MERGE statement. Esses resultados podem ser retornados ao aplicativo de processamento para uso em mensagens de confirmação, arquivamentos e outros requisitos similares de aplicativo.These results can be returned to the processing application for use in such things as confirmation messages, archiving, and other such application requirements. Os resultados também podem ser inseridos em uma tabela ou variável de tabela.The results can also be inserted into a table or table variable. Além disso, você pode capturar os resultados de uma cláusula OUTPUT em uma instrução INSERT, UPDATE, DELETE ou MERGE aninhada e inserir esses resultados em uma tabela ou exibição de destino.Additionally, you can capture the results of an OUTPUT clause in a nested INSERT, UPDATE, DELETE, or MERGE statement, and insert those results into a target table or view.

Observação

Uma instrução UPDATE, INSERT ou DELETE que tem uma cláusula OUTPUT retornará linhas ao cliente mesmo que a instrução encontre erros e seja revertida.An UPDATE, INSERT, or DELETE statement that has an OUTPUT clause will return rows to the client even if the statement encounters errors and is rolled back. O resultado não deverá ser usado se ocorrer algum erro quando você executar a instrução.The result should not be used if any error occurs when you run the statement.

Usado em:Used in:

DELETEDELETE

INSERTINSERT

UPDATEUPDATE

MERGEMERGE

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

SintaxeSyntax

  
<OUTPUT_CLAUSE> ::=  
{  
    [ OUTPUT <dml_select_list> INTO { @table_variable | output_table } [ ( column_list ) ] ]  
    [ OUTPUT <dml_select_list> ]  
}  
<dml_select_list> ::=  
{ <column_name> | scalar_expression } [ [AS] column_alias_identifier ]  
    [ ,...n ]  
  
<column_name> ::=  
{ DELETED | INSERTED | from_table_name } . { * | column_name }  
    | $action  

ArgumentosArguments

@table_variable@table_variable
Especifica uma variável table na qual as linhas retornadas são inseridas, em vez de serem retornadas ao chamador.Specifies a table variable that the returned rows are inserted into instead of being returned to the caller. @table_variable precisa ser declarada antes da instrução INSERT, UPDATE, DELETE ou MERGE.@table_variable must be declared before the INSERT, UPDATE, DELETE, or MERGE statement.

Se column_list não for especificada, a variável table precisará ter o mesmo número de colunas que o conjunto de resultados de OUTPUT.If column_list is not specified, the table variable must have the same number of columns as the OUTPUT result set. As colunas de identidade e as colunas computadas são exceções, que devem ser ignoradas.The exceptions are identity and computed columns, which must be skipped. Se column_list for especificada, as colunas omitidas precisarão permitir valores nulos ou ter valores padrão atribuídos.If column_list is specified, any omitted columns must either allow null values or have default values assigned to them.

Para obter mais informações sobre as variáveis table, confira table (Transact-SQL).For more information about table variables, see table (Transact-SQL).

output_tableoutput_table
Especifica uma tabela na qual as linhas retornadas são inseridas, em vez de serem retornadas ao chamador.Specifies a table that the returned rows are inserted into instead of being returned to the caller. output_table pode ser uma tabela temporária.output_table may be a temporary table.

Se column_list não for especificada, a tabela precisará ter o mesmo número de colunas que o conjunto de resultados de OUTPUT.If column_list is not specified, the table must have the same number of columns as the OUTPUT result set. As colunas de identidade e as colunas computadas são exceções.The exceptions are identity and computed columns. Elas devem ser ignoradas.These must be skipped. Se column_list for especificada, as colunas omitidas precisarão permitir valores nulos ou ter valores padrão atribuídos.If column_list is specified, any omitted columns must either allow null values or have default values assigned to them.

output_table não pode:output_table cannot:

  • Ter gatilhos habilitados definidos.Have enabled triggers defined on it.

  • Participar de uma restrição FOREIGN KEY de nenhuma forma.Participate on either side of a FOREIGN KEY constraint.

  • Ter restrições CHECK ou regras habilitadas.Have CHECK constraints or enabled rules.

column_listcolumn_list
É uma lista opcional de nomes de coluna na tabela de destino da cláusula INTO.Is an optional list of column names on the target table of the INTO clause. Ela é semelhante à lista de colunas permitida na instrução INSERT.It is analogous to the column list allowed in the INSERT statement.

scalar_expressionscalar_expression
É qualquer combinação de símbolos e operadores que avalia um mesmo valor.Is any combination of symbols and operators that evaluates to a single value. As funções de agregação não são permitidas na scalar_expression.Aggregate functions are not permitted in scalar_expression.

Qualquer referência a colunas na tabela que está sendo modificada deve estar qualificada com o prefixo INSERTED ou DELETED.Any reference to columns in the table being modified must be qualified with the INSERTED or DELETED prefix.

column_alias_identifiercolumn_alias_identifier
É um nome alternativo usado como referência ao nome de coluna.Is an alternative name used to reference the column name.

DELETEDDELETED
É um prefixo de coluna que especifica o valor excluído pela operação de atualização ou exclusão.Is a column prefix that specifies the value deleted by the update or delete operation. Colunas prefixadas com DELETED refletem o valor antes de a instrução UPDATE, DELETE ou MERGE ser concluída.Columns prefixed with DELETED reflect the value before the UPDATE, DELETE, or MERGE statement is completed.

DELETED não pode ser usado com a cláusula OUTPUT na instrução INSERT.DELETED cannot be used with the OUTPUT clause in the INSERT statement.

INSERTEDINSERTED
É um prefixo de coluna que especifica o valor adicionado pela operação de inserção ou atualização.Is a column prefix that specifies the value added by the insert or update operation. Colunas prefixadas com INSERTED refletem o valor depois da conclusão da instrução UPDATE, INSERT ou MERGE, mas antes da execução dos gatilhos.Columns prefixed with INSERTED reflect the value after the UPDATE, INSERT, or MERGE statement is completed but before triggers are executed.

INSERTED não pode ser usado com a cláusula OUTPUT na instrução DELETE.INSERTED cannot be used with the OUTPUT clause in the DELETE statement.

from_table_namefrom_table_name
É um prefixo de coluna que especifica uma tabela incluída na cláusula FROM de uma instrução DELETE, UPDATE ou MERGE utilizada para especificar as linhas a serem atualizadas ou excluídas.Is a column prefix that specifies a table included in the FROM clause of a DELETE, UPDATE, or MERGE statement that is used to specify the rows to update or delete.

Se a tabela que está sendo modificada também estiver especificada na cláusula FROM, toda a referência a colunas nessa tabela também deverá estar qualificada com o prefixo INSERTED ou DELETED.If the table being modified is also specified in the FROM clause, any reference to columns in that table must be qualified with the INSERTED or DELETED prefix.

*
Especifica que todas as colunas afetadas pela ação de exclusão, inserção ou atualização serão retornadas na ordem em que aparecem na tabela.Specifies that all columns affected by the delete, insert, or update action will be returned in the order in which they exist in the table.

Por exemplo, OUTPUT DELETED.* na instrução DELETE a seguir retorna todas as colunas excluídas da tabela ShoppingCartItem:For example, OUTPUT DELETED.* in the following DELETE statement returns all columns deleted from the ShoppingCartItem table:

DELETE Sales.ShoppingCartItem  
    OUTPUT DELETED.*;  

column_namecolumn_name
É uma referência de coluna explícita.Is an explicit column reference. Toda referência à tabela que está sendo modificada deve ser corretamente qualificada pelo prefixo INSERTED ou DELETED, conforme apropriado, por exemplo: INSERTED . column_name.Any reference to the table being modified must be correctly qualified by either the INSERTED or the DELETED prefix as appropriate, for example: INSERTED .column_name.

$action$action
Está disponível apenas para a instrução MERGE.Is available only for the MERGE statement. Especifica uma coluna do tipo nvarchar(10) na cláusula OUTPUT em uma instrução MERGE que retorna um entre três valores para cada linha: 'INSERT', 'UPDATE' ou 'DELETE', de acordo com a ação que foi executada nessa linha.Specifies a column of type nvarchar(10) in the OUTPUT clause in a MERGE statement that returns one of three values for each row: 'INSERT', 'UPDATE', or 'DELETE', according to the action that was performed on that row.

RemarksRemarks

A cláusula OUTPUT <dml_select_list> e a cláusula OUTPUT <dml_select_list> INTO { @ table_variable | output_table } pode ser definida em uma única instrução INSERT, UPDATE, DELETE ou MERGE.The OUTPUT <dml_select_list> clause and the OUTPUT <dml_select_list> INTO { @table_variable | output_table } clause can be defined in a single INSERT, UPDATE, DELETE, or MERGE statement.

Observação

Salvo indicação em contrário, as referências à cláusula OUTPUT se referem tanto à cláusula OUTPUT, quanto à cláusula OUTPUT INTO.Unless specified otherwise, references to the OUTPUT clause refer to both the OUTPUT clause and the OUTPUT INTO clause.

A cláusula OUTPUT pode ser útil para recuperar o valor de identidade ou colunas computadas depois de uma operação INSERT ou UPDATE.The OUTPUT clause may be useful to retrieve the value of identity or computed columns after an INSERT or UPDATE operation.

Quando uma coluna computada é incluída na <dml_select_list>, a coluna correspondente na tabela de saída ou na variável de tabela não é uma coluna computada.When a computed column is included in the <dml_select_list>, the corresponding column in the output table or table variable is not a computed column. Os valores na nova coluna são aqueles que foram computados no momento em que a instrução foi executada.The values in the new column are the values that were computed at the time the statement was executed.

Não há nenhuma garantia de que a ordem na qual as alterações são aplicadas à tabela e a ordem na qual as linhas são inseridas na tabela de saída ou na variável de tabela correspondam.There is no guarantee that the order in which the changes are applied to the table and the order in which the rows are inserted into the output table or table variable will correspond.

Se forem modificados parâmetros ou variáveis como parte de uma instrução UPDATE, a cláusula OUTPUT sempre retornará o valor do parâmetro ou a variável como era antes de a instrução ser executada, e não o valor modificado.If parameters or variables are modified as part of an UPDATE statement, the OUTPUT clause always returns the value of the parameter or variable as it was before the statement executed instead of the modified value.

Você pode usar OUTPUT com uma instrução UPDATE ou DELETE posicionada em um cursor que use a sintaxe WHERE CURRENT OF.You can use OUTPUT with an UPDATE or DELETE statement positioned on a cursor that uses WHERE CURRENT OF syntax.

Não há suporte para a cláusula OUTPUT nas seguintes instruções:The OUTPUT clause is not supported in the following statements:

  • Instruções DML que façam referência a exibições particionadas locais, exibições particionadas distribuídas ou tabelas remotas.DML statements that reference local partitioned views, distributed partitioned views, or remote tables.

  • Instruções INSERT contendo uma instrução EXECUTE.INSERT statements that contain an EXECUTE statement.

  • Não são permitidos predicados de texto completo na cláusula OUTPUT quando o nível de compatibilidade de banco de dados é definido como 100.Full-text predicates are not allowed in the OUTPUT clause when the database compatibility level is set to 100.

  • A cláusula OUTPUT INTO não pode ser usada para inserção em uma exibição ou função de conjunto de linhas.The OUTPUT INTO clause cannot be used to insert into a view, or rowset function.

  • Não é possível criar uma função definida pelo usuário caso ela contenha uma cláusula OUTPUT INTO que tenha uma tabela como seu destino.A user-defined function cannot be created if it contains an OUTPUT INTO clause that has a table as its target.

Para impedir um comportamento não determinista, a cláusula OUTPUT não pode conter as referências a seguir:To prevent nondeterministic behavior, the OUTPUT clause cannot contain the following references:

  • Subconsultas ou funções definidas pelo usuário que executam acesso a dados pelo usuário ou sistema ou que assumem que executam tal acesso.Subqueries or user-defined functions that perform user or system data access, or are assumed to perform such access. Supõe-se que as funções definidas pelo usuário executam acesso a dados quando não são associadas a esquema.User-defined functions are assumed to perform data access if they are not schema-bound.

  • Uma coluna de uma função com valor de tabela embutida ou exibição quando essa coluna é definida por um dos seguintes métodos:A column from a view or inline table-valued function when that column is defined by one of the following methods:

    • Uma subconsulta.A subquery.

    • Uma função definida pelo usuário que executa acesso a dados de usuário ou de sistema ou que supostamente executa tal acesso.A user-defined function that performs user or system data access, or is assumed to perform such access.

    • Uma coluna computada que contém uma função definida pelo usuário e que executa acesso a dados de usuário ou de sistema em sua definição.A computed column that contains a user-defined function that performs user or system data access in its definition.

    Quando SQL ServerSQL Server detectar tal coluna na cláusula OUTPUT, ocorrerá o erro 4186.When SQL ServerSQL Server detects such a column in the OUTPUT clause, error 4186 is raised.

Inserindo dados retornados de uma cláusula OUTPUT em uma tabelaInserting Data Returned From an OUTPUT Clause Into a Table

Ao capturar os resultados de uma cláusula OUTPUT em uma instrução INSERT, UPDATE, DELETE ou MERGE aninhada e inserir esses resultados em uma tabela ou exibição de destino, lembre-se do seguinte:When you are capturing the results of an OUTPUT clause in a nested INSERT, UPDATE, DELETE, or MERGE statement and inserting those results into a target table, keep the following information in mind:

  • Toda a operação é atômica.The whole operation is atomic. As instruções INSERT interna e DML aninhada que contêm a cláusula OUTPUT cláusula são executadas ou falham inteiramente.Either both the INSERT statement and the nested DML statement that contains the OUTPUT clause execute, or the whole statement fails.

  • As seguintes restrições aplicam-se ao destino da instrução INSERT exterior:The following restrictions apply to the target of the outer INSERT statement:

    • O destino não pode ser uma tabela remota, exibição ou expressão de tabela comum.The target cannot be a remote table, view, or common table expression.

    • O destino não pode ter uma restrição FOREIGN KEY nem ser referenciado por uma restrição FOREIGN KEY.The target cannot have a FOREIGN KEY constraint, or be referenced by a FOREIGN KEY constraint.

    • Não podem ser definidos gatilhos no destino.Triggers cannot be defined on the target.

    • O gatilho não pode participar de replicação de mesclagem ou de assinaturas atualizáveis para replicação transacional.The target cannot participate in merge replication or updatable subscriptions for transactional replication.

  • As seguintes restrições aplicam-se à instrução DML aninhada:The following restrictions apply to the nested DML statement:

    • O destino não pode ser uma tabela remota ou exibição particionada.The target cannot be a remote table or partitioned view.

    • A origem em si não pode conter uma cláusula <dml_table_source>.The source itself cannot contain a <dml_table_source> clause.

  • A cláusula OUTPUT INTO não é compatível com instruções INSERT que contêm uma cláusula <dml_table_source>.The OUTPUT INTO clause is not supported in INSERT statements that contain a <dml_table_source> clause.

  • @@ROWCOUNT retorna as linhas inseridas apenas pela instrução INSERT externa.@@ROWCOUNT returns the rows inserted only by the outer INSERT statement.

  • @@IDENTITY, SCOPE_IDENTITY e IDENT_CURRENT retornam valores de identidade gerados apenas pela instrução DML aninhada, e não os valores gerados pela instrução INSERT externa.@@IDENTITY, SCOPE_IDENTITY, and IDENT_CURRENT return identity values generated only by the nested DML statement, and not those generated by the outer INSERT statement.

  • As notificações de consulta tratam a instrução como uma única entidade, e o tipo de qualquer mensagem criada será o tipo DML aninhado, mesmo que alteração significativa seja proveniente da própria instrução INSERT.Query notifications treat the statement as a single entity, and the type of any message that is created will be the type of the nested DML, even if the significant change is from the outer INSERT statement itself.

  • Na cláusula <dml_table_source>, as cláusulas SELECT e WHERE não podem conter subconsultas, funções de agregação, funções de classificação, predicados de texto completo, funções definidas pelo usuário que executam acesso a dados nem a função TEXTPTR.In the <dml_table_source> clause, the SELECT and WHERE clauses cannot include subqueries, aggregate functions, ranking functions, full-text predicates, user-defined functions that perform data access, or the TEXTPTR function.

ParallelismParallelism

Uma cláusula OUTPUT que retorna resultados para o cliente sempre usará um plano serial.An OUTPUT clause that returns results to the client will always use a serial plan.

No contexto de um banco de dados definido com o nível de compatibilidade 130 ou superior, se uma operação INSERT...SELECT usar uma dica WITH (TABLOCK) para a instrução SELECT e também usar OUTPUT…INTO para inserir em uma tabela temporária ou de usuário, a tabela de destino da instrução INSERT…SELECT será qualificada para o paralelismo, dependendo do custo da subárvore.In the context of a database set to compatibility level 130 or higher, if an INSERT...SELECT operation uses a WITH (TABLOCK) hint for the SELECT statement and also uses OUTPUT...INTO to insert into a temporary or user table, then the target table for the INSERT...SELECT will be eligible for parallelism depending on the subtree cost. A tabela de destino referenciada na cláusula OUTPUT INTO não será qualificada para o paralelismo.The target table referenced in the OUTPUT INTO clause will not be eligible for parallelism.

GatilhosTriggers

Colunas retornadas de OUTPUT refletem os dados da forma em que se encontram após a conclusão da instrução UPDATE, INSERT ou MERGE, mas antes da execução dos gatilhos.Columns returned from OUTPUT reflect the data as it is after the INSERT, UPDATE, or DELETE statement has completed but before triggers are executed.

No caso dos gatilhos INSTEAD OF, os resultados retornados são gerados como se INSERT, UPDATE ou DELETE tivesse ocorrido de fato, mesmo que nenhuma modificação aconteça como resultado da operação do gatilho.For INSTEAD OF triggers, the returned results are generated as if the INSERT, UPDATE, or DELETE had actually occurred, even if no modifications take place as the result of the trigger operation. Se uma instrução que inclui uma cláusula OUTPUT for usada dentro do corpo de um disparador, devem ser usados aliases de tabela para fazer referência às tabelas inseridas e excluídas pelo disparador, para evitar referências duplicadas a colunas com as tabelas INSERTED e DELETED associadas à OUTPUT.If a statement that includes an OUTPUT clause is used inside the body of a trigger, table aliases must be used to reference the trigger inserted and deleted tables to avoid duplicating column references with the INSERTED and DELETED tables associated with OUTPUT.

Se a cláusula OUTPUT for especificada sem especificação da palavra-chave INTO, o destino da operação de DML não poderá ter um gatilho habilitado definido para a ação DML fornecida.If the OUTPUT clause is specified without also specifying the INTO keyword, the target of the DML operation cannot have any enabled trigger defined on it for the given DML action. Por exemplo, se a cláusula OUTPUT estiver definida em uma instrução UPDATE, a tabela de destino não poderá ter nenhum gatilho UPDATE habilitado.For example, if the OUTPUT clause is defined in an UPDATE statement, the target table cannot have any enabled UPDATE triggers.

Se a opção sp_configure disallow results from triggers estiver definida, uma cláusula OUTPUT sem cláusula INTO fará com que a instrução falhe quando ela for invocada a partir de um disparador.If the sp_configure option disallow results from triggers is set, an OUTPUT clause without an INTO clause causes the statement to fail when it is invoked from within a trigger.

Tipos de dadosData Types

A cláusula OUTPUT é compatível com os tipos de dados de objeto grande: nvarchar(max) , varchar(max) , varbinary(max) , text, ntext, image e xml.The OUTPUT clause supports the large object data types: nvarchar(max), varchar(max), varbinary(max), text, ntext, image, and xml. Quando você usar a cláusula .WRITE na instrução UPDATE para modificar uma coluna nvarchar(max) , varchar(max) ou varbinary(max) , as imagens completas de antes e depois dos valores serão retornadas se forem referenciadas.When you use the .WRITE clause in the UPDATE statement to modify an nvarchar(max), varchar(max), or varbinary(max) column, the full before and after images of the values are returned if they are referenced. A função TEXTPTR( ) não pode fazer parte de uma expressão em uma coluna text, ntext ou image na cláusula OUTPUT.The TEXTPTR( ) function cannot appear as part of an expression on a text, ntext, or image column in the OUTPUT clause.

FilasQueues

Você pode usar OUTPUT em aplicativos que usam tabelas como filas ou para manter conjuntos de resultados intermediários.You can use OUTPUT in applications that use tables as queues, or to hold intermediate result sets. Ou seja, o aplicativo está somando ou removendo linhas constantemente da tabela.That is, the application is constantly adding or removing rows from the table. O exemplo a seguir usa a cláusula OUTPUT em uma instrução DELETE para retornar a linha excluída para o aplicativo de chamada.The following example uses the OUTPUT clause in a DELETE statement to return the deleted row to the calling application.

USE AdventureWorks2012;  
GO  
DELETE TOP(1) dbo.DatabaseLog WITH (READPAST)  
OUTPUT deleted.*  
WHERE DatabaseLogID = 7;  
GO  
  

Este exemplo remove uma linha de uma tabela usada como fila e retorna os valores excluídos para o aplicativo de processamento em uma única ação.This example removes a row from a table used as a queue and returns the deleted values to the processing application in a single action. Outras semânticas também podem ser implementadas, como usar uma tabela para implementar uma pilha.Other semantics may also be implemented, such as using a table to implement a stack. Porém, o SQL ServerSQL Server não garante a ordem em que as linhas são processadas e retornadas por instruções DML que usam a cláusula OUTPUT.However, SQL ServerSQL Server does not guarantee the order in which rows are processed and returned by DML statements using the OUTPUT clause. Cabe ao aplicativo incluir uma cláusula WHERE apropriada que possa garantir a semântica desejada ou entender que, quando várias linhas puderem se qualificar para a operação DML, não haverá nenhuma garantia de ordem.It is up to the application to include an appropriate WHERE clause that can guarantee the desired semantics, or understand that when multiple rows may qualify for the DML operation, there is no guaranteed order. O exemplo a seguir usa uma subconsulta e presume que exclusividade seja uma característica da coluna DatabaseLogID para implementar a semântica de ordenação desejada.The following example uses a subquery and assumes uniqueness is a characteristic of the DatabaseLogID column in order to implement the desired ordering semantics.

USE tempdb;  
GO  
CREATE TABLE dbo.table1  
(  
    id INT,  
    employee VARCHAR(32)  
);  
GO  
  
INSERT INTO dbo.table1 VALUES   
      (1, 'Fred')  
     ,(2, 'Tom')  
     ,(3, 'Sally')  
     ,(4, 'Alice');  
GO  
  
DECLARE @MyTableVar TABLE  
(  
    id INT,  
    employee VARCHAR(32)  
);  
  
PRINT 'table1, before delete'   
SELECT * FROM dbo.table1;  
  
DELETE FROM dbo.table1  
OUTPUT DELETED.* INTO @MyTableVar  
WHERE id = 4 OR id = 2;  
  
PRINT 'table1, after delete'  
SELECT * FROM dbo.table1;  
  
PRINT '@MyTableVar, after delete'  
SELECT * FROM @MyTableVar;  
  
DROP TABLE dbo.table1;  
  
--Results  
--table1, before delete  
--id          employee  
------------- ------------------------------  
--1           Fred  
--2           Tom  
--3           Sally  
--4           Alice  
--  
--table1, after delete  
--id          employee  
------------- ------------------------------  
--1           Fred  
--3           Sally  
--@MyTableVar, after delete  
--id          employee  
------------- ------------------------------  
--2           Tom  
--4           Alice  
  

Observação

Use a dica de tabela READPAST nas instruções UPDATE e DELETE, se o cenário permitir que vários aplicativos executem uma leitura destrutiva de uma tabela.Use the READPAST table hint in UPDATE and DELETE statements if your scenario allows for multiple applications to perform a destructive read from one table. Isso impedirá que venham a acontecer problemas de bloqueios, caso outro aplicativo já esteja lendo o primeiro registro de qualificação na tabela.This prevents locking issues that can come up if another application is already reading the first qualifying record in the table.

PermissõesPermissions

São necessárias permissões SELECT nas colunas recuperadas por meio de <dml_select_list> ou usadas em <scalar_expression>.SELECT permissions are required on any columns retrieved through <dml_select_list> or used in <scalar_expression>.

São necessárias permissões INSERT nas tabelas especificadas em <output_table>.INSERT permissions are required on any tables specified in <output_table>.

ExemplosExamples

A.A. Usando OUTPUT INTO com uma instrução INSERT simplesUsing OUTPUT INTO with a simple INSERT statement

O exemplo a seguir insere uma linha na tabela ScrapReason e usa a cláusula OUTPUT para retornar os resultados da instrução para a variável @MyTableVar``table.The following example inserts a row into the ScrapReason table and uses the OUTPUT clause to return the results of the statement to the @MyTableVar``table variable. Como a coluna ScrapReasonID está definida com uma propriedade IDENTITY, não é especificado um valor na instrução INSERT dessa coluna.Because the ScrapReasonID column is defined with an IDENTITY property, a value is not specified in the INSERT statement for that column. Porém, note que o valor gerado pelo Mecanismo de Banco de DadosDatabase Engine para a coluna é retornado na cláusula OUTPUT na coluna inserted.ScrapReasonID.However, note that the value generated by the Mecanismo de Banco de DadosDatabase Engine for that column is returned in the OUTPUT clause in the column inserted.ScrapReasonID.

USE AdventureWorks2012;  
GO  
DECLARE @MyTableVar table( NewScrapReasonID smallint,  
                           Name varchar(50),  
                           ModifiedDate datetime);  
INSERT Production.ScrapReason  
    OUTPUT INSERTED.ScrapReasonID, INSERTED.Name, INSERTED.ModifiedDate  
        INTO @MyTableVar  
VALUES (N'Operator error', GETDATE());  
  
--Display the result set of the table variable.  
SELECT NewScrapReasonID, Name, ModifiedDate FROM @MyTableVar;  
--Display the result set of the table.  
SELECT ScrapReasonID, Name, ModifiedDate   
FROM Production.ScrapReason;  
GO  
  

B.B. Usando OUTPUT com uma instrução DELETEUsing OUTPUT with a DELETE statement

O exemplo a seguir exclui todas as linhas da tabela ShoppingCartItem.The following example deletes all rows in the ShoppingCartItem table. A cláusula OUTPUT deleted.* especifica que os resultados da instrução DELETE, que são todas as colunas nas linhas excluídas, sejam retornados para o aplicativo de chamada.The clause OUTPUT deleted.* specifies that the results of the DELETE statement, that is all columns in the deleted rows, be returned to the calling application. A instrução SELECT que segue verifica os resultados da operação de exclusão na tabela ShoppingCartItem.The SELECT statement that follows verifies the results of the delete operation on the ShoppingCartItem table.

USE AdventureWorks2012;  
GO  
DELETE Sales.ShoppingCartItem  
OUTPUT DELETED.*   
WHERE ShoppingCartID = 20621;  
  
--Verify the rows in the table matching the WHERE clause have been deleted.  
SELECT COUNT(*) AS [Rows in Table] FROM Sales.ShoppingCartItem WHERE ShoppingCartID = 20621;  
GO  
  

C.C. Usando OUTPUT INTO com uma instrução UPDATEUsing OUTPUT INTO with an UPDATE statement

O exemplo a seguir atualiza a coluna VacationHours na tabela Employee em 25% nas primeiras 10 linhas.The following example updates the VacationHours column in the Employee table by 25 percent for the first 10 rows. A cláusula OUTPUT retorna o valor de VacationHours existente antes da aplicação da instrução UPDATE na coluna deleted.VacationHours e o valor atualizado na coluna inserted.VacationHours para a variável de tabela @MyTableVar.The OUTPUT clause returns the VacationHours value that exists before applying the UPDATE statement in the column deleted.VacationHours, and the updated value in the column inserted.VacationHours to the @MyTableVar table variable.

Seguem duas instruções SELECT que retornam os valores em @MyTableVar e os resultados da operação de atualização na tabela Employee.Two SELECT statements follow that return the values in @MyTableVar and the results of the update operation in the Employee table.

USE AdventureWorks2012;  
GO  
  
DECLARE @MyTableVar table(  
    EmpID int NOT NULL,  
    OldVacationHours int,  
    NewVacationHours int,  
    ModifiedDate datetime);  
  
UPDATE TOP (10) HumanResources.Employee  
SET VacationHours = VacationHours * 1.25,  
    ModifiedDate = GETDATE()   
OUTPUT inserted.BusinessEntityID,  
       deleted.VacationHours,  
       inserted.VacationHours,  
       inserted.ModifiedDate  
INTO @MyTableVar;  
  
--Display the result set of the table variable.  
SELECT EmpID, OldVacationHours, NewVacationHours, ModifiedDate  
FROM @MyTableVar;  
GO  
--Display the result set of the table.  
SELECT TOP (10) BusinessEntityID, VacationHours, ModifiedDate  
FROM HumanResources.Employee;  
GO  
  

D.D. Usando OUTPUT INTO para retornar uma expressãoUsing OUTPUT INTO to return an expression

O exemplo a seguir se baseia no exemplo C, definindo uma expressão na cláusula OUTPUT como diferença entre o valor VacationHours atualizado e o valor VacationHours antes de a atualização ser aplicada.The following example builds on example C by defining an expression in the OUTPUT clause as the difference between the updated VacationHours value and the VacationHours value before the update was applied. O valor dessa expressão é retornado para a variável @MyTableVar``table na coluna VacationHoursDifference.The value of this expression is returned to the @MyTableVar``table variable in the column VacationHoursDifference.

USE AdventureWorks2012;  
GO  
DECLARE @MyTableVar table(  
    EmpID int NOT NULL,  
    OldVacationHours int,  
    NewVacationHours int,  
    VacationHoursDifference int,  
    ModifiedDate datetime);  
  
UPDATE TOP (10) HumanResources.Employee  
SET VacationHours = VacationHours * 1.25,  
    ModifiedDate = GETDATE()  
OUTPUT inserted.BusinessEntityID,  
       deleted.VacationHours,  
       inserted.VacationHours,  
       inserted.VacationHours - deleted.VacationHours,  
       inserted.ModifiedDate  
INTO @MyTableVar;  
  
--Display the result set of the table variable.  
SELECT EmpID, OldVacationHours, NewVacationHours,   
    VacationHoursDifference, ModifiedDate  
FROM @MyTableVar;  
GO  
SELECT TOP (10) BusinessEntityID, VacationHours, ModifiedDate  
FROM HumanResources.Employee;  
GO  
  

E.E. Usando OUTPUT INTO com from_table_name em uma instrução UPDATEUsing OUTPUT INTO with from_table_name in an UPDATE statement

A exemplo a seguir atualiza a coluna ScrapReasonID na tabela WorkOrder para todas as ordens de serviço com uma ProductID e uma ScrapReasonID especificadas.The following example updates the ScrapReasonID column in the WorkOrder table for all work orders with a specified ProductID and ScrapReasonID. A cláusula OUTPUT INTO retorna valores da tabela que está sendo atualizada (WorkOrder) e também da tabela Product.The OUTPUT INTO clause returns values from the table being updated (WorkOrder) and also from the Product table. A tabela Product é usada na cláusula FROM para especificar as linhas a serem atualizadas.The Product table is used in the FROM clause to specify the rows to update. Como a tabela WorkOrder tem um gatilho AFTER UPDATE definido, é necessária a palavra-chave INTO.Because the WorkOrder table has an AFTER UPDATE trigger defined on it, the INTO keyword is required.

USE AdventureWorks2012;  
GO  
DECLARE @MyTestVar table (  
    OldScrapReasonID int NOT NULL,   
    NewScrapReasonID int NOT NULL,   
    WorkOrderID int NOT NULL,  
    ProductID int NOT NULL,  
    ProductName nvarchar(50)NOT NULL);  
  
UPDATE Production.WorkOrder  
SET ScrapReasonID = 4  
OUTPUT deleted.ScrapReasonID,  
       inserted.ScrapReasonID,   
       inserted.WorkOrderID,  
       inserted.ProductID,  
       p.Name  
    INTO @MyTestVar  
FROM Production.WorkOrder AS wo  
    INNER JOIN Production.Product AS p   
    ON wo.ProductID = p.ProductID   
    AND wo.ScrapReasonID= 16  
    AND p.ProductID = 733;  
  
SELECT OldScrapReasonID, NewScrapReasonID, WorkOrderID,   
    ProductID, ProductName   
FROM @MyTestVar;  
GO  
  

F.F. Usando OUTPUT INTO com from_table_name em uma instrução DELETEUsing OUTPUT INTO with from_table_name in a DELETE statement

O exemplo a seguir exclui linhas da tabela ProductProductPhoto com base em critérios de pesquisa definidos na cláusula FROM da instrução DELETE.The following example deletes rows in the ProductProductPhoto table based on search criteria defined in the FROM clause of DELETE statement. A cláusula OUTPUT retorna colunas da tabela que está sendo excluída (deleted.ProductID, deleted.ProductPhotoID) e colunas da tabela Product.The OUTPUT clause returns columns from the table being deleted (deleted.ProductID, deleted.ProductPhotoID) and columns from the Product table. Essa tabela é usada na cláusula FROM para especificar as linhas a serem excluídas.This table is used in the FROM clause to specify the rows to delete.

USE AdventureWorks2012;  
GO  
DECLARE @MyTableVar table (  
    ProductID int NOT NULL,   
    ProductName nvarchar(50)NOT NULL,  
    ProductModelID int NOT NULL,   
    PhotoID int NOT NULL);  
  
DELETE Production.ProductProductPhoto  
OUTPUT DELETED.ProductID,  
       p.Name,  
       p.ProductModelID,  
       DELETED.ProductPhotoID  
    INTO @MyTableVar  
FROM Production.ProductProductPhoto AS ph  
JOIN Production.Product as p   
    ON ph.ProductID = p.ProductID   
    WHERE p.ProductModelID BETWEEN 120 and 130;  
  
--Display the results of the table variable.  
SELECT ProductID, ProductName, ProductModelID, PhotoID   
FROM @MyTableVar  
ORDER BY ProductModelID;  
GO  
  

G.G. Usando OUTPUT INTO com um tipo de dados de objeto grandeUsing OUTPUT INTO with a large object data type

O exemplo a seguir atualiza um valor parcial em DocumentSummary e uma coluna nvarchar(max) na tabela Production.Document usando a cláusula .WRITE.The following example updates a partial value in DocumentSummary, an nvarchar(max) column in the Production.Document table, by using the .WRITE clause. A palavra components é substituída pela palavra features especificando a palavra de substituição, o local de início (deslocamento) da palavra a ser substituída nos dados existentes e o número de caracteres a serem substituídos (comprimento).The word components is replaced by the word features by specifying the replacement word, the beginning location (offset) of the word to be replaced in the existing data, and the number of characters to be replaced (length). O exemplo usa a cláusula OUTPUT para retornar as imagens de antes e depois da coluna DocumentSummary para a variável @MyTableVar``table.The example uses the OUTPUT clause to return the before and after images of the DocumentSummary column to the @MyTableVar``table variable. Observe que são retornadas as imagens completas de antes e depois da coluna DocumentSummary.Note that the full before and after images of the DocumentSummary column are returned.

USE AdventureWorks2012;  
GO  
DECLARE @MyTableVar table (  
    SummaryBefore nvarchar(max),  
    SummaryAfter nvarchar(max));  
  
UPDATE Production.Document  
SET DocumentSummary .WRITE (N'features',28,10)  
OUTPUT deleted.DocumentSummary,   
       inserted.DocumentSummary   
    INTO @MyTableVar  
WHERE Title = N'Front Reflector Bracket Installation';  
  
SELECT SummaryBefore, SummaryAfter   
FROM @MyTableVar;  
GO  
  

H.H. Usando OUTPUT em um gatilho INSTEAD OFUsing OUTPUT in an INSTEAD OF trigger

O exemplo a seguir usa a cláusula OUTPUT em um gatilho para retornar os resultados da operação do gatilho.The following example uses the OUTPUT clause in a trigger to return the results of the trigger operation. Primeiro, uma exibição é criada na tabela ScrapReason e, em seguida, um gatilho INSTEAD OF INSERT é definido na exibição, permitindo que apenas a coluna Name da tabela base seja modificada pelo usuário.First, a view is created on the ScrapReason table, and then an INSTEAD OF INSERT trigger is defined on the view that lets only the Name column of the base table to be modified by the user. Como a coluna ScrapReasonID é uma coluna IDENTITY na tabela base, o gatilho ignora o valor fornecido pelo usuário.Because the column ScrapReasonID is an IDENTITY column in the base table, the trigger ignores the user-supplied value. Isso permite ao Mecanismo de Banco de DadosDatabase Engine gerar o valor correto automaticamente.This allows the Mecanismo de Banco de DadosDatabase Engine to automatically generate the correct value. O valor fornecido pelo usuário para ModifiedDate também é ignorado, sendo definido como a data atual.Also, the value supplied by the user for ModifiedDate is ignored and is set to the current date. A cláusula OUTPUT retorna os valores inseridos de fato na tabela ScrapReason.The OUTPUT clause returns the values actually inserted into the ScrapReason table.

USE AdventureWorks2012;  
GO  
IF OBJECT_ID('dbo.vw_ScrapReason','V') IS NOT NULL  
    DROP VIEW dbo.vw_ScrapReason;  
GO  
CREATE VIEW dbo.vw_ScrapReason  
AS (SELECT ScrapReasonID, Name, ModifiedDate  
    FROM Production.ScrapReason);  
GO  
CREATE TRIGGER dbo.io_ScrapReason   
    ON dbo.vw_ScrapReason  
INSTEAD OF INSERT  
AS  
BEGIN  
--ScrapReasonID is not specified in the list of columns to be inserted   
--because it is an IDENTITY column.  
    INSERT INTO Production.ScrapReason (Name, ModifiedDate)  
        OUTPUT INSERTED.ScrapReasonID, INSERTED.Name,   
               INSERTED.ModifiedDate  
    SELECT Name, getdate()  
    FROM inserted;  
END  
GO  
INSERT vw_ScrapReason (ScrapReasonID, Name, ModifiedDate)  
VALUES (99, N'My scrap reason','20030404');  
GO  
  

Eis o conjunto de resultados gerado no dia 12 de abril de 2004 ('2004-04-12').Here is the result set generated on April 12, 2004 ('2004-04-12'). Observe que as colunas ScrapReasonIDActual e ModifiedDate refletem os valores gerados pela operação do gatilho, no lugar dos valores fornecidos na instrução INSERT.Notice that the ScrapReasonIDActual and ModifiedDate columns reflect the values generated by the trigger operation instead of the values provided in the INSERT statement.

ScrapReasonID  Name             ModifiedDate  
-------------  ---------------- -----------------------  
17             My scrap reason  2004-04-12 16:23:33.050

I.I. Usando OUTPUT INTO com colunas de identidade e colunas computadasUsing OUTPUT INTO with identity and computed columns

O exemplo a seguir cria a tabela EmployeeSales e, em seguida, insere várias linhas nela por meio de uma instrução INSERT com uma instrução SELECT, para recuperar dados das tabelas de origem.The following example creates the EmployeeSales table and then inserts several rows into it using an INSERT statement with a SELECT statement to retrieve data from source tables. A tabela EmployeeSales contém uma coluna de identidade (EmployeeID) e uma coluna computada (ProjectedSales).The EmployeeSales table contains an identity column (EmployeeID) and a computed column (ProjectedSales).

USE AdventureWorks2012 ;  
GO  
IF OBJECT_ID ('dbo.EmployeeSales', 'U') IS NOT NULL  
    DROP TABLE dbo.EmployeeSales;  
GO  
CREATE TABLE dbo.EmployeeSales  
( EmployeeID   int IDENTITY (1,5)NOT NULL,  
  LastName     nvarchar(20) NOT NULL,  
  FirstName    nvarchar(20) NOT NULL,  
  CurrentSales money NOT NULL,  
  ProjectedSales AS CurrentSales * 1.10   
);  
GO  
DECLARE @MyTableVar table(  
  EmployeeID   int NOT NULL,  
  LastName     nvarchar(20) NOT NULL,  
  FirstName    nvarchar(20) NOT NULL,  
  CurrentSales money NOT NULL,  
  ProjectedSales money NOT NULL  
  );  
  
INSERT INTO dbo.EmployeeSales (LastName, FirstName, CurrentSales)  
  OUTPUT INSERTED.LastName,   
         INSERTED.FirstName,   
         INSERTED.CurrentSales  
  INTO @MyTableVar  
    SELECT c.LastName, c.FirstName, sp.SalesYTD  
    FROM Sales.SalesPerson AS sp  
    INNER JOIN Person.Person AS c  
        ON sp.BusinessEntityID = c.BusinessEntityID  
    WHERE sp.BusinessEntityID LIKE '2%'  
    ORDER BY c.LastName, c.FirstName;  
  
SELECT EmployeeID, LastName, FirstName, CurrentSales, ProjectedSales  
FROM @MyTableVar;  
GO  
SELECT EmployeeID, LastName, FirstName, CurrentSales, ProjectedSales  
FROM dbo.EmployeeSales;  
GO  
  

J.J. Usando OUTPUT e OUTPUT INTO em uma única instruçãoUsing OUTPUT and OUTPUT INTO in a single statement

O exemplo a seguir exclui linhas da tabela ProductProductPhoto com base em critérios de pesquisa definidos na cláusula FROM da instrução DELETE.The following example deletes rows in the ProductProductPhoto table based on search criteria defined in the FROM clause of DELETE statement. A cláusula OUTPUT INTO retorna as colunas da tabela que está sendo excluída (deleted.ProductID, deleted.ProductPhotoID) e as colunas da tabela Product para a variável @MyTableVar``table.The OUTPUT INTO clause returns columns from the table being deleted (deleted.ProductID, deleted.ProductPhotoID) and columns from the Product table to the @MyTableVar``table variable. A tabela Product é usada na cláusula FROM para especificar as linhas a serem excluídas.The Product table is used in the FROM clause to specify the rows to delete. A cláusula OUTPUT retorna as colunas deleted.ProductID e deleted.ProductPhotoID e a data e a hora em que a linha foi excluída da tabela ProductProductPhoto ao aplicativo de chamada.The OUTPUT clause returns the deleted.ProductID, deleted.ProductPhotoID columns and the date and time the row was deleted from the ProductProductPhoto table to the calling application.

USE AdventureWorks2012;  
GO  
DECLARE @MyTableVar table (  
    ProductID int NOT NULL,   
    ProductName nvarchar(50)NOT NULL,  
    ProductModelID int NOT NULL,   
    PhotoID int NOT NULL);  
  
DELETE Production.ProductProductPhoto  
OUTPUT DELETED.ProductID,  
       p.Name,  
       p.ProductModelID,  
       DELETED.ProductPhotoID  
    INTO @MyTableVar  
OUTPUT DELETED.ProductID, DELETED.ProductPhotoID, GETDATE() AS DeletedDate   
FROM Production.ProductProductPhoto AS ph  
JOIN Production.Product as p   
    ON ph.ProductID = p.ProductID   
WHERE p.ProductID BETWEEN 800 and 810;  
  
--Display the results of the table variable.  
SELECT ProductID, ProductName, PhotoID, ProductModelID   
FROM @MyTableVar;  
GO  
  

K.K. Inserindo dados retornados de uma cláusula OUTPUTInserting data returned from an OUTPUT clause

O exemplo a seguir captura dados retornados da cláusula OUTPUT de uma instrução MERGE e insere esses dados em outra tabela.The following example captures data returned from the OUTPUT clause of a MERGE statement, and inserts that data into another table. A instrução MERGE atualiza a coluna Quantity da tabela ProductInventory diariamente, com base nos pedidos processados na tabela SalesOrderDetail.The MERGE statement updates the Quantity column of the ProductInventory table daily, based on orders that are processed in the SalesOrderDetail table. Ela também exclui linhas de produtos cujos inventários caem para 0 ou menos.It also deletes rows for products whose inventories drop to 0 or below. O exemplo captura as linhas excluídas e as insere em outra tabela, ZeroInventory, que rastreia produtos sem-estoque.The example captures the rows that are deleted and inserts them into another table, ZeroInventory, which tracks products with no inventory.

USE AdventureWorks2012;  
GO  
IF OBJECT_ID(N'Production.ZeroInventory', N'U') IS NOT NULL  
    DROP TABLE Production.ZeroInventory;  
GO  
--Create ZeroInventory table.  
CREATE TABLE Production.ZeroInventory (DeletedProductID int, RemovedOnDate DateTime);  
GO  
  
INSERT INTO Production.ZeroInventory (DeletedProductID, RemovedOnDate)  
SELECT ProductID, GETDATE()  
FROM  
(   MERGE Production.ProductInventory AS pi  
    USING (SELECT ProductID, SUM(OrderQty) FROM Sales.SalesOrderDetail AS sod  
           JOIN Sales.SalesOrderHeader AS soh  
           ON sod.SalesOrderID = soh.SalesOrderID  
           AND soh.OrderDate = '20070401'  
           GROUP BY ProductID) AS src (ProductID, OrderQty)  
    ON (pi.ProductID = src.ProductID)  
    WHEN MATCHED AND pi.Quantity - src.OrderQty <= 0  
        THEN DELETE  
    WHEN MATCHED  
        THEN UPDATE SET pi.Quantity = pi.Quantity - src.OrderQty  
    OUTPUT $action, deleted.ProductID) AS Changes (Action, ProductID)  
WHERE Action = 'DELETE';  
IF @@ROWCOUNT = 0  
PRINT 'Warning: No rows were inserted';  
GO  
SELECT DeletedProductID, RemovedOnDate FROM Production.ZeroInventory;  
  

Consulte TambémSee Also

DELETE (Transact-SQL) DELETE (Transact-SQL)
INSERT (Transact-SQL) INSERT (Transact-SQL)
UPDATE (Transact-SQL) UPDATE (Transact-SQL)
table (Transact-SQL) table (Transact-SQL)
CREATE TRIGGER (Transact-SQL) CREATE TRIGGER (Transact-SQL)
sp_configure (Transact-SQL)sp_configure (Transact-SQL)