CREATE FUNCTION

Применимо к:Конечная точка аналитики SQL в Microsoft Fabric и хранилище в Microsoft Fabric

CREATE FUNCTION создаёт встроенные табличные функции и скалярные функции.

Примечание.

Скалярные определяемые пользователем функции — это предварительная версия в хранилище данных Fabric.

Пользовательская функция — это Transact-SQL процедура, которая принимает параметры, выполняет действие, например, комплексное вычисление, и возвращает результат этого действия в виде значения. Скалярные функции возвращают скалярное значение, например число или строку. Определяемые пользователем табличные функции (TVFs) возвращают таблицу.

Используйте CREATE FUNCTION для создания повторно используемой T-SQL процедуры, которую можно использовать следующим образом:

  • В Transact-SQL утверждениях, таких как SELECT.
  • В Transact-SQL операторы обработки данных (DML), такие UPDATEкак , INSERT, и DELETE.
  • В приложениях вызывают функцию.
  • В определении другой пользовательской функции.
  • Чтобы заменить сохранённую процедуру.

Укажите CREATE OR ALTER FUNCTION , чтобы создать новую функцию, если она не существует под этим именем, или изменить существующую функцию в одном операторе.

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

Синтаксис

Синтаксис скалярной функции

CREATE FUNCTION [ schema_name. ] function_name   
( [ { @parameter_name [ AS ] parameter_data_type   
    [ = default ] }   
    [ ,...n ]  
  ]  
)  
RETURNS return_data_type  
    [ WITH <function_option> [ ,...n ] ]  
    [ AS ]  
    BEGIN   
        function_body   
        RETURN scalar_expression  
    END  
[ ; ]  

<function_option>::=   
{  
    [ INLINE = AUTO ]
  | [ SCHEMABINDING ]  
  | [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]  
}

Встроенный синтаксис функции с табличным значением

CREATE FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] parameter_data_type
    [ = default ] }
    [ ,...n ]
  ]
)
RETURNS TABLE
    [ WITH SCHEMABINDING ]
    [ AS ]
    RETURN [ ( ] select_stmt [ ) ]
[ ; ]

Аргументы

schema_name

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

function_name

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

Вы должны добавить скобки после имени функции, даже если параметр не указан.

@ parameter_name

Параметр в пользовательской функции. Вы можете объявить один или несколько параметров.

Функция может иметь до 2 100 параметров. Когда пользователь или приложение вызывает функцию, значение каждого объявленного параметра должно быть указано, если только для этого параметра не определено по умолчанию.

Определяет имя параметра, используя знак @ как первый символ. Имя параметра должно соответствовать правилам идентификаторов. Параметры локальны для функции; Вы можете использовать те же имена параметров в других функциях. Параметры могут заменять только константы; Их нельзя использовать вместо имён таблиц, имён столбцов или других объектов базы данных.

ANSI_WARNINGS не учитывается при передаче параметров в хранимой процедуре, определяемой пользователем функции или при объявлении и установке переменных в пакетной инструкции. Например, если определить переменную как char(3), а затем установить значение больше трёх символов, данные усекаются до определённого размера, и SQL-оператор работает успешно.

parameter_data_type

Тип данных параметра. Для функций Transact-SQL поддерживаются все скалярные типы данных .

[ = по умолчанию ]

Значение параметра по умолчанию. Если определить значение по умолчанию , можно выполнить функцию без указания значения для этого параметра.

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

return_data_type

Возвращаемое значение скалярной функции, определяемой пользователем.

Для функций в хранилище данных Fabric разрешены все типы данных, за исключениемметки времени/. Нескалярные типы, такие как таблицы , не разрешены.

function_body

Ряд операторов Transact-SQL.

