CREATE FUNCTION

Aplica-se a:Endpoint de análise SQL no Microsoft Fabric e Warehouse no Microsoft Fabric

CREATE FUNCTION cria funções de tabela em linha e funções escalares.

Uma função definida pelo utilizador é uma rotina Transact-SQL que aceita parâmetros, realiza uma ação como um cálculo complexo e devolve o resultado dessa ação como valor. As funções escalares retornam um valor escalar, como um número ou uma cadeia de caracteres. Funções com valor de tabela definidas pelo usuário (TVFs) retornam uma tabela.

Use CREATE FUNCTION para criar uma rotina T-SQL reutilizável que possa usar das seguintes formas:

• Em Transact-SQL declarações como SELECT
• Em Transact-SQL declarações de manipulação de dados (DML), como UPDATE, INSERTe DELETE
• Em aplicativos que chamam a função
• Na definição de outra função definida pelo utilizador
• Para substituir um procedimento armazenado

Pode especificar CREATE OR ALTER FUNCTION a criação de uma nova função se não existir nenhuma com esse nome, ou alterar uma função existente, numa única instrução.

Transact-SQL convenções de sintaxe

Sintaxe

Sintaxe da função escalar

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

Sintaxe da função com valor de tabela embutido

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

Argumentos

schema_name

O nome do esquema ao qual a função definida pelo usuário pertence.

function_name

O nome da função definida pelo usuário. Os nomes das funções devem seguir as regras dos identificadores e ser únicos dentro da base de dados e do seu esquema.

@ parameter_name

Um parâmetro na função definida pelo usuário. Pode declarar um ou mais parâmetros.

Uma função pode ter até 2.100 parâmetros. Quando um utilizador ou aplicação chama uma função, o valor de cada parâmetro declarado deve ser fornecido, a menos que seja definido um padrão para o parâmetro.

Especifique um nome de parâmetro usando um sinal de arroba (@) como o primeiro caractere. O nome do parâmetro deve seguir as regras dos identificadores. Os parâmetros são locais à função; Podes usar os mesmos nomes de parâmetros noutras funções. Os parâmetros só podem substituir constantes; não podem ser usados em vez de nomes de tabelas, nomes de colunas ou nomes de outros objetos de base de dados.

parameter_data_type

O tipo de dados do parâmetro. Para funções Transact-SQL, todos os tipos de dados escalares suportados são permitidos .

[ = padrão ]

Um valor padrão para o parâmetro. Se definir um valor por defeito , pode executar a função sem especificar um valor para esse parâmetro.

Quando um parâmetro da função tem um valor predefinido, deve especificar a palavra-chave DEFAULT ao chamar a função para recuperar o valor predefinido. Esse comportamento é diferente do uso de parâmetros com valores padrão em procedimentos armazenados em que omitir o parâmetro também implica o valor padrão.

return_data_type

O valor de retorno de uma função escalar definida pelo usuário.

Para funções no Fabric Data Warehouse, todos os tipos de dados são permitidos, exceto ocarimbo de data/hora/ de linha. Tipos não escalares como tabela não são permitidos.

function_body

Uma série de declarações Transact-SQL.

Em funções escalares, function_body é uma série de Transact-SQL instruções que, juntas, avaliam até um valor escalar, que pode incluir:

• Expressão de instrução única
• Expressões com várias instruções (IF/THEN/ELSE e BEGIN/END blocos)
• Variáveis locais
• Chamadas para funções SQL incorporadas disponíveis
• Chamadas para outras UDFs
• SELECT instruções e referências a tabelas, exibições e funções com valor de tabela embutido
• Instruções de fluxo de controlo (WHILE loops, RETURNS)

scalar_expression

Especifica o valor escalar que a função escalar retorna.

select_stmt

A instrução única SELECT que define o valor de retorno de uma função com valor de tabela embutido. Para uma função com valores de tabela em linha, não existe corpo de funções; a tabela é o conjunto de resultados de uma única SELECT afirmação.

