DECLARE (Transact-SQL)DECLARE (Transact-SQL)

APLICA-SE A: simSQL Server simBanco de Dados SQL do Azure simSQL Data Warehouse do Azure simParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database yesAzure SQL Data Warehouse yesParallel Data Warehouse

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.Variables are declared in the body of a batch or procedure with the DECLARE statement and are assigned values by using either a SET or SELECT statement. As variáveis de cursor podem ser declaradas com essa instrução e usadas com outras instruções relacionadas ao cursor.Cursor variables can be declared with this statement and used with other cursor-related statements. 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.After declaration, all variables are initialized as NULL, unless a value is provided as part of the declaration.

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

SintaxeSyntax

-- 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 SQL Data Warehouse and Parallel Data Warehouse  
  
DECLARE   
{{ @local_variable [AS] data_type } [ =value [ COLLATE <collation_name> ] ] } [,...n]  
  

ArgumentosArguments

@local_variable@local_variable
É o nome de uma variável.Is the name of a variable. Os nomes de variável devem começar com uma arroba (@).Variable names must begin with an at (@) sign. Os nomes de variável local devem obedecer às regras de identificadores.Local variable names must comply with the rules for identifiers.

data_typedata_type
É qualquer tipo de tabela CLR (Common Language Runtime) definido pelo usuário e fornecido pelo sistema ou tipo de dados alias.Is any system-supplied, common language runtime (CLR) user-defined table type, or alias data type. Uma variável não pode ser de um tipo de dados text, ntext ou image.A variable cannot be of text, ntext, or image data type.

Para obter mais informações sobre tipos de dados do sistema, consulte Tipos de dados (Transact-SQL).For more information about system data types, see Data Types (Transact-SQL). Para obter mais informações sobre tipos de dados CLR definidos pelo usuário ou tipos de dados alias, consulte CREATE TYPE (Transact-SQL).For more information about CLR user-defined types or alias data types, see CREATE TYPE (Transact-SQL).

=value=value
Atribui um valor à variável embutida.Assigns a value to the variable in-line. 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.The value can be a constant or an expression, but it must either match the variable declaration type or be implicitly convertible to that type. Para obter mais informações, veja Expressões (Transact-SQL).For more information, see Expressions (Transact-SQL).

@cursor_variable_name@cursor_variable_name
É o nome de uma variável de cursor.Is the name of a cursor variable. Os nomes de variável de cursor devem começar com uma arroba (@) e devem ser compatíveis com as regras para identificadores.Cursor variable names must begin with an at (@) sign and conform to the rules for identifiers.

CURSORCURSOR
Especifica que a variável é uma variável de cursor local.Specifies that the variable is a local cursor variable.

@table_variable_name@table_variable_name
É o nome de uma variável do tipo table.Is the name of a variable of type table. Os nomes de variável devem começar com uma arroba (@) e devem ser compatíveis com as regras para identificadores.Variable names must begin with an at (@) sign and conform to the rules for identifiers.

<table_type_definition><table_type_definition>
Define o tipo de dados table.Defines the table data type. A declaração de tabela inclui definições de coluna, nomes, tipos de dados e restrições.The table declaration includes column definitions, names, data types, and constraints. Os únicos tipos de restrição permitidos são PRIMARY KEY, UNIQUE, NULL e CHECK.The only constraint types allowed are PRIMARY KEY, UNIQUE, NULL, and 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.An alias data type cannot be used as a column scalar data type if a rule or default definition is bound to the type.

<table_type_definiton> É um subconjunto de informações usado para definir uma tabela em CREATE TABLE.<table_type_definiton> Is a subset of information used to define a table in CREATE TABLE. Elementos e definições essenciais são incluídos aqui.Elements and essential definitions are included here. Para obter mais informações, consulte CREATE TABLE (Transact-SQL).For more information, see CREATE TABLE (Transact-SQL).

nn
É um espaço reservado que indica que várias variáveis podem ser especificadas e valores podem ser atribuídos.Is a placeholder indicating that multiple variables can be specified and assigned values. Ao declarar variáveis table, a variável table deve ser a única declarada na instrução DECLARE.When declaring table variables, the table variable must be the only variable being declared in the DECLARE statement.