В скалярных функциях function_body представляет собой ряд операторов Transact-SQL , которые вместе оценивают скалярное значение, которое может включать:

  • Выражение одной инструкции
  • Выражения с несколькими операторами (IF/THEN/ELSE и BEGIN/END блоки)
  • Локальные переменные
  • Вызовы встроенных функций SQL
  • Вызовы других определяемых пользователем функций
  • SELECT операторы и ссылки на таблицы, представления и встроенные функции с табличным значением
  • Операторы управления потоком (WHILE циклы, RETURNS)

scalar_expression

Указывает скалярное значение, возвращаемое скалярной функцией.

select_stmt

SELECT Одна инструкция, определяющая возвращаемое значение встроенной табличной функции. Для функции с встроенным таблицным значением тела функции не существует; Таблица — это набор результатов одного SELECT оператора.

TABLE

Указывает, что возвращаемым значением функции с табличным значением (TVF) является таблица. Вы можете передавать только константы и @local_variables TVF.

В встроенных TVF (предварительный просмотр) вы определяете TABLE возвратное значение через один SELECT оператор. Встроенные функции не имеют связанных переменных возврата.

<function_option>

В Fabric Data Warehouse ключевые ENCRYPTION слова и EXECUTE AS не поддерживаются.

Поддерживаемые функции включают:

ЛИНЕЙНЫЙ = АВТОМАТ

Задаёт, можно ли создавать или изменять скалярную пользовательскую функцию независимо от требований к инлайнированию. Условие INLINE является необязательным. Для линейного скалярного UDF указание INLINE = AUTO не меняет его инлайнируемость или поведение при выполнении.

SCHEMABINDING

Указывает, что функция привязана к объектам базы данных, которые содержат ссылки на нее. Когда вы задаёте SCHEMABINDING, вы не можете изменить исходные объекты (например, вид или таблицу) так, чтобы это влияло на определение функции. Сначала нужно изменить или отказаться от определения функции, чтобы убрать зависимости от объекта, который вы хотите изменить.

Привязка функции к ссылающимся на нее объектам удаляется в следующих случаях:

  • Ты отключаешь функцию.

  • Вы ALTER используете оператор функции и удалите эту SCHEMABINDING опцию.

Вы можете связать функцию схемой только при выполнении следующих условий:

  • Любые пользовательские функции, на которые ссылается функция, также связаны со схемой.

  • Функция ссылается на объекты с помощью двухчастного имени.

  • Внутри корпуса UDF можно ссылаться только на встроенные функции и другие UDF в одной базе данных.

  • Пользователь, исполняющий этот CREATE FUNCTION оператор, имеет право REFERENCES на объекты базы данных, на которые ссылается функция.

Чтобы удалить SCHEMABINDING, используйте ALTER.

ВОЗВРАЩАЕТ ЗНАЧЕНИЕ NULL ДЛЯ ВХОДНЫХ ДАННЫХ NULL | ВЫЗЫВАЕТСЯ ДЛЯ ВХОДНЫХ ДАННЫХ NULL

Задает OnNULLCall атрибут скалярной функции. Если не указать этот атрибут, то CALLED ON NULL INPUT подразумевается по умолчанию, и тело функции выполняется даже если NULL оно передаётся как аргумент.

Рекомендации

Это важно

В Fabric Data Warehouse скалярные UDF должны быть inlineable для использования с SELECT ... FROM запросами к пользовательским таблицам, но вы всё равно можете создавать функции, которые не являются inlineable, указав WITH INLINE = AUTO опцию функции. Скалярные UDF, которые не являются линейными, работают в ограниченном числе сценариев. Вы можете проверить, можно ли встраить UDF.

  • Если вы не создаёте пользовательскую функцию с помощью schemabinding, изменения в базовых объектах могут повлиять на определение функции и вызвать неожиданные результаты при её вызове. Когда вы указываете WITH SCHEMABINDING момент создания функции, вы гарантируете, что последующие изменения в базовых объектах не смогут изменить или нарушить поведение функции.

  • Пишите свои пользовательские функции так, чтобы они были нелинейными. Для получения дополнительной информации о концепции инлайнирования см. раздел «Инлайнирование скалярного UDF». Для примеров того, как сделать скалярный UDF инлайнируемым, см. Создать скалярный UDF в Microsoft Fabric Data Warehouse.