TABLE

Especifica que o valor de retorno da função com valor de tabela (TVF) é uma tabela. Só podes passar constantes e @local_variables aos TVFs.

Nos TVFs inline (pré-visualização), define-se o TABLE valor de retorno através de uma única SELECT instrução. As funções embutidas não têm variáveis de retorno associadas.

<function_option>

Em Fabric Data Warehouse, as INLINEpalavras-chave , ENCRYPTION, e EXECUTE AS não são suportadas.

As opções de função suportadas incluem:

SCHEMABINDING

Especifica que a função está vinculada aos objetos de banco de dados aos quais faz referência. Quando especificas SCHEMABINDING, não podes modificar os objetos subjacentes (como uma vista ou uma tabela, por exemplo) de uma forma que afete a definição da função. Deve primeiro modificar ou eliminar a definição da função para remover dependências do objeto que pretende modificar.

A associação da função aos objetos aos quais ela faz referência é removida somente quando ocorre uma das seguintes ações:

• Deixas de usar a função.

• Usa ALTER a declaração de função e remove a SCHEMABINDING opção.

Só pode vincular um esquema a uma função se as seguintes condições forem verdadeiras:

• Quaisquer funções definidas pelo utilizador que a função referenciam também são limitadas ao esquema.

• A função faz referência a objetos usando um nome em duas partes.

• No corpo dos UDFs, só pode referenciar funções incorporadas e outros UDFs na mesma base de dados.

• O utilizador que executa a CREATE FUNCTION instrução tem permissão REFERENCES sobre os objetos da base de dados que a função referencia.

Para remover SCHEMABINDING, use ALTER.

DEVOLVE NULL NA ENTRADA NULA | CHAMADA NA ENTRADA NULA

Especifica o OnNULLCall atributo de uma função com valor escalar. Se não especificares este atributo, CALLED ON NULL INPUT está implícito por defeito, e o corpo da função executa-se mesmo que NULL seja passado como argumento.

Melhores práticas

• Se não criar uma função definida pelo utilizador com schemabinding, alterações aos objetos subjacentes podem afetar a definição da função e causar resultados inesperados ao invocar a função. Quando especifica WITH SCHEMABINDING quando cria a função, assegura que alterações posteriores aos objetos subjacentes não podem alterar ou quebrar o comportamento da função.

• Escreva as suas funções definidas pelo utilizador para serem inlineáveis. Para obter mais informações, consulte Scalar UDF inlining.

Interoperabilidade

Funções definidas pelo usuário com valor de tabela embutido

Uma função com valores em tabela em linha aceita apenas uma única SELECT afirmação.

Funções escalares definidas pelo usuário

• As instruções a seguir são válidas em uma função de valor escalar:

  • Declarações de atribuição
  • Instruções de controle de fluxo, exceto TRY...CATCH instruções
  • DECLARE instruções que definem variáveis de dados locais

• As seguintes funções internas não são suportadas em um corpo de função com valor escalar:

  • NEWID()
  • RAND()
  • Funções de configuração
  • DATABASEPROPERTYEX
  • OBJECTPROPERTYEX
  • SERVERPROPERTY
  • PRÓXIMO VALOR PARA
  • COLLATIONPROPERTY
  • HAS_PERMS_BY_NAME
  • HAS_DBACCESS

• UDFs escalares não podem ser usadas em uma SELECT ... FROM consulta em uma tabela de usuário quando:

  • O corpo UDF contém uma chamada para funções incorporadas não determinísticas (como GETDATE()), veja Funções determinísticas e não determinísticas.
  • O órgão da UDF contém BREAK a nossa CONTINUE declaração.
  • Existe uma chamada UDF escalar recursiva.