column_namecolumn_name
É o nome da coluna na tabela.Is the name of the column in the table.

scalar_data_typescalar_data_type
Especifica que a coluna é um tipo de dados escalar.Specifies that the column is a scalar data type.

computed_column_expressioncomputed_column_expression
É uma expressão que define o valor de uma coluna computada.Is an expression defining the value of a computed column. Essa coluna é computada a partir de uma expressão que usa outras colunas na mesma tabela.It is computed from an expression using other columns in the same table. Por exemplo, uma coluna computada pode ter a definição cost AS price * qty. A expressão pode ser o nome de uma coluna não computada, uma constante, uma função interna, uma variável ou qualquer combinação dessas conectada por um ou mais operadores.For example, a computed column can have the definition cost AS price * qty. The expression can be a noncomputed column name, constant, built-in function, variable, or any combination of these connected by one or more operators. A expressão não pode ser uma subconsulta ou uma função definida pelo usuário.The expression cannot be a subquery or a user-defined function. A expressão não pode fazer referência a um tipo de dados CLR definido pelo usuário.The expression cannot reference a CLR user-defined type.

[ COLLATE collation_name][ COLLATE collation_name]
Especifica a ordenação da coluna.Specifies the collation for the column. 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.collation_name can be either a Windows collation name or an SQL collation name, and is applicable only for columns of the char, varchar, text, nchar, nvarchar, and ntext data types. 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.If not specified, the column is assigned either the collation of the user-defined data type (if the column is of a user-defined data type) or the collation of the current database.

Para obter mais informações sobre os nomes de ordenação do Windows e do SQL, veja COLLATE (Transact-SQL).For more information about the Windows and SQL collation names, see COLLATE (Transact-SQL).

DEFAULTDEFAULT
Especifica o valor fornecido para a coluna quando um valor não for fornecido explicitamente durante uma inserção.Specifies the value provided for the column when a value is not explicitly supplied during an insert. 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.DEFAULT definitions can be applied to any columns except those defined as timestamp or those with the IDENTITY property. As definições DEFAULT serão removidas quando a tabela for descartada.DEFAULT definitions are removed when the table is dropped. 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.Only a constant value, such as a character string; a system function, such as a SYSTEM_USER(); or NULL can be used as a default. Para manter a compatibilidade com versões anteriores do SQL ServerSQL Server, um nome de restrição pode ser atribuído a um DEFAULT.To maintain compatibility with earlier versions of SQL ServerSQL Server, a constraint name can be assigned to a DEFAULT.

constant_expressionconstant_expression
É uma constante, um NULL ou uma função de sistema usada como valor de coluna padrão.Is a constant, NULL, or a system function used as the default value for the column.

IDENTITYIDENTITY
Indica que a nova coluna é uma coluna de identidade.Indicates that the new column is an identity column. Quando uma nova linha é adicionada à tabela, o SQL ServerSQL Server fornece um valor incremental exclusivo para a coluna.When a new row is added to the table, SQL ServerSQL Server provides a unique incremental value for the column. 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.Identity columns are commonly used in conjunction with PRIMARY KEY constraints to serve as the unique row identifier for the table. A propriedade IDENTITY pode ser atribuída às colunas tinyint, smallint, int, decimal(p,0) ou numeric(p,0) .The IDENTITY property can be assigned to tinyint, smallint, int, decimal(p,0), or numeric(p,0) columns. Apenas uma coluna de identidade pode ser criada por tabela.Only one identity column can be created per table. Padrões associados e restrições DEFAULT não podem ser usados com uma coluna de identidade.Bound defaults and DEFAULT constraints cannot be used with an identity column. Você deve especificar a semente e o incremento, ou nenhum dos dois.You must specify both the seed and increment, or neither. Se nenhum for especificado, o padrão será (1,1).If neither is specified, the default is (1,1).

seedseed
É o valor usado para a primeira linha carregada na tabela.Is the value used for the very first row loaded into the table.