Совместимость

Встроенные пользовательские функции с табличным значением

Встроенная функция с таблицным значением принимает только один SELECT оператор.

Скалярные пользовательские функции

  • Нелинейная функция не может использоваться в SELECT ... FROM запросе к пользовательской таблице.

  • В скалярных функциях допустимы следующие инструкции с одиночным значением.

    • Инструкции присваивания.
    • Операторы управления потоком, кроме TRY...CATCH и GOTO операторов.
    • DECLARE операторы, определяющие локальные переменные данных.
    • Вызовы встроенных функций.
    • Ссылки на таблицы/виды/iTVF/другие скалярные UDF.

  • Операторы DML не разрешены в скалярных пользовательских функциях.

  • В теле функции с скалярным значением не поддерживаются следующие встроенные функции:

Метаданные

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

  • sys.sql_modules: отображает определение Transact-SQL пользовательских функций, а также информацию о инлайнируемости. Например:

      SELECT 
      SCHEMA_NAME(o.schema_id) AS SchemaName,
      o.name AS FunctionName,
      m.definition AS FunctionDefinition,
      m.is_inlineable AS Inlineable,
      m.inline_eligibility_mask AS InlineEligibilityMask
  FROM sys.objects o
  JOIN sys.sql_modules m ON o.object_id = m.object_id
  WHERE o.type = 'FN';

  • sys.parameters: отображает сведения о параметрах, определенных в определяемых пользователем функциях.

  • sys.sql_expression_dependencies: отображает базовые объекты, на которые ссылается функция.

Разрешения

Члены роли администратора рабочей области Fabric, участника и участника могут создавать функции.

Инлайнирование скалярного UDF

Microsoft Fabric Data Warehouse использует различные техники инлайнирования для компиляции и выполнения пользовательского кода в распределённой форме.

Инлайнирование скалярного UDF по умолчанию включено.

Некоторый синтаксис T-SQL делает скалярный UDF нелинейным. Например, функции, содержащие комбинацию WHILE цикла и ссылающиеся на таблицу внутри тела UDF, не могут быть инлайнированы.

Проверьте, можно ли встраить скалярную UDF

Представление sys.sql_modules каталога содержит столбец is_inlineable, указывающий, является ли UDF встроенным. Свойство is_inlineable возникает при проверке синтаксиса внутри определения UDF. Скалярный UDF инлайнируется только во время компиляции.

В этом inline_eligibility_mask свойстве объясняется, какой тип инлайнинга применим к UDF.

  • Значение означает 0 , что UDF не является линейным.
  • Значение указывает 1 на то, что UDF подходит для инлайнирования скалярных UDF.
  • Значение означает 2 , что UDF может быть инлайнирован через блок Expression.
  • Значение означает 3 , что UDF подходит для любой из методов инлайнирования.

Это важно

Если скалярный UDF может быть инлайнируем только через скалярное UDF-инлайнирование, это не гарантирует, что он всегда инлайнирован при компиляции запроса.

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

SELECT 
SCHEMA_NAME(b.schema_id) as function_schema_name,
    b.name as function_name,
       b.type_desc as function_type,
       a.is_inlineable
FROM sys.sql_modules AS a
     INNER JOIN sys.objects AS b
         ON a.object_id = b.object_id
WHERE b.type IN ('FN');

Если скалярная функция не является инлайнируемой в sys.sql_modules.is_inlineable, вы всё равно можете выполнить запрос как отдельный вызов, например, для установки переменной. Скалярная функция не может быть частью SELECT ... FROM запроса в пользовательской таблице. Например:

CREATE FUNCTION [dbo].[custom_SYSUTCDATETIME]()
  RETURNS datetime2(6)
  AS
  BEGIN
   RETURN SYSUTCDATETIME();
  END

