DECLARE @local_variable (Transact-SQL)

Область применения: SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure конечной точке аналитики платформы Аналитики Azure Synapse Analytics (PDW) в Microsoft Fabric Хранилище в базе данных Microsoft Fabric SQL в Microsoft Fabric

Переменные объявляются в теле пакета или процедуры при помощи инструкции DECLARE, а значения им присваиваются при помощи инструкций SET или SELECT. При помощи этой инструкции можно объявлять переменные курсоров для использования в других инструкциях. После декларации все переменные инициализируются значением NULL, если иное значение не предоставляется как часть декларации.

Соглашения о синтаксисе Transact-SQL

Синтаксис

Следующий синтаксис предназначен для SQL Server и Базы данных SQL Azure:

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> | <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 ] ) ] ]
}

Следующий синтаксис предназначен для Azure Synapse Analytics и Parallel Data Warehouse и Microsoft Fabric:

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

Аргументы

@local_variable

Имя переменной. Имена переменных должны начинаться с символа @. Имена локальных переменных должны соответствовать правилам для идентификаторов.

data_type
Любой системный тип данных, определяемый пользователем табличный тип среды CLR или псевдоним типа данных. Переменная не может иметь тип данных text, ntext или image.

Дополнительные сведения о типах данных в системе см. в разделе Типы данных (Transact-SQL). Дополнительные сведения об определяемых пользователем типах данных CLR или о псевдонимах типов данных см. в разделе CREATE TYPE(Transact-SQL).

= значение
Подставляет значение переменной. Значение может быть константой или выражением, но должно совпадать с объявленным типом переменной или явно преобразовываться в этот тип. Дополнительные сведения см. в статье Выражения (Transact-SQL).

@cursor_variable_name

Имя переменной курсора. Имена переменных курсора должны начинаться с символа @ и должны соответствовать правилам именования идентификаторов.

CURSOR
Указывает, что переменная является локальной переменной курсора.

@table_variable_name
Имя переменной типа table. Имена переменных должны начинаться с символа @ и соответствовать правилам именования идентификаторов.

<table_type_definition>
Определяет тип данных table. Декларация таблицы включает определения столбцов, имен, типов данных и ограничений. Допустимы только ограничения PRIMARY KEY, UNIQUE, NULL и CHECK. Псевдоним типа данных не может использоваться как скалярный тип данных столбца, если к этому столбцу привязано правило или значение по умолчанию.

<table_type_definition>

Аргумент представляет собой подмножество данных, используемых для определения таблицы в инструкции CREATE TABLE. Сюда включены элементы и наиболее существенные определения. Дополнительные сведения см. в статье CREATE TABLE (Transact-SQL).

n
Заполнитель, указывающий на то, что могут быть заданы несколько переменных и им могут быть присвоены значения. При объявлении переменных типа table в инструкции DECLARE единственной объявляемой переменной должна быть переменная типа table.

column_name

Имя столбца в таблице.

scalar_data_type
Указывает, что столбец имеет скалярный тип данных.

computed_column_expression
Выражение, определяющее значение вычисляемого столбца. Значение вычисляется из выражения при помощи других столбцов той же таблицы. Например, вычисляемый столбец может иметь определение cost AS price * qty. Выражение может быть именем невычисляемого столбца, константой, встроенной функцией, переменной или любым их сочетанием, созданным с помощью одного или нескольких операторов. Выражение не может быть вложенным запросом или определяемой пользователем функцией. Выражение не может ссылаться на определяемый пользователем тип данных CLR.

[ COLLATE collation_name ]

Задает параметры сортировки для столбца. collation_name может быть либо именем сортировки Windows, либо именем сортировки SQL, и применимо только для столбцов char, varchar, text, nchar, nvarchar и ntext данных. Если этот аргумент не указан, столбцу назначаются либо параметры сортировки определяемого пользователем типа данных (если столбец принадлежит к определяемому пользователем типу данных), либо параметры сортировки текущей базы данных.

Дополнительные сведения об именах параметров сортировки Windows и SQL: COLLATE (Transact-SQL).

ПО УМОЛЧАНИЮ

Указывает значение, присваиваемое столбцу в случае отсутствия явно заданного значения при вставке. Определения DEFAULT могут применяться к любым столбцам, кроме имеющих тип timestamp или обладающих свойством IDENTITY. Определения DEFAULT удаляются, когда таблица удаляется из памяти. По умолчанию могут использоваться только константные значения, например символьные строки, системные функции, например SYSTEM_USER(), или NULL. Для обеспечения совместимости с более ранними версиями SQL Server можно назначить имя ограничения default.

