DECLARAR @local_variable (Transact-SQL)

Aplica-se a:SQL Server Base de Dados SQL do Azure Instância Gerida do Azure SQL Azure Synapse Analytics Sistema de Plataforma de Análise (PDW)Ponto de Extremidade de Análise SQL no Microsoft Fabric Armazém no Microsoft Fabric Base de Dados SQL no Microsoft Fabric

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

Transact-SQL convenções de sintaxe

Syntax

A sintaxe a seguir é para o SQL Server e o Banco de Dados SQL do Azure:

DECLARE
{
  { @local_variable [AS] data_type [ = value ] }
  | { @cursor_variable_name CURSOR }
| { @table_variable_name [AS] <table_type_definition> }
} [ , ...n ]

<table_type_definition> ::=
    TABLE ( { <column_definition> | <table_constraint> | <table_index> } } [ , ...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_index> ]

<column_constraint> ::=
{
    [ NULL | NOT NULL ]
    { PRIMARY KEY | UNIQUE }
      [ CLUSTERED | NONCLUSTERED ]
      [ WITH FILLFACTOR = fillfactor
        | WITH ( < index_option > [ , ...n ] )
      [ ON { filegroup | "default" } ]
  | [ CHECK ( logical_expression ) ] [ , ...n ]
}

<column_index> ::=
    INDEX index_name [ CLUSTERED | NONCLUSTERED ]
    [ WITH ( <index_option> [ , ... n ] ) ]
    [ ON { partition_scheme_name (column_name )
         | filegroup_name
         | default
         }
    ]
    [ FILESTREAM_ON { filestream_filegroup_name | partition_scheme_name | "NULL" } ]

<table_constraint> ::=
{
    { PRIMARY KEY | UNIQUE }
      [ CLUSTERED | NONCLUSTERED ]
      ( column_name [ ASC | DESC ] [ , ...n ]
        [ WITH FILLFACTOR = fillfactor
        | WITH ( <index_option> [ , ...n ] )
  | [ CHECK ( logical_expression ) ] [ , ...n ]
}

<table_index> ::=
{
    {
      INDEX index_name  [ UNIQUE ] [ CLUSTERED | NONCLUSTERED ]
         (column_name [ ASC | DESC ] [ , ... n ] )
    | INDEX index_name CLUSTERED COLUMNSTORE
    | INDEX index_name [ NONCLUSTERED ] COLUMNSTORE ( column_name [ , ... n ] )
    }
    [ WITH ( <index_option> [ , ... n ] ) ]
    [ ON { partition_scheme_name ( column_name )
         | filegroup_name
         | default
         }
    ]
    [ FILESTREAM_ON { filestream_filegroup_name | partition_scheme_name | "NULL" } ]
}

<index_option> ::=
{
  PAD_INDEX = { ON | OFF }
  | FILLFACTOR = fillfactor
  | IGNORE_DUP_KEY = { ON | OFF }
  | STATISTICS_NORECOMPUTE = { ON | OFF }
  | STATISTICS_INCREMENTAL = { ON | OFF }
  | ALLOW_ROW_LOCKS = { ON | OFF }
  | ALLOW_PAGE_LOCKS = { ON | OFF }
  | OPTIMIZE_FOR_SEQUENTIAL_KEY = { ON | OFF }
  | COMPRESSION_DELAY = { 0 | delay [ Minutes ] }
  | DATA_COMPRESSION = { NONE | ROW | PAGE | COLUMNSTORE | COLUMNSTORE_ARCHIVE }
       [ ON PARTITIONS ( { partition_number_expression | <range> }
       [ , ...n ] ) ]
  | XML_COMPRESSION = { ON | OFF }
      [ ON PARTITIONS ( { <partition_number_expression> | <range> }
      [ , ...n ] ) ] ]
}

A sintaxe a seguir é para o Azure Synapse Analytics e o Parallel Data Warehouse e o Microsoft Fabric:

DECLARE
{ { @local_variable [AS] data_type } [ = value [ COLLATE <collation_name> ] ] } [ , ...n ]

Arguments

@ local_variable

O nome de uma variável. Os nomes das variáveis devem começar com um sinal at (@). Os nomes das variáveis locais devem estar em conformidade com as regras para identificadores.

data_type

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

Para obter mais informações sobre tipos de dados do sistema, consulte Tipos de dados. Para obter mais informações sobre tipos de dados de alias ou tipos de dados de alias definidos pelo usuário CLR, consulte CREATE TYPE.
= valor

Atribui um valor à variável in-line. O valor pode ser uma constante ou uma expressão, mas deve corresponder ao tipo de declaração variável ou ser implicitamente conversível para esse tipo. Para obter mais informações, consulte Expressões.

@ cursor_variable_name

O nome de uma variável de cursor. Os nomes das variáveis do cursor devem começar com um sinal at (@) e estar em conformidade 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 tabela. Os nomes das variáveis devem começar com um sinal at (@) e estar em conformidade com as regras para identificadores.
<table_type_definition>

Define o tipo de dados da tabela . 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, NULLe CHECK. Um tipo de dados de alias não pode ser usado como um tipo de dados escalar de coluna se uma regra ou definição padrão estiver vinculada ao tipo.

<table_type_definition>

Um subconjunto de informações usado para definir uma tabela em CREATE TABLE. Elementos e definições essenciais estão incluídos aqui. Para obter mais informações, consulte CREATE TABLE.

n

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

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 calculada. É calculado a partir de uma expressão usando outras colunas na mesma tabela. Por exemplo, uma coluna computada pode ter a definição cost AS price * qty. A expressão pode ser um nome de coluna não computado, constante, função interna, variável ou qualquer combinação dessas opções conectadas 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 CLR definido pelo usuário.

[ COLATE collation_name ]

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

Para obter mais informações sobre os nomes de agrupamento Windows e SQL, consulte COLLATE.

DEFAULT

Especifica o valor fornecido para a coluna quando um valor não é fornecido explicitamente durante uma inserção. DEFAULT As definições podem ser aplicadas a qualquer coluna, exceto colunas definidas como carimbo de data/hora ou com a IDENTITY propriedade. DEFAULT As definições são removidas quando a tabela é descartada. Apenas um valor constante, como uma cadeia de caracteres; uma função do sistema, como um 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 DEFAULTarquivo .

constant_expression

Uma constante, NULL, ou uma função do sistema usada como o valor padrão para a coluna.

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 são comumente usadas com PRIMARY KEY restrições para servir como identificador de linha exclusivo para a tabela. A IDENTITY propriedade pode ser atribuída a colunas tinyint, smallint, int, decimal(p,0) ou numérica(p,0 ). Apenas uma coluna de identidade pode ser criada por tabela. Os padrões e DEFAULT restrições vinculados não podem ser usados com uma coluna de identidade. Você deve especificar a semente e o incremento, ou nenhum. Se nenhum dos dois 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 global exclusivo de linha. Apenas uma coluna uniqueidentifier por tabela pode ser designada como ROWGUIDCOL coluna. A ROWGUIDCOL propriedade só pode ser atribuída a uma coluna uniqueidentifier .

NULO | NÃO NULO

Indica se null é permitido na variável. A predefinição é NULL.

CHAVE PRIMÁRIA

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

UNIQUE

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

AGRUPADOS | NÃO AGRUPADO

Indique que um índice clusterizado ou não clusterizado é criado para a PRIMARY KEY restrição ou UNIQUE . PRIMARY KEY uso de CLUSTEREDrestrições e UNIQUE uso de NONCLUSTEREDrestrições .

CLUSTERED pode ser especificado para apenas uma restrição. Se CLUSTERED for especificado para uma UNIQUE restrição e uma PRIMARY KEY restrição também for especificada, os PRIMARY KEY usos NONCLUSTERED.

CHECK

Uma restrição que impõe a integridade do domínio limitando os valores possíveis que podem ser inseridos em uma coluna ou colunas.

logical_expression

Uma expressão lógica que retorna TRUE ou FALSE.

<index_option>

Especifica uma ou mais opções de índice. Os índices não podem ser criados explicitamente em variáveis de tabela e nenhuma estatística é mantida em variáveis de tabela. O SQL Server 2014 (12.x) introduziu sintaxe que permite criar determinados tipos de índice em linha com a definição de tabela. Usando essa sintaxe, você pode criar índices em variáveis de tabela como parte da definição de tabela. Em alguns casos, o desempenho pode melhorar usando tabelas temporárias, que fornecem suporte total ao índice e estatísticas.

Para obter uma descrição completa dessas opções, consulte CREATE TABLE.

Variáveis de tabela e estimativas de linha

As variáveis de tabela não têm estatísticas de distribuição. Em muitos casos, o otimizador cria um plano de consulta com base na suposição de que a variável de tabela tem zero linhas ou uma linha. Para obter mais informações, revise o tipo de dados da tabela - Limitações e restrições.

Por esse motivo, você deve ser cauteloso ao usar uma variável de tabela se você espera um número maior de linhas (maior que 100). Considere as seguintes alternativas:

As tabelas temp podem ser uma solução melhor do que as variáveis de tabela quando é possível que a contagem de linhas seja maior (maior que 100).
Para consultas que unem a variável de tabela com outras tabelas, use a RECOMPILE dica, que faz com que o otimizador use a cardinalidade correta para a variável de tabela.
No Banco de Dados SQL do Azure e a partir do SQL Server 2019 (15.x), o recurso de compilação adiada da variável de tabela propaga estimativas de cardinalidade baseadas em contagens de linhas de variáveis de tabela reais, fornecendo uma contagem de linhas mais precisa para otimizar o plano de execução. Para obter mais informações, consulte Processamento inteligente de consultas em bancos de dados SQL.

Remarks

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

As variáveis podem ser usadas apenas em expressões, não no lugar de nomes de objetos 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 de memória. Sob pressão de memória, as páginas pertencentes a uma variável de tabela podem ser empurradas para tempdb.

Você pode definir um índice embutido em uma variável de tabela.

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

CLOSE Declaração
DEALLOCATE Declaração
FETCH Declaração
OPEN Declaração
Posicionado DELETE ou UPDATE declaração
SET CURSOR instrução variável (no lado direito)

Em todas essas instruções, o SQL Server gera um erro se uma variável de cursor referenciada existir, mas não tiver um cursor atualmente alocado a ela. Se uma variável de cursor referenciada não existir, o SQL Server gerará o mesmo erro gerado 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.
Pode ser referenciado como o destino de um parâmetro de cursor de saída em uma EXECUTE instrução se a variável de cursor não tiver um cursor atualmente atribuído a ela.
Deve ser considerado como um ponteiro para o cursor.

Examples

Os exemplos de código neste artigo usam o AdventureWorks2025 banco de dados ou AdventureWorksDW2025 exemplo, que você pode baixar da home page de Exemplos e Projetos da Comunidade do Microsoft SQL Server .

A. Usar DECLARE

O exemplo a seguir usa uma variável local chamada @find para recuperar informações de contato para todos os nomes de família começando com Man.

USE AdventureWorks2022;
GO

DECLARE @find AS VARCHAR (30);
/* Also allowed:
DECLARE @find VARCHAR(30) = 'Man%';
*/

SET @find = 'Man%';

SELECT p.LastName,
       p.FirstName,
       ph.PhoneNumber
FROM Person.Person AS p
     INNER JOIN Person.PersonPhone AS ph
         ON p.BusinessEntityID = ph.BusinessEntityID
WHERE LastName LIKE @find;

Aqui está 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

B. Use DECLARE com duas variáveis

O exemplo a seguir recupera os nomes dos representantes de vendas da Adventure Works Cycles que estão localizados no território de vendas da América do Norte e têm pelo menos US$ 2.000.000 em vendas para o ano.

USE AdventureWorks2022;
GO

SET NOCOUNT ON;
GO

DECLARE @Group AS NVARCHAR (50), @Sales AS 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. Declarar uma variável do tipo tabela

O exemplo a seguir cria uma table variável que armazena OUTPUT os valores especificados na cláusula da UPDATE instrução. Seguem-se duas SELECT instruções que retornam os valores e @MyTableVar os resultados da operação de atualização na Employee tabela. Os resultados na INSERTED.ModifiedDate coluna diferem dos valores na ModifiedDate coluna na Employee tabela. Isso ocorre porque o AFTER UPDATE gatilho, que atualiza o valor de ModifiedDate para a data atual, é definido na Employee tabela. No entanto, as colunas retornadas de OUTPUT refletem os dados antes que os gatilhos sejam acionados. Para obter mais informações, consulte Cláusula OUTPUT.

USE AdventureWorks2022;
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. Declarar uma variável do tipo tabela, com índices embutidos

O exemplo a seguir cria uma table variável com um índice embutido clusterizado e dois índices embutidos não clusterizados.

DECLARE @MyTableVar TABLE (
    EmpID INT NOT NULL,
    PRIMARY KEY CLUSTERED (EmpID),
    UNIQUE NONCLUSTERED (EmpID),
    INDEX CustomNonClusteredIndex NONCLUSTERED (EmpID));
GO

A consulta a seguir retorna informações sobre os índices criados na consulta anterior.

SELECT * FROM tempdb.sys.indexes
WHERE object_id < 0;
GO

E. Declarar uma variável do 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. Esta etapa requer um tipo de tabela correspondente definido pelo usuário chamado LocationTableType.

Para obter mais informações sobre como criar um tipo de tabela definido pelo usuário, consulte CREATE TYPE. 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).

DECLARE @LocationTVP AS LocationTableType;

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

F. Usar DECLARE

O exemplo a seguir usa uma variável local chamada @find para recuperar informações de contato para todos os nomes de família começando com Walt.

-- Uses AdventureWorks
DECLARE @find AS VARCHAR (30);
/* Also allowed:
DECLARE @find VARCHAR(30) = 'Man%';
*/

SET @find = 'Walt%';

SELECT LastName,
       FirstName,
       Phone
FROM DimEmployee
WHERE LastName LIKE @find;

G. Use DECLARE com duas variáveis

O exemplo a seguir recupera usa variáveis para especificar o nome e a família dos funcionários na DimEmployee tabela.

DECLARE @lastName AS VARCHAR (30),
    @firstName AS VARCHAR (30);

SET @lastName = 'Walt%';
SET @firstName = 'Bryan';

SELECT LastName,
       FirstName,
       Phone
FROM DimEmployee
WHERE LastName LIKE @lastName
      AND FirstName LIKE @firstName;

Comentários

Esta página foi útil?

Last updated on 2025-11-18