Выборочная dbo.custom_SYSUTCDATETIME скалярная пользовательская функция не является линейной, потому что использует недетерминированную системную функцию, SYSUTCDATETIME(). Он не работает при использовании в SELECT ... FROM запросе к пользовательской таблице, но успешно работает как самостоятельный вызов. Например:

DECLARE @utcdate datetime2(7);
SET @utcdate = dbo.custom_SYSUTCDATETIME();
SELECT @utcdate as 'utc_date';

Ограничения

Примечание.

Скалярные определяемые пользователем функции — это предварительная версия в хранилище данных Fabric. Во время текущей предварительной версии ограничения могут быть изменены.

  • Когда скалярный UDF используется в любом неподдерживаемом сценарии, при выполнении запроса появляется сообщение Scalar UDF execution is currently unavailable in this context. об ошибке.

  • Скалярный UDF нельзя инлайнировать через блок выражения , когда:

  • Скалярный UDF не может быть инлайнирован скалярным UDF при следующих условиях. Для получения дополнительной информации см. раздел «Инлайнирование скалярного UDF».

    • Скалярный UDF нельзя инлайнировать через скалярное UDF-инлайнирование, если скалярное тело UDF содержит WHILE петлю BREAK или CONTINUE оператор.
    • Скалярный UDF нельзя инлайнировать через скалярное UDF-инлайнирование, если скалярное тело UDF содержит несколько RETURN операторов.
    • Скалярный UDF нельзя инлайнировать с помощью скалярного UDF-инлайнирования, если скалярное тело UDF содержит встроенную функцию, зависящую от времени, такую как GETDATE(). Дополнительные сведения см. в разделе детерминированные и недетерминированные функции.
    • Скалярный UDF нельзя инлайнировать с помощью скалярного инлайнирования, если скалярное тело UDF содержит функцию STRING_AGG, функцию JSON_ARRAYAGG или другие системные функции.

  • Можно вкладывать пользовательские функции. То есть одна определяемая пользователем функция может вызывать другую. Уровень вложения увеличивается при начале выполнения вызываемой функции, а уменьшается — когда вызванная функция завершает выполнение. В Fabric Data Warehouse вы можете вкладывать пользовательские функции до четырёх уровней, если тело UDF ссылается на таблицу, представление или функцию с встроенными значениями таблицы, или до 32 уровней в противном случае. Если вы превысите максимальный уровень вложения, цепочка вызова функций не выходит из строя.

  • Дополнительные сведения см. в статье о требованиях к встраивание скалярных UDF.

  • Скалярный UDF не может использоваться во всех формах запроса, в зависимости от того, какая техника инлайнирования применима.

    • Для скалярного инлайнирования UDF:
      • Скалярный UDF не может использоваться в GROUP BY и ORDER BY.
      • Скалярный UDF нельзя использовать в сочетании с CTE.
      • Пользовательский запрос может провалиться, если в одном запросе совершается более 10 вызовов UDF.

  • В Fabric Data Warehouse скалярный UDF не может использоваться в ROLLUP, CUBE, или GROUPING SETS.

Предупреждение

Если запрос содержит несколько скалярных UDF, и хотя бы один из них использует скалярное UDF-инлайнирование, весь запрос должен соответствовать требованиям скалярного UDF-инлайнирования.

Примеры

А. Создание встроенной табличной функции

Следующий пример создаёт встроенную функцию со значением таблицы, которая возвращает ключевую информацию о модулях, фильтруя по параметру objectType . Он включает значение по умолчанию для возврата всех модулей при вызове функции с параметром DEFAULT . В этом примере используются некоторые из представлений системных каталогов, упомянутых в метаданных.