• Um UDF escalar não pode ser usado em todas as formas de consulta, como CTEs e GROUP BY, se:

  • A UDF escalar contém qualquer um destes tipos de dados como parâmetro de entrada, variável local ou tipo de devolução de dados: varchar(max),nvarchar(max), varbinary(max), binary(max).
  • O corpo escalar das UDFs contém chamadas para outras UDFs escalares.
  • O corpo escalar do UDF contém referências a tabelas/vistas/iTVF.

Para obter mais informações, consulte Requisitos de inlining UDF escalar.

• Se um UDF escalar contiver algum dos seguintes elementos, uma consulta do utilizador pode falhar se forem feitas mais de 10 chamadas UDF numa única consulta. Em alguns casos de borda, a complexidade da consulta do usuário e do corpo UDF impede o inlining, caso em que o UDF escalar não está embutido e a consulta do usuário falha.

  • A UDF escalar contém qualquer um destes tipos de dados como parâmetro de entrada, variável local ou tipo de devolução de dados: varchar(max),nvarchar(max), varbinary(max), binary(max).
  • O corpo escalar das UDFs contém chamadas para outras UDFs escalares.
  • O corpo escalar do UDF contém referências a tabelas/vistas/iTVF.

• Quando um UDF escalar é usado em qualquer cenário sem suporte, você vê uma mensagem de erro "Scalar UDF execution is currently unavailable in this context."

Limitações

Não podes usar funções definidas pelo utilizador para realizar ações que modifiquem o estado da base de dados.

Podes aninhar funções definidas pelo utilizador. Ou seja, uma função definida pelo usuário pode chamar outra. O nível de aninhamento incrementa quando a função chamada inicia a execução, e diminui quando a função chamada termina a execução. Em Fabric Data Warehouse, pode aninhar funções definidas pelo utilizador até quatro níveis quando um corpo UDF faz referência a uma tabela, vista ou função de tabela inline, ou até 32 níveis caso contrário. Se ultrapassar os níveis máximos de aninhamento, a cadeia de funções de chamada falha.

Metadados

Esta seção lista as exibições do catálogo do sistema que você pode usar para retornar metadados sobre funções definidas pelo usuário.

• sys.sql_modules: Apresenta a definição de Transact-SQL funções definidas pelo utilizador, bem como informação de inlineabilidade. Por exemplo:

   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: Exibe informações sobre os parâmetros definidos em funções definidas pelo usuário.

• sys.sql_expression_dependencies: Exibe os objetos subjacentes referenciados por uma função.

Permissões

Os membros das funções de Administrador, Membro e Colaborador do espaço de trabalho Malha podem criar funções.

Inlining de UDF escalar

Microsoft Fabric Data Warehouse utiliza diferentes técnicas de inlining para compilar e executar código definido pelo utilizador de forma distribuída.

O inlining do UDF escalar está ativado por defeito.

Algumas sintaxes T-SQL tornam um UDF escalar não inlineável. Por exemplo, funções que contêm uma combinação de um WHILE loop e fazem referência a uma tabela dentro do corpo do UDF não podem ser em linha. Para obter mais informações, consulte Requisitos de inlining UDF escalar.

Verifique se uma UDF escalar pode ser embutida

A sys.sql_modules exibição de catálogo inclui a coluna is_inlineable, que indica se um UDF é inlineável. A is_inlineable propriedade vem da verificação da sintaxe dentro da definição UDF. O UDF escalar não é inlineado antes do tempo de compilação.

A inline_eligibility_mask propriedade explica que tipo de inlining é aplicável a um UDF.

• Um valor de 0 significa que a UDF não é inlineável.
• Um valor de 1 indica que a UDF é elegível para o inlining Scalar UDF.
• Um valor de 2 significa que o UDF é elegível para inlining via bloco de expressão.
• Um valor de 3 significa que a UDF é elegível para qualquer uma das técnicas de inlining.

Se um UDF escalar for inlineável, isso não garante que esteja sempre em linha quando a consulta é compilada.