constant_expression
Константа, NULL или системная функция, используемые в качестве значения по умолчанию для столбца.

IDENTITY

Указывает, что новый столбец является столбцом идентификаторов. При добавлении новой строки в таблицу SQL Server предоставляет уникальное добавочное значение для столбца. Столбцы идентификаторов обычно используются с ограничением PRIMARY KEY для поддержания уникальности идентификаторов строк в таблице. Свойство IDENTITY может назначаться для столбцов типа tinyint, smallint, int, decimal(p,0) или numeric(p,0). Для каждой таблицы можно создать только один столбец идентификаторов. Ограниченные значения по умолчанию и ограничения DEFAULT не могут использоваться в столбце идентификаторов. Необходимо указывать либо оба значения seed и increment, либо ни тот, ни другой. Если ничего не указано, применяется значение по умолчанию (1,1).

seed
Значение, используемое для первой строки, загружаемой в таблицу.

increment
Значение, добавляемое к значению идентификатора предыдущей загруженной строки.

ROWGUIDCOL

Указывает, что новый столбец является столбцом глобального уникального идентификатора строки. Только один столбец типа uniqueidentifier в таблице может быть назначен в качестве столбца ROWGUIDCOL. Свойство ROWGUIDCOL может быть присвоено только столбцу типа uniqueidentifier.

NULL | NOT NULL

Указывает, является ли значение null допустимым в переменной. По умолчанию имеет значение NULL.

ПЕРВИЧНЫЙ КЛЮЧ

Ограничение, которое с помощью уникального индекса требует целостности сущностей для данного столбца или столбцов. Можно создать только одно ограничение PRIMARY KEY для таблицы.

UNIQUE

Ограничение, которое с помощью уникального индекса обеспечивает целостность сущностей для данного столбца или столбцов. В таблице может быть несколько ограничений UNIQUE.

CLUSTERED | NONCLUSTERED

Указывает, что для ограничения PRIMARY KEY или UNIQUE создается кластеризованный или некластеризованный индекс. Ограничения PRIMARY KEY используют параметр CLUSTERED, а ограничения UNIQUE используют параметр NONCLUSTERED.

Параметр CLUSTERED может быть указан только для одного ограничения. Если параметр CLUSTERED указан для ограничения UNIQUE и указано ограничение PRIMARY KEY, то PRIMARY KEY использует NONCLUSTERED.

ПРОВЕРКА

Ограничение, обеспечивающее целостность домена путем ограничения возможных значений, которые могут быть введены в столбец или столбцы.

logical_expression
Логическое выражение, возвращающее значения TRUE или FALSE.

<index_option>

Указывает один или более параметров индекса. Для переменных table нельзя явно создавать индексы, при этом статистика для переменных table не сохраняется. Начиная с SQL Server 2014 (12.x) реализован новый синтаксис, который позволяет создавать определенные типы индекса прямо в коде определения таблицы. С помощью этого нового синтаксиса можно создавать индексы в переменной table как часть определения таблицы. В некоторых случаях можно добиться повышения производительности за счет использования временных таблиц, которые позволяют работать с индексами и статистикой.

Полное описание этих параметров см. в разделе CREATE TABLE.

Табличные переменные и расчетное количество строк

Для переменных Table не предусмотрена статистика распределения. Во многих случаях оптимизатор строит план запроса на предположении, что у табличной переменной нет строк или есть одна строка. Дополнительные сведения см. в описании типа данных таблицы — ограничения.

По этой причине следует проявлять осторожность относительно использования табличной переменной, если ожидается большое число строк (больше 100). Рассмотрите один из следующих вариантов:

• Временные таблицы могут быть более эффективным решением, чем табличные переменные, если это число строк может быть большим (больше 100).
• Для запросов, которые объединяют табличную переменную с другими таблицами, используйте указание RECOMPILE, чтобы оптимизатор использовал правильную кратность для табличной переменной.
• В Базе данных SQL Azure, начиная с SQL Server 2019 (15.x) функция отложенной компиляции в табличной переменной будет распространять оценки кратности в зависимости от фактического количества строк табличных переменных, предоставляя уточненное число строк для оптимизации плана выполнения. Дополнительные сведения см. в статье Интеллектуальная обработка запросов в базах данных SQL.