CREATE FUNCTION dbo.ModulesByType (@objectType CHAR(2) = '%%')
RETURNS TABLE
AS
RETURN (
        SELECT sm.object_id AS 'Object Id',
            o.create_date AS 'Date Created',
            OBJECT_NAME(sm.object_id) AS 'Name',
            o.type AS 'Type',
            o.type_desc AS 'Type Description',
            sm.DEFINITION AS 'Module Description',
            sm.is_inlineable AS 'Inlineable'
        FROM sys.sql_modules AS sm
        INNER JOIN sys.objects AS o ON sm.object_id = o.object_id
        WHERE o.type LIKE '%' + @objectType + '%'
        );
GO

Вызовите функцию для возврата всех входящих таблицных функций (IF):

SELECT * FROM dbo.ModulesByType('IF'); -- SQL_INLINE_TABLE_VALUED_FUNCTION

Или найдите все скалярные функции (FN):

SELECT * FROM dbo.ModulesByType('FN'); -- SQL_SCALAR_FUNCTION

В. Объединение результатов встроенной табличной функции

Этот простой пример использует ранее созданный встроенный TVF, чтобы показать, как можно комбинировать его результаты с другими таблицами с CROSS APPLYпомощью . Здесь вы выбираете все столбцы из обоих sys.objects и результаты для ModulesByType всех строк, совпадающих в столбце type . Для получения дополнительной информации о использовании APPLYсм. пункт FROM плюс JOIN, APPLY, PIVOT (Transact-SQL).

SELECT * 
FROM sys.objects AS o
CROSS APPLY dbo.ModulesByType(o.type);
GO

С. Создание скалярной функции UDF

В следующем примере создается встроенный скалярный UDF, который маскирует входной текст.

CREATE OR ALTER FUNCTION [dbo].[cleanInput] (@InputString VARCHAR(100))
    RETURNS VARCHAR(50)
    AS
    BEGIN
        DECLARE @Result VARCHAR(50);
        DECLARE @CleanedInput VARCHAR(50);

        -- Trim whitespace
        SET @CleanedInput = LTRIM(RTRIM(@InputString));

        -- Handle empty or null input
        IF @CleanedInput = '' OR @CleanedInput IS NULL
        BEGIN
            SET @Result = '';
        END
        ELSE IF LEN(@CleanedInput) <= 2
        BEGIN
            -- If string length is 1 or 2, just return the cleaned string
            SET @Result = @CleanedInput;
        END
        ELSE
        BEGIN
            -- Construct the masked string
            SET @Result = 
                LEFT(@CleanedInput, 1) +
                REPLICATE('*', LEN(@CleanedInput) - 2) +
                RIGHT(@CleanedInput, 1);
        END

        RETURN @Result
    END

Эту функцию можно вызвать следующим образом:

DECLARE @input varchar(100) = '123456789';

SELECT dbo.cleanInput (@input) AS function_output;

Дополнительные примеры использования скалярных определяемых пользователем файлов в хранилище данных Fabric:

В инструкции SELECT :

SELECT TOP 10 
t.id, t.name, 
dbo.cleanInput (t.name) AS function_output
FROM dbo.MyTable AS t;

В предложении WHERE :

 SELECT t.id, t.name, dbo.cleanInput(t.name) AS function_output
FROM dbo.MyTable AS t
WHERE dbo.cleanInput(t.name)='myvalue';

В предложении JOIN :

SELECT t1.id, t1.name, 
     dbo.cleanInput (t1.name) AS function_output, 
     dbo.cleanInput (t2.name) AS function_output_2
FROM dbo.MyTable1 AS t1
    INNER JOIN dbo.MyTable2 AS t2 
        ON dbo.cleanInput(t1.name)=dbo.cleanInput(t2.name);

В предложении ORDER BY :

SELECT  t.id, t.name, dbo.cleanInput (t.name) AS function_output
FROM dbo.MyTable AS t
ORDER BY function_output;

В операторах языка обработки данных (DML), таких как INSERT, UPDATEили DELETE:

SELECT t.id, t.name, dbo.cleanInput (t.name) AS function_output 
INTO dbo.MyTable_new
FROM dbo.MyTable AS t;