incrementincrement
É o valor incremental adicionado ao valor de identidade da linha anterior que foi carregada.Is the incremental value added to the identity value of the previous row that was loaded.

ROWGUIDCOLROWGUIDCOL
Indica que a nova coluna é uma coluna de identificador exclusivo global de linha.Indicates that the new column is a row global unique identifier column. Somente uma coluna uniqueidentifier por tabela pode ser designada como a coluna ROWGUIDCOL.Only one uniqueidentifier column per table can be designated as the ROWGUIDCOL column. A propriedade ROWGUIDCOL pode ser atribuída somente a uma coluna uniqueidentifier.The ROWGUIDCOL property can be assigned only to a uniqueidentifier column.

NULL | NOT NULLNULL | NOT NULL
Indica se será permitido um valor nulo na variável.Indicates if null is allowed in the variable. O padrão é NULO.The default is NULL.

PRIMARY KEYPRIMARY KEY
É uma restrição que impõe a integridade de entidade para uma coluna ou colunas especificadas por meio de um índice exclusivo.Is a constraint that enforces entity integrity for a given column or columns through a unique index. Somente uma restrição PRIMARY KEY pode ser criada por tabela.Only one PRIMARY KEY constraint can be created per table.

UNIQUEUNIQUE
É uma restrição que fornece a integridade de entidade para uma coluna ou colunas especificadas por meio de um índice exclusivo.Is a constraint that provides entity integrity for a given column or columns through a unique index. Uma tabela pode ter várias restrições UNIQUE.A table can have multiple UNIQUE constraints.

CHECKCHECK
É 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.Is a constraint that enforces domain integrity by limiting the possible values that can be entered into a column or columns.

logical_expressionlogical_expression
É uma expressão lógica que retorna TRUE ou FALSE.Is a logical expression that returns TRUE or FALSE.

RemarksRemarks

As variáveis geralmente são usadas em um lote ou procedimento como contadores para WHILE, LOOP ou para um bloco IF...ELSE.Variables are often used in a batch or procedure as counters for WHILE, LOOP, or for an IF...ELSE block.

As variáveis podem ser usadas somente em expressões, não no lugar de nomes de objeto ou palavras-chave.Variables can be used only in expressions, not in place of object names or keywords. Para construir instruções SQL dinâmicas, use EXECUTE.To construct dynamic SQL statements, use EXECUTE.

O escopo de uma variável local é o lote no qual ela é declarada.The scope of a local variable is the batch in which it is declared.

Uma variável de tabela não é necessariamente residente em memória.A table variable is not necessarily memory resident. Sob demanda de memória, as páginas que pertencem a uma variável de tabela podem ser enviadas para fora do tempdb.Under memory pressure, the pages belonging to a table variable can be pushed out to tempdb.

Uma variável de cursor que atualmente tem um cursor atribuído pode ser mencionada como uma fonte em uma:A cursor variable that currently has a cursor assigned to it can be referenced as a source in a:

  • Instrução CLOSE.CLOSE statement.

  • Instrução DEALLOCATE.DEALLOCATE statement.

  • Instrução FETCH.FETCH statement.

  • Instrução OPEN.OPEN statement.

  • Instrução DELETE ou UPDATE posicionada.Positioned DELETE or UPDATE statement.

  • Instrução de variável SET CURSOR (à direita).SET CURSOR variable statement (on the right side).

Em todas essas instruções, o SQL ServerSQL Server gera um erro se uma variável de cursor mencionada existir, mas não tiver no cursor alocado atualmente.In all of these statements, SQL ServerSQL Server raises an error if a referenced cursor variable exists but does not have a cursor currently allocated to it. Se uma variável de cursor mencionada não existir, o SQL ServerSQL Server gerará o mesmo erro ocorrido para uma variável não declarada de outro tipo.If a referenced cursor variable does not exist, SQL ServerSQL Server raises the same error raised for an undeclared variable of another type.

