DECLARE @local_variable (Transact-SQL)

Aplica-se a:yesSQL Server (todas as versões compatíveis) YesBanco de Dados SQL do Azure YesInstância Gerenciada de SQL do Azure yesAzure Synapse Analytics yesAnalytics Platform System (PDW)

As variáveis são declaradas no corpo de um lote ou procedimento com a instrução DECLARE e valores são atribuídos com uma instrução SET ou SELECT. As variáveis de cursor podem ser declaradas com essa instrução e usadas com outras instruções relacionadas ao cursor. Depois da declaração, todas as variáveis são inicializadas como NULL, a menos que um valor seja fornecido como parte da declaração.

Topic link iconConvenções de sintaxe do Transact-SQL

Sintaxe

-- Syntax for SQL Server and Azure SQL Database  
  
DECLARE   
{   
    { @local_variable [AS] data_type  [ = value ] }  
  | { @cursor_variable_name CURSOR }  
} [,...n]   
| { @table_variable_name [AS] <table_type_definition> }   
  
<table_type_definition> ::=   
     TABLE ( { <column_definition> | <table_constraint> } [ ,...n] )   
  
<column_definition> ::=   
     column_name { scalar_data_type | AS computed_column_expression }  
     [ COLLATE collation_name ]   
     [ [ DEFAULT constant_expression ] | IDENTITY [ (seed ,increment ) ] ]   
     [ ROWGUIDCOL ]   
     [ <column_constraint> ]   
  
<column_constraint> ::=   
     { [ NULL | NOT NULL ]   
     | [ PRIMARY KEY | UNIQUE ]   
     | CHECK ( logical_expression )   
     | WITH ( <index_option > )  
     }   
  
<table_constraint> ::=   
     { { PRIMARY KEY | UNIQUE } ( column_name [ ,...n] )   
     | CHECK ( search_condition )   
     }   
  
<index_option> ::=  
See CREATE TABLE for index option syntax.  
  
-- Syntax for Azure Synapse Analytics and Parallel Data Warehouse  
  
DECLARE   
{{ @local_variable [AS] data_type } [ =value [ COLLATE <collation_name> ] ] } [,...n]  
  

Observação

Para ver a sintaxe do Transact-SQL para o SQL Server 2014 e versões anteriores, confira a Documentação das versões anteriores.

Argumentos

@local_variable
É o nome de uma variável. Os nomes de variável devem começar com uma arroba (@). Os nomes de variável local devem obedecer às regras de identificadores.

data_type
É qualquer tipo de tabela CLR (Common Language Runtime) definido pelo usuário e fornecido pelo sistema ou tipo de dados alias. Uma variável não pode ser de um tipo de dados text, ntext ou image.

Para obter mais informações sobre tipos de dados do sistema, confira Tipos de dados (Transact-SQL). Para obter mais informações sobre tipos de dados CLR definidos pelo usuário ou tipos de dados alias, confira CREATE TYPE (Transact-SQL).

=value
Atribui um valor à variável embutida. O valor pode ser uma constante ou uma expressão, mas deve corresponder ao tipo de declaração de variável ou ser convertido implicitamente nesse tipo. Para obter mais informações, confira Expressões (Transact-SQL).

@cursor_variable_name
É o nome de uma variável de cursor. Os nomes de variável de cursor devem começar com uma arroba (@) e devem ser compatíveis com as regras para identificadores.

CURSOR
Especifica que a variável é uma variável de cursor local.

@table_variable_name
É o nome de uma variável do tipo table. Os nomes de variável devem começar com uma arroba (@) e devem estar em conformidade com as regras para identificadores.

<table_type_definition>
Define o tipo de dados table. A declaração de tabela inclui definições de coluna, nomes, tipos de dados e restrições. Os únicos tipos de restrição permitidos são PRIMARY KEY, UNIQUE, NULL e CHECK. Um tipo de dados alias não pode ser usado como um tipo de dados escalar de coluna se uma regra ou definição padrão for associada ao tipo.

<table_type_definiton> É um subconjunto de informações usado para definir uma tabela em CREATE TABLE. Elementos e definições essenciais são incluídos aqui. Para obter mais informações, veja CREATE TABLE (Transact-SQL).

n
É um espaço reservado que indica que várias variáveis podem ser especificadas e valores podem ser atribuídos. Ao declarar variáveis table, a variável table deve ser a única declarada na instrução DECLARE.

column_name
É o nome da coluna na tabela.

scalar_data_type
Especifica que a coluna é um tipo de dados escalar.

computed_column_expression
É uma expressão que define o valor de uma coluna computada. Essa coluna é computada a partir de uma expressão que usa outras colunas na mesma tabela. Por exemplo, uma coluna computada pode ter uma definição: cost AS price * qty. A expressão pode ser o nome de uma coluna não computada, constante, função, variável ou qualquer combinação dessas, conectada por um ou mais operadores. A expressão não pode ser uma subconsulta ou uma função definida pelo usuário. A expressão não pode fazer referência a um tipo de dados CLR definido pelo usuário.