UPDATE t
SET t.mycolumn_new = dbo.cleanInput (t.name)
FROM dbo.MyTable AS t;

DELETE t
FROM dbo.MyTable AS t
WHERE dbo.cleanInput (t.name) ='myvalue';

Связанный контент

Область применения:Azure Synapse Analytics AnalyticsPlatform System (PDW)

Создает определяемую пользователем функцию (UDF) в Azure Synapse Analytics или Analytics Platform System (PDW). Определяемая пользователем функция представляет собой подпрограмму Transact-SQL, которая принимает параметры, выполняет действие, например сложное вычисление, а затем возвращает результат этого действия в виде значения. Определяемые пользователем табличные функции (TVFs) возвращают тип данных таблицы.

Подсказка

Для синтаксиса в Fabric Data Warehouse см. версию CREATE FUNCTION для Fabric Data Warehouse.

  • В системе платформы аналитики (PDW) возвращаемое значение должно быть скалярным (одним) значением.

  • В Azure Synapse Analytics CREATE FUNCTION можно возвращать таблицу с помощью синтаксиса встроенных табличных функций (предварительная версия) или возвращать одно значение с помощью синтаксиса скалярных функций.

  • В бессерверных пулах SQL в Azure Synapse Analytics можно создавать встроенные функции табличного значения, CREATE FUNCTION но не скалярные функции.

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

  • В инструкциях Transact-SQL, таких как SELECT

  • В приложениях, вызывающих функцию

  • В определении другой пользовательской функции.

  • Для определения ограничения CHECK на столбец.

  • Для замены хранимой процедуры.

  • Использование встроенной функции в качестве предиката фильтра для политики безопасности

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

Синтаксис

Синтаксис скалярной функции

-- Transact-SQL Scalar Function Syntax (in dedicated pools in Azure Synapse Analytics and Parallel Data Warehouse)
-- Not available in the serverless SQL pools in Azure Synapse Analytics

CREATE FUNCTION [ schema_name. ] function_name   
( [ { @parameter_name [ AS ] parameter_data_type   
    [ = default ] }   
    [ ,...n ]  
  ]  
)  
RETURNS return_data_type  
    [ WITH <function_option> [ ,...n ] ]  
    [ AS ]  
    BEGIN   
        function_body   
        RETURN scalar_expression  
    END  
[ ; ]  

<function_option>::=   
{  
    [ SCHEMABINDING ]  
  | [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]  
}

Встроенный синтаксис функции с табличным значением

-- Transact-SQL Inline Table-Valued Function Syntax
-- Preview in dedicated SQL pools in Azure Synapse Analytics
-- Available in the serverless SQL pools in Azure Synapse Analytics
CREATE FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] parameter_data_type
    [ = default ] }
    [ ,...n ]
  ]
)
RETURNS TABLE
    [ WITH SCHEMABINDING ]
    [ AS ]
    RETURN [ ( ] select_stmt [ ) ]
[ ; ]

Аргументы

schema_name

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

function_name

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

Примечание.

Вы должны добавить скобки после имени функции, даже если параметр не указан.

@ parameter_name

Параметр в пользовательской функции. Вы можете объявить один или несколько параметров.

Функция может иметь до 2 100 параметров. Когда пользователь или приложение вызывает функцию, значение каждого объявленного параметра должно быть указано, если только для этого параметра не определено по умолчанию.

Определяет имя параметра, используя знак @ как первый символ. Имя параметра должно соответствовать правилам идентификаторов. Параметры локальны для функции; Вы можете использовать те же имена параметров в других функциях. Параметры могут заменять только константы; Их нельзя использовать вместо имён таблиц, имён столбцов или других объектов базы данных.

Примечание.