Замечания

Переменные часто используются в пакете или процедуре в качестве счетчиков для циклов WHILE, LOOP или в блоке IF…ELSE.

Переменные могут использоваться только в выражениях, но не вместо имен объектов или ключевых слов. Для построения динамических инструкций SQL используйте EXECUTE.

Областью локальной переменной является пакет, в котором она объявлена.

Табличная переменная необязательно является резидентной. В случае нехватки памяти страницы, относящиеся к табличной переменной, можно перенести в базу данных tempdb.

Встроенный индекс можно определить в табличной переменной.

На переменную курсора, которая в настоящее время содержит назначенный ей курсор, можно ссылаться в качестве источника из:

• Инструкция CLOSE
• DEALLOCATE, инструкция
• FETCH, инструкция
• OPEN, инструкция
• позиционированных инструкций DELETE или UPDATE;
• инструкции SET CURSOR с использованием переменных (в правой части).

Во всех этих инструкциях SQL Server формирует ошибку, если переменная курсора, на которую они ссылаются, существует, но не содержит курсора, назначенного ей в настоящее время. Если переменной курсора, на которую производится ссылка, не существует, сервер SQL Server формирует ту же ошибку, что и для необъявленной переменной другого типа.

Переменная курсора:

• Может быть целью типа курсора или другой переменной курсора. Дополнительные сведения см. в разделе SET @local_variable (Transact-SQL).

• Может быть объектом ссылки в качестве цели выходного параметра курсора в инструкции EXECUTE, если эта переменная не содержит курсора, назначенного ей в настоящее время.

• Должна рассматриваться в качестве указателя на курсор.

Примеры

А. Использование инструкции DECLARE

В следующем примере локальная переменная с именем @find используется для получения контактных данных для лиц с фамилией, начинающейся на Man.

USE AdventureWorks2022;
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;

Вот результирующий набор.

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. Использование инструкции DECLARE с двумя переменными

В следующем примере извлекаются имена представителей продаж Adventure Works Cycles, которые находятся на территории продаж Северная Америка n и имеют по крайней мере $2000 000 в продажах в течение года.

USE AdventureWorks2022;
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;

В. Объявление переменной типа table

В следующем примере создается переменная типа table, в которой хранятся значения, задаваемые в предложении OUTPUT инструкции UPDATE. Две следующие инструкции SELECT возвращают значения в табличную переменную @MyTableVar, а результаты операции обновления — в таблицу Employee. Результаты в столбце INSERTED.ModifiedDate отличаются от значений в столбце ModifiedDate таблицы Employee. Это связано с тем, что для таблицы AFTER UPDATE определен триггер ModifiedDate, обновляющий значение Employee до текущей даты. Однако столбцы, возвращенные из OUTPUT, отражают состояние данных перед срабатыванием триггеров. Дополнительные сведения см. в статье Предложение OUTPUT (Transact-SQL).

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. Объявление переменной таблицы типов со встроенными индексами

В указанном ниже примере создается переменная table с кластеризованным встроенным индексом и двумя некластеризованными встроенными индексами.

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

Указанный ниже запрос возвращает сведения об индексах, созданных в предыдущем запросе.

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

Е. Объявление переменной определяемого пользователем табличного типа

Следующий пример демонстрирует создание параметра, возвращающего табличное значение, или табличной переменной с именем @LocationTVP. Здесь требуется соответствующий определяемый пользователем табличный тип с именем LocationTableType. Дополнительные сведения о создании определяемого пользователем табличного типа см. в разделе CREATE TYPE (Transact-SQL). Дополнительные сведения о возвращающих табличные значения параметрах см. в разделе Использование параметров, возвращающих табличные значения (ядро СУБД).

DECLARE @LocationTVP
AS LocationTableType;

Примеры: Azure Synapse Analytics и система платформы аналитики (PDW)

F. Использование инструкции DECLARE

В следующем примере локальная переменная с именем @find используется для получения контактных данных для лиц с фамилией, начинающейся на 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;

G. Использование инструкции DECLARE с двумя переменными

В следующем примере используются переменные для указания имен и фамилий сотрудников в таблице 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;

См. также

• EXECUTE (Transact-SQL)
• Встроенные функции (Transact-SQL)
• SELECT (Transact-SQL)
• table (Transact-SQL)
• Сравнение типизированного и нетипизированного XML