Fabric Data Warehouse decide (por consulta) qual a técnica de inlining a aplicar.

Use a seguinte consulta de exemplo para verificar se um UDF escalar é inlineável:

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');

Se uma função escalar não for inlineável em sys.sql_modules.is_inlineable, ainda pode executar a consulta como uma chamada autónoma, por exemplo, para definir uma variável. Mas a função escalar não pode fazer parte de uma SELECT ... FROM consulta numa tabela de utilizador. Por exemplo:

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

A função escalar definida pelo utilizador da amostra dbo.custom_SYSUTCDATETIME não é inlineável devido ao uso de uma função do sistema não determinante, SYSUTCDATETIME(). Falha quando é usado numa SELECT ... FROM consulta numa tabela de utilizador, mas tem sucesso como chamada autónoma. Por exemplo:

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

Exemplos

Um. Criar uma função com valor de tabela embutido

O exemplo seguinte cria uma função inline com valores de tabela que devolve informações-chave sobre módulos, filtrando pelo objectType parâmetro. Inclui um valor padrão para devolver todos os módulos quando chamas a função com o DEFAULT parâmetro. Este exemplo utiliza algumas das visualizações de catálogo do sistema mencionadas em Metadados.

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

Chame a função para devolver todas as funções de tabela em linha (IF):

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

Ou, localize todas as funções escalares (FN):

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

B. Combinar resultados de uma função com valor de tabela embutido

Este exemplo simples utiliza o TVF inline previamente criado para demonstrar como pode combinar os seus resultados com outras tabelas usando CROSS APPLY. Aqui, seleciona todas as colunas de ambos sys.objects e os resultados de ModulesByType para todas as linhas que correspondem na type coluna. Para mais informações sobre a utilização APPLYde , veja a cláusula FROM mais JOIN, APPLY, PIVOT (Transact-SQL).

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

C. Criar uma função UDF escalar

O exemplo a seguir cria um UDF escalar inlineável que mascara um texto de entrada.

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

Você pode chamar a função assim:

DECLARE @input varchar(100) = '123456789'

SELECT dbo.cleanInput (@input) AS function_output;

Mais exemplos de como você pode usar UDFs escalares no Fabric Data Warehouse:

Em comunicado SELECT :

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

WHERE Numa cláusula:

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

JOIN Numa cláusula:

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 Numa cláusula:

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

Em declarações de linguagem de manipulação de dados (DML) como INSERT, UPDATEou 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';

Conteúdo relacionado

• Inlining UDF escalar
• Assistente de migração do Fabric Data Warehouse

Aplica-se a: do Azure Synapse AnalyticsAnalytics Platform System (PDW)

Cria uma função definida pelo usuário (UDF) no Azure Synapse Analytics ou no Analytics Platform System (PDW). Uma função definida pelo usuário é uma rotina Transact-SQL que aceita parâmetros, executa uma ação, como um cálculo complexo, e retorna o resultado dessa ação como um valor. As funções com valor de tabela (TVFs) definidas pelo usuário retornam um tipo de dados de tabela.

• No Analytics Platform System (PDW), o valor de retorno deve ser um valor escalar (único).

• No Azure Synapse Analytics, CREATE FUNCTION pode retornar uma tabela usando a sintaxe para funções com valor de tabela embutido (visualização) ou pode retornar um único valor usando a sintaxe para funções escalares.

• Em pools SQL sem servidor no Azure Synapse Analytics, pode criar funções de valor de tabela embutidas, CREATE FUNCTION mas não funções escalares.

  Use esta declaração para criar uma rotina reutilizável que possa usar das seguintes formas:

• Em Transact-SQL declarações como SELECT

• Em aplicativos que chamam a função

• Na definição de outra função definida pelo utilizador

• Para definir uma restrição CHECK em uma coluna

• Para substituir um procedimento armazenado

• Usar uma função embutida como um predicado de filtro para uma diretiva de segurança