ANSI_WARNINGS не учитывается при передаче параметров в хранимой процедуре, определяемой пользователем функции или при объявлении и установке переменных в пакетной инструкции. Например, если определить переменную как char(3), а затем установить значение больше трёх символов, данные урезают до определённого размера, и INSERT оператор or UPDATE выполняется успешно.

parameter_data_type

Тип данных параметра. Для функций Transact-SQL допускаются все скалярные типы данных, которые поддерживаются в Azure Synapse Analytics. Тип данных с временной меткой (rowversion) не поддерживается.

[ = по умолчанию ]

Значение параметра по умолчанию. Если определить значение по умолчанию , можно выполнить функцию без указания значения для этого параметра.

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

return_data_type

Возвращаемое значение скалярной функции, определяемой пользователем. Для функций Transact-SQL допускаются все скалярные типы данных, которые поддерживаются в Azure Synapse Analytics. Типданных с временной меткой/ не поддерживается. Курсор и нескалярные типы не разрешены.

function_body

Ряд инструкций Transact-SQL. function_body не может содержать SELECT оператор и не может ссылаться на данные базы данных. function_body не может ссылаться на таблицы или представления. Тело функций может вызывать другие детерминированные функции, но не может вызывать недетерминированные функции.

Для скалярных функций function_body представляет собой ряд инструкций Transact-SQL, совместное выполнение которых вычисляет скалярное выражение.

scalar_expression

Указывает скалярное значение, возвращаемое скалярной функцией.

select_stmt

SELECT Одна инструкция, определяющая возвращаемое значение встроенной табличной функции. Для функции с встроенным таблицным значением тела функции не существует; Таблица — это набор результатов одного SELECT оператора.

TABLE

Указывает, что возвращаемым значением функции с табличным значением (TVF) является таблица. Вы можете передавать только константы и @local_variables TVF.

В встроенных TVF (предварительный просмотр) вы определяете TABLE возвратное значение через один SELECT оператор. Встроенные функции не имеют связанных переменных возврата.

<function_option>

Указывает, что функция имеет один или несколько следующих параметров.

SCHEMABINDING

Указывает, что функция привязана к объектам базы данных, которые содержат ссылки на нее. Когда вы задаёте SCHEMABINDING, вы не можете изменить исходные объекты (например, вид или таблицу) так, чтобы это влияло на определение функции. Сначала нужно изменить или отказаться от определения функции, чтобы убрать зависимости от объекта, который вы хотите изменить.

Привязка функции к ссылающимся на нее объектам удаляется в следующих случаях:

  • Ты отключаешь функцию.

  • Вы ALTER используете оператор функции и удалите эту SCHEMABINDING опцию.

Вы можете связать функцию схемой только при выполнении следующих условий:

  • Любые пользовательские функции, на которые ссылается функция, также связаны со схемой.

  • Ссылки на функции используют имена из одной или двух частей.

  • Внутри корпуса UDF можно ссылаться только на встроенные функции и другие UDF в одной базе данных.

  • Пользователь, исполняющий этот CREATE FUNCTION оператор, имеет право REFERENCES на объекты базы данных, на которые ссылается функция.

Чтобы удалить SCHEMABINDING, используйте ALTER.

ВОЗВРАЩАЕТ ЗНАЧЕНИЕ NULL ДЛЯ ВХОДНЫХ ДАННЫХ NULL | ВЫЗЫВАЕТСЯ ДЛЯ ВХОДНЫХ ДАННЫХ NULL

Задает OnNULLCall атрибут скалярной функции. Если не указать этот атрибут, то CALLED ON NULL INPUT подразумевается по умолчанию, и тело функции выполняется даже если NULL оно передаётся как аргумент.

Рекомендации

Если вы не создаёте пользовательскую функцию с клаузой SCHEMABINING, изменения в базовых объектах могут повлиять на определение функции и вызвать неожиданные результаты при её вызове. Указывайте клаузу WITH SCHEMABINDING при создании функции. Это предложение гарантирует, что вы не сможете изменить объекты, указанные в определении функции, если вы не измените и саму функцию.