Uma variável de cursor:A cursor variable:

  • Pode ser o destino de um tipo de cursor ou de outra variável de cursor.Can be the target of either a cursor type or another cursor variable. Para obter mais informações, consulte SET @local_variable (Transact-SQL).For more information, see 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.Can be referenced as the target of an output cursor parameter in an EXECUTE statement if the cursor variable does not have a cursor currently assigned to it.

  • Deve ser considerada como um ponteiro para o cursor.Should be regarded as a pointer to the cursor.

ExemplosExamples

A.A. Usando DECLAREUsing 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.The following example uses a local variable named @find to retrieve contact information for all last names beginning with 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;  
  

Aqui está o conjunto de resultados.Here is the result set.

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.B. Usando DECLARE com duas variáveisUsing DECLARE with two variables

O exemplo a seguir recupera os nomes de representantes de vendas do Ciclos da Adventure WorksAdventure Works Cycles localizados no território de vendas norte-americano que venderam pelo menos US$ 2.000.000 durante o ano.The following example retrieves the names of Ciclos da Adventure WorksAdventure Works Cycles sales representatives who are located in the North American sales territory and have at least $2,000,000 in sales for the year.

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.C. Declarando uma variável de tabela de tiposDeclaring a variable of type table

O exemplo a seguir cria uma variável table que armazena os valores especificados na cláusula OUTPUT da instrução UPDATE.The following example creates a table variable that stores the values specified in the OUTPUT clause of the UPDATE statement. 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. Observe que os resultados da coluna INSERTED.ModifiedDate são diferentes dos valores da coluna ModifiedDate na tabela Employee.Note that the results in the INSERTED.ModifiedDate column differ from the values in the ModifiedDate column in the Employee table. Isso porque o gatilho AFTER UPDATE, que atualiza o valor de ModifiedDate com a data atual, está definido na tabela Employee.This is because the AFTER UPDATE trigger, which updates the value of ModifiedDate to the current date, is defined on the Employee table. Porém, as colunas retornadas de OUTPUT refletem os dados antes de os gatilhos serem disparados.However, the columns returned from OUTPUT reflect the data before triggers are fired. Para obter mais informações, confira Cláusula OUTPUT (Transact-SQL).For more information, see OUTPUT Clause (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.D. Declarando uma variável de tipo de tabela definido pelo usuárioDeclaring a variable of user-defined table type

O exemplo a seguir cria um parâmetro com valor de tabela ou uma variável de tabela chamada @LocationTVP.The following example creates a table-valued parameter or table variable called @LocationTVP. Isso requer um tipo de tabela definido pelo usuário correspondente chamado LocationTableType.This requires a corresponding user-defined table type called LocationTableType. Para obter mais informações sobre como criar um tipo de tabela definido pelo usuário, consulte CREATE TYPE (Transact-SQL).For more information about how to create a user-defined table type, see CREATE TYPE (Transact-SQL). Para obter mais informações sobre parâmetros com valor de tabela, consulte Usar parâmetros com valor de tabela (Mecanismo de Banco de Dados).For more information about table-valued parameters, see Use Table-Valued Parameters (Database Engine).

DECLARE @LocationTVP   
AS LocationTableType;  

Exemplos: Azure SQL Data WarehouseAzure SQL Data Warehouse e Parallel Data WarehouseParallel Data WarehouseExamples: Azure SQL Data WarehouseAzure SQL Data Warehouse and Parallel Data WarehouseParallel Data Warehouse

E.E. Usando DECLAREUsing 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.The following example uses a local variable named @find to retrieve contact information for all last names beginning with 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.F. Usando DECLARE com duas variáveisUsing DECLARE with two variables

O exemplo a seguir recupera e usa variáveis para especificar os nomes e sobrenomes de funcionários na tabela DimEmployee.The following example retrieves uses variables to specify the first and last names of employees in the DimEmployee table.

-- 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émSee Also

EXECUTE (Transact-SQL) EXECUTE (Transact-SQL)
Funções internas (Transact-SQL) Built-in Functions (Transact-SQL)
SELECT (Transact-SQL) SELECT (Transact-SQL)
table (Transact-SQL) table (Transact-SQL)
Comparar XML tipado com XML não tipadoCompare Typed XML to Untyped XML