[ COLLATE collation_name]
Especifica a ordenação da coluna. collation_name pode ser um nome de ordenação do Windows ou um nome de ordenação SQL e é aplicável somente a colunas dos tipos de dados char, varchar, text, nchar, nvarchar e ntext. Se não for especificado, à coluna será atribuída a ordenação do tipo de dados definido pelo usuário (se a coluna for de um tipo de dados definido pelo usuário) ou a ordenação do banco de dados atual.

Para obter mais informações sobre os nomes de ordenação do Windows e do SQL, consulte COLLATE (Transact-SQL).

DEFAULT
Especifica o valor fornecido para a coluna quando um valor não for fornecido explicitamente durante uma inserção. As definições de DEFAULT podem ser aplicadas a qualquer coluna, com exceção das definidas como timestamp ou das colunas com a propriedade IDENTITY. As definições DEFAULT serão removidas quando a tabela for descartada. Somente um valor constante, como uma cadeia de caracteres, uma função de sistema, como SYSTEM_USER() ou NULL pode ser usado como padrão. Para manter a compatibilidade com versões anteriores do SQL Server, um nome de restrição pode ser atribuído a um DEFAULT.

constant_expression
É uma constante, um NULL ou uma função de sistema usada como valor de coluna padrão.

IDENTITY
Indica que a nova coluna é uma coluna de identidade. Quando uma nova linha é adicionada à tabela, o SQL Server fornece um valor incremental exclusivo para a coluna. As colunas de identidade, em geral, são usadas juntamente com restrições PRIMARY KEY para servir de identificador exclusivo de linha para a tabela. A propriedade IDENTITY pode ser atribuída às colunas tinyint, smallint, int, decimal(p,0) ou numeric(p,0) . Apenas uma coluna de identidade pode ser criada por tabela. Padrões associados e restrições DEFAULT não podem ser usados com uma coluna de identidade. Você deve especificar a semente e o incremento, ou nenhum dos dois. Se nenhum for especificado, o padrão será (1,1).

seed
É o valor usado para a primeira linha carregada na tabela.

increment
É o valor incremental adicionado ao valor de identidade da linha anterior que foi carregada.

ROWGUIDCOL
Indica que a nova coluna é uma coluna de identificador exclusivo global de linha. Somente uma coluna uniqueidentifier por tabela pode ser designada como a coluna ROWGUIDCOL. A propriedade ROWGUIDCOL pode ser atribuída somente a uma coluna uniqueidentifier.

NULL | NOT NULL
Indica se será permitido um valor nulo na variável. O padrão é NULO.

PRIMARY KEY
É uma restrição que impõe a integridade de entidade para uma coluna ou colunas especificadas por meio de um índice exclusivo. Somente uma restrição PRIMARY KEY pode ser criada por tabela.

UNIQUE
É uma restrição que fornece a integridade de entidade para uma coluna ou colunas especificadas por meio de um índice exclusivo. Uma tabela pode ter várias restrições UNIQUE.

CHECK
É uma restrição que impõe a integridade de domínio limitando os possíveis valores que podem ser inseridos em uma ou mais colunas.

logical_expression
É uma expressão lógica que retorna TRUE ou FALSE.

Comentários

As variáveis geralmente são usadas em um lote ou procedimento como contadores para WHILE, LOOP ou para um bloco IF...ELSE.

As variáveis podem ser usadas somente em expressões, não no lugar de nomes de objeto ou palavras-chave. Para construir instruções SQL dinâmicas, use EXECUTE.

O escopo de uma variável local é o lote no qual ela é declarada.

Uma variável de tabela não é necessariamente residente em memória. Sob demanda de memória, as páginas que pertencem a uma variável de tabela podem ser enviadas para fora do tempdb.

Uma variável de cursor que atualmente tem um cursor atribuído pode ser mencionada como uma fonte em uma:

  • Instrução CLOSE.

  • Instrução DEALLOCATE.

  • Instrução FETCH.

  • Instrução OPEN.

  • Instrução DELETE ou UPDATE posicionada.

  • Instrução de variável SET CURSOR (à direita).

Em todas essas instruções, o SQL Server gera um erro se uma variável de cursor mencionada existir, mas não tiver no cursor alocado atualmente. Se uma variável de cursor mencionada não existir, o SQL Server gerará o mesmo erro ocorrido para uma variável não declarada de outro tipo.