Transact-SQL convenções de sintaxe

Sintaxe

Sintaxe da função escalar

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

Sintaxe da função com valor de tabela embutido

-- 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 [ ) ]
[ ; ]

Argumentos

schema_name

O nome do esquema ao qual a função definida pelo usuário pertence.

function_name

O nome da função definida pelo usuário. Os nomes das funções devem seguir as regras dos identificadores e ser únicos dentro da base de dados e do seu esquema.

@ parameter_name

Um parâmetro na função definida pelo usuário. Pode declarar um ou mais parâmetros.

Uma função pode ter até 2.100 parâmetros. Quando um utilizador ou aplicação chama uma função, o valor de cada parâmetro declarado deve ser fornecido, a menos que seja definido um padrão para o parâmetro.

Especifique um nome de parâmetro usando um sinal de arroba (@) como o primeiro caractere. O nome do parâmetro deve seguir as regras dos identificadores. Os parâmetros são locais à função; Podes usar os mesmos nomes de parâmetros noutras funções. Os parâmetros só podem substituir constantes; não podem ser usados em vez de nomes de tabelas, nomes de colunas ou nomes de outros objetos de base de dados.

parameter_data_type

O tipo de dados do parâmetro. Para funções Transact-SQL, todos os tipos de dados escalares suportados no Azure Synapse Analytics são permitidos. O tipo de dado timestamp (rowversion) não é um tipo suportado.

[ = padrão ]

Um valor padrão para o parâmetro. Se definir um valor por defeito , pode executar a função sem especificar um valor para esse parâmetro.

Quando um parâmetro da função tem um valor predefinido, deve especificar a palavra-chave DEFAULT ao chamar a função para recuperar o valor predefinido. Esse comportamento é diferente do uso de parâmetros com valores padrão em procedimentos armazenados em que omitir o parâmetro também implica o valor padrão.

return_data_type

O valor de retorno de uma função escalar definida pelo usuário. Para funções Transact-SQL, todos os tipos de dados escalares suportados no Azure Synapse Analytics são permitidos. O tipo de datade timestamp da rowversion/ não é um tipo suportado. Os tipos não escalares de cursor e tabela não são permitidos.

function_body

Série de declarações Transact-SQL. O function_body não pode conter uma SELECT instrução nem referenciar dados da base de dados. A function_body não pode consultar tabelas ou vistas. O corpo de funções pode chamar outras funções determinísticas, mas não pode chamar funções não determinísticas.

Em funções escalares, function_body é uma série de Transact-SQL instruções que, juntas, avaliam até um valor escalar.

scalar_expression

Especifica o valor escalar que a função escalar retorna.

select_stmt

A instrução única SELECT que define o valor de retorno de uma função com valor de tabela embutido. Para uma função com valores de tabela em linha, não existe corpo de funções; a tabela é o conjunto de resultados de uma única SELECT afirmação.

TABLE

Especifica que o valor de retorno da função com valor de tabela (TVF) é uma tabela. Só podes passar constantes e @local_variables aos TVFs.

Nos TVFs inline (pré-visualização), define-se o TABLE valor de retorno através de uma única SELECT instrução. As funções embutidas não têm variáveis de retorno associadas.

<function_option>

Especifica que a função tem uma ou mais das seguintes opções.

SCHEMABINDING

Especifica que a função está vinculada aos objetos de banco de dados aos quais faz referência. Quando especificas SCHEMABINDING, não podes modificar os objetos subjacentes (como uma vista ou uma tabela, por exemplo) de uma forma que afete a definição da função. Deve primeiro modificar ou eliminar a definição da função para remover dependências do objeto que pretende modificar.

A associação da função aos objetos aos quais ela faz referência é removida somente quando ocorre uma das seguintes ações:

• Deixas de usar a função.

• Usa ALTER a declaração de função e remove a SCHEMABINDING opção.