Совместимость

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

  • Инструкции присваивания.

  • Операторы управления потоком, кроме TRY... Ключевые заявления.

  • Операторы DECIDE, определяющие локальные переменные данных.

В функции с встроенным таблицным значением (предпросмотр) можно использовать только один оператор select.

Ограничения

Нельзя использовать пользовательские функции для выполнения действий, изменяющих состояние базы данных.

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

Вы не можете создавать объекты, включая функции, в master базе данных вашего серверного SQL-пула в Azure Synapse Analytics.

Метаданные

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

  • sys.sql_modules: отображает определение Transact-SQL определяемых пользователем функций. Например:

    SELECT definition, type   
FROM sys.sql_modules AS m  
JOIN sys.objects AS o   
    ON m.object_id = o.object_id   
    AND type = ('FN');

  • sys.parameters: отображает сведения о параметрах, определенных в определяемых пользователем функциях.

  • sys.sql_expression_dependencies: отображает базовые объекты, на которые ссылается функция.

Разрешения

Требуется CREATE FUNCTION разрешение в базе данных и разрешение ALTER на схеме, в которой создаётся функция.

Примеры

А. Использование скалярной определяемой пользователем функции для изменения типа данных

Эта простая функция принимает int-тип данных в качестве входа и возвращает десятичный(10,2) тип данных в качестве выхода.

CREATE FUNCTION dbo.ConvertInput (@MyValueIn int)  
RETURNS decimal(10,2)  
AS  
BEGIN
    DECLARE @MyValueOut int;  
    SET @MyValueOut= CAST( @MyValueIn AS decimal(10,2));  
    RETURN(@MyValueOut);  
END;  
GO  

SELECT dbo.ConvertInput(15) AS 'ConvertedValue';

Примечание.

Скалярные функции недоступны в бессерверных SQL-пулах.

В. Создание встроенной табличной функции

Следующий пример создаёт встроенную функцию со значением таблицы, которая возвращает ключевую информацию о модулях, фильтруя по параметру objectType . Он включает значение по умолчанию для возврата всех модулей при вызове функции с параметром DEFAULT . В этом примере используются некоторые из представлений системных каталогов, упомянутых в метаданных.

CREATE FUNCTION dbo.ModulesByType(@objectType CHAR(2) = '%%')
RETURNS TABLE
AS
RETURN
(
    SELECT 
        sm.object_id AS 'Object Id',
        o.create_date AS 'Date Created',
        OBJECT_NAME(sm.object_id) AS 'Name',
        o.type AS 'Type',
        o.type_desc AS 'Type Description', 
        sm.definition AS 'Module Description'
    FROM sys.sql_modules AS sm  
    JOIN sys.objects AS o ON sm.object_id = o.object_id
    WHERE o.type like '%' + @objectType + '%'
);
GO

Вы можете вызвать функцию для возврата всех объектов view (V) с помощью следующих видов:

select * from dbo.ModulesByType('V');

Примечание.

Встроенные функции table-value доступны в серверных SQL-пулах, но в предварительном просмотре в выделенных SQL-пулах.

С. Объединение результатов встроенной табличной функции

Этот простой пример использует ранее созданный встроенный TVF, чтобы показать, как можно комбинировать его результаты с другими таблицами с CROSS APPLYпомощью . В этом примере вы выбираете все столбцы из обоих sys.objects и результаты для ModulesByType всех строк, совпадающих в столбце type . Для получения дополнительной информации о использовании APPLYсм. пункт FROM плюс JOIN, APPLY, PIVOT (Transact-SQL).

SELECT * 
FROM sys.objects o
CROSS APPLY dbo.ModulesByType(o.type);
GO

Примечание.

Встроенные функции table-value доступны в серверных SQL-пулах, но в предварительном просмотре в выделенных SQL-пулах.

Следующий шаг

Создание определяемых пользователем функций (ядро СУБД)

  • Last updated on