Uma variável de cursor:

  • Pode ser o destino de um tipo de cursor ou de outra variável de cursor. Para obter mais informações, consulte SET @local_variable (Transact-SQL).

  • Pode ser mencionada como o destino de um parâmetro de cursor de saída em uma instrução EXECUTE se a variável não tiver um cursor atribuído no momento.

  • Deve ser considerada como um ponteiro para o cursor.

Exemplos

a. Usando DECLARE

O exemplo a seguir usa uma variável local chamada @find para recuperar informações de contato para todos os sobrenomes que começam com Man.

USE AdventureWorks2012;  
GO  
DECLARE @find VARCHAR(30);   
/* Also allowed:   
DECLARE @find VARCHAR(30) = 'Man%';   
*/  
SET @find = 'Man%';   
SELECT p.LastName, p.FirstName, ph.PhoneNumber  
FROM Person.Person AS p   
JOIN Person.PersonPhone AS ph ON p.BusinessEntityID = ph.BusinessEntityID  
WHERE LastName LIKE @find;  

Este é o conjunto de resultados.

LastName            FirstName               Phone
------------------- ----------------------- -------------------------
Manchepalli         Ajay                    1 (11) 500 555-0174
Manek               Parul                   1 (11) 500 555-0146
Manzanares          Tomas                   1 (11) 500 555-0178
 
(3 row(s) affected)

B. Usando DECLARE com duas variáveis

O exemplo a seguir recupera os nomes de representantes de vendas do Ciclos da Adventure Works localizados no território de vendas norte-americano que venderam pelo menos US$ 2.000.000 durante o ano.

USE AdventureWorks2012;  
GO  
SET NOCOUNT ON;  
GO  
DECLARE @Group nvarchar(50), @Sales MONEY;  
SET @Group = N'North America';  
SET @Sales = 2000000;  
SET NOCOUNT OFF;  
SELECT FirstName, LastName, SalesYTD  
FROM Sales.vSalesPerson  
WHERE TerritoryGroup = @Group and SalesYTD >= @Sales;  

C. Declarando uma variável de tabela de tipos

O exemplo a seguir cria uma variável table que armazena os valores especificados na cláusula OUTPUT da instrução UPDATE. Seguem duas instruções SELECT que retornam os valores em @MyTableVar e os resultados da operação de atualização na tabela Employee. Observe que os resultados da coluna INSERTED.ModifiedDate são diferentes dos valores da coluna ModifiedDate na tabela Employee. Isso porque o gatilho AFTER UPDATE, que atualiza o valor de ModifiedDate com a data atual, está definido na tabela Employee. Porém, as colunas retornadas de OUTPUT refletem os dados antes de os gatilhos serem disparados. Para obter mais informações, confira Cláusula OUTPUT (Transact-SQL).

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   
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.  
--Note that ModifiedDate reflects the value generated by an  
--AFTER UPDATE trigger.  
SELECT TOP (10) BusinessEntityID, VacationHours, ModifiedDate  
FROM HumanResources.Employee;  
GO  

D. Declarando uma variável de tipo de tabela definido pelo usuário

O exemplo a seguir cria um parâmetro com valor de tabela ou uma variável de tabela chamada @LocationTVP. Isso requer um tipo de tabela definido pelo usuário correspondente chamado LocationTableType. Para obter mais informações sobre como criar um tipo de tabela definido pelo usuário, confira CREATE TYPE (Transact-SQL). Para obter mais informações sobre parâmetros com valor de tabela, confira Usar parâmetros com valor de tabela (Mecanismo de Banco de Dados).

DECLARE @LocationTVP   
AS LocationTableType;  

Exemplos: Azure Synapse Analytics e PDW (Analytics Platform System)

E. Usando DECLARE

O exemplo a seguir usa uma variável local chamada @find para recuperar informações de contato para todos os sobrenomes que começam com Walt.

-- Uses AdventureWorks  
  
DECLARE @find VARCHAR(30);  
/* Also allowed:   
DECLARE @find VARCHAR(30) = 'Man%';  
*/  
SET @find = 'Walt%';  
  
SELECT LastName, FirstName, Phone  
FROM DimEmployee   
WHERE LastName LIKE @find;  

F. Usando DECLARE com duas variáveis

O exemplo a seguir recupera e usa variáveis para especificar os nomes e sobrenomes de funcionários na tabela DimEmployee.

-- Uses AdventureWorks  
  
DECLARE @lastName VARCHAR(30), @firstName VARCHAR(30);  
  
SET @lastName = 'Walt%';  
SET @firstName = 'Bryan';  
  
SELECT LastName, FirstName, Phone  
FROM DimEmployee   
WHERE LastName LIKE @lastName AND FirstName LIKE @firstName;  

Consulte Também

EXECUTE (Transact-SQL)
Funções internas (Transact-SQL)
SELECT (Transact-SQL)
tabela (Transact-SQL)
Comparar XML tipado com XML não tipado