Só pode vincular um esquema a uma função se as seguintes condições forem verdadeiras:

• Quaisquer funções definidas pelo utilizador que a função referenciam também são limitadas ao esquema.

• As referências de funções usam nomes de uma ou duas partes.

• No corpo dos UDFs, só pode referenciar funções incorporadas e outros UDFs na mesma base de dados.

• O utilizador que executa a CREATE FUNCTION instrução tem permissão REFERENCES sobre os objetos da base de dados que a função referencia.

Para remover SCHEMABINDING, use ALTER.

DEVOLVE NULL NA ENTRADA NULA | CHAMADA NA ENTRADA NULA

Especifica o OnNULLCall atributo de uma função com valor escalar. Se não especificares este atributo, CALLED ON NULL INPUT está implícito por defeito, e o corpo da função executa-se mesmo que NULL seja passado como argumento.

Melhores práticas

Se não criar uma função definida pelo utilizador com a cláusula SCHEMABIND, alterações aos objetos subjacentes podem afetar a definição da função e causar resultados inesperados quando a invoca. Especifica a WITH SCHEMABINDING cláusula quando criares a função. Esta cláusula garante que não podes modificar os objetos referenciados na definição da função, a menos que também modifiques a função.

Interoperabilidade

As instruções a seguir são válidas em uma função de valor escalar:

• Declarações de atribuição.

• Instruções de controlo do fluxo, exceto TRY... Declarações CATCH.

• Instruções DECLARE que definem variáveis locais de dados.

Numa função com valores de tabela inline (pré-visualização), só pode usar uma única instrução select.

Limitações

Não podes usar funções definidas pelo utilizador para realizar ações que modifiquem o estado da base de dados.

Podes aninhar funções definidas pelo utilizador. Uma função definida pelo utilizador pode chamar outra. O nível de aninhamento incrementa quando a função chamada inicia a execução, e diminui quando a função chamada termina a execução. Se ultrapassar os níveis máximos de nesting, toda a cadeia de funções de chamada falha.

Não pode criar objetos, incluindo funções, na master base de dados do seu pool SQL serverless no Azure Synapse Analytics.

Metadados

Esta seção lista as exibições do catálogo do sistema que você pode usar para retornar metadados sobre funções definidas pelo usuário.

• sys.sql_modules: Exibe a definição de Transact-SQL funções definidas pelo usuário. Por exemplo:

  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: Exibe informações sobre os parâmetros definidos em funções definidas pelo usuário.

• sys.sql_expression_dependencies: Exibe os objetos subjacentes referenciados por uma função.

Permissões

Requer CREATE FUNCTION permissão na base de dados e permissão ALTER no esquema onde a função está a ser criada.

Exemplos

Um. Usar uma função definida pelo usuário com valor escalar para alterar um tipo de dados

Esta função simples recebe um tipo de dado int como entrada e devolve um tipo de dado decimal(10,2) como saída.

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';  

B. Criar uma função com valor de tabela embutido

O exemplo seguinte cria uma função inline com valores de tabela que devolve informações-chave sobre módulos, filtrando pelo objectType parâmetro. Inclui um valor padrão para devolver todos os módulos quando chamas a função com o DEFAULT parâmetro. Este exemplo utiliza algumas das visualizações de catálogo do sistema mencionadas em Metadados.

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

Pode chamar a função para devolver todos os objetos da vista (V) com:

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

C. Combinar resultados de uma função com valor de tabela embutido

Este exemplo simples utiliza o TVF inline previamente criado para demonstrar como pode combinar os seus resultados com outras tabelas usando CROSS APPLY. Neste exemplo, seleciona todas as colunas tanto de sys.objects como dos resultados de ModulesByType para todas as linhas que correspondem na type coluna. Para mais informações sobre a utilização APPLYde , veja a cláusula FROM mais JOIN, APPLY, PIVOT (Transact-SQL).

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

Próximo passo