CREATE FUNCTION

Aplica-se a:Ponto de extremidade de análise de 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 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 escalares retornam um valor escalar, como um número ou cadeia de caracteres. AS TVFs (funções com valor de tabela) definidas pelo usuário retornam uma tabela.

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

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

Você pode especificar CREATE OR ALTER FUNCTION para criar uma nova função se não existir com esse nome, ou alterar uma função existente, em uma única instrução.

Convenções de sintaxe de Transact-SQL

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 de função com valor de tabela embutida

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 do banco de dados e seu esquema.

@ Parameter_name

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

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

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 para a função; Você pode usar os mesmos nomes de parâmetros em outras funções. Parâmetros só podem substituir constantes; Eles não podem ser usados no lugar de nomes de tabelas, nomes de colunas ou nomes de outros objetos de banco de dados.

parameter_data_type

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

[ = padrão ]

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

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

return_data_type

O valor retornado 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 o carimbo dedata/hora/. Tipos não escalares como tabela não são permitidos.

function_body

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

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

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

scalar_expression

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

select_stmt

A única SELECT instrução que define o valor retornado de uma função embutida com valor de tabela. Para uma função de tabela em linha, não há corpo de função; a tabela é o conjunto de resultados de uma única SELECT afirmação.

TABLE

Especifica que o valor retornado da TVF (função com valor de tabela) é uma tabela. Você só pode passar constantes e @local_variables para TVFs.

Em TVFs inline (pré-visualização), você define o TABLE valor de retorno por meio 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á associada aos objetos de banco de dados referenciados por ela. Quando você especifica SCHEMABINDING, não pode modificar os objetos subjacentes (como uma vista ou uma tabela, por exemplo) de uma forma que afete a definição da função. Você deve primeiro modificar ou eliminar a definição da função para remover dependências do objeto que deseja modificar.

A associação da função aos objetos referenciados por ela será removida somente quando ocorrer uma das ações a seguir:

• Você deixa a função para fora.

• Você ALTER usa a instrução de função e remove a SCHEMABINDING opção.

Você só pode vincular uma função por schema se as seguintes condições forem verdadeiras:

• Quaisquer funções definidas pelo usuário que a função referenciam também são vinculadas ao esquema.

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

• Dentro do corpo dos UDFs, você só pode referenciar funções embutidas e outros UDFs no mesmo banco de dados.

• O usuário que executa a CREATE FUNCTION instrução tem permissão REFERENCES sobre os objetos de banco de dados que a função referencia.

Para remover SCHEMABINDING, use ALTER.

RETORNA NULO NA ENTRADA NULA | CHAMADO NA ENTRADA NULA

Especifica o OnNULLCall atributo de uma função com valor escalar. Se você não especificar esse atributo, CALLED ON NULL INPUT é implícito por padrão, e o corpo da função executa mesmo que NULL seja passado como argumento.

Práticas recomendadas

• Se você não criar uma função definida pelo usuário com schemabinding, mudanças nos objetos subjacentes podem afetar a definição da função e causar resultados inesperados ao invocar a função. Quando você especifica WITH SCHEMABINDING quando cria a função, garante que mudanças posteriores nos objetos subjacentes não possam alterar ou quebrar o comportamento da função.

• Escreva suas funções definidas pelo usuário para serem inlineáveis. Para saber mais, confira Scalar UDF Inlining (Embutimento de UDF escalar).

Interoperabilidade

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

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

Funções escalares definidas pelo usuário

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

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

• As seguintes funções internas não têm suporte 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 usados 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 nossa CONTINUE declaração.
  • Existe uma chamada escalar recursiva para UDF.

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

  • O UDF escalar contém qualquer um desses tipos de dados como parâmetro de entrada, variável local ou tipo de dado de retorno: varchar(max),nvarchar(max), varbinary(max), binary(max).
  • O corpo escalar das UDFs contém chamadas para outros UDFs escalares.
  • O corpo escalar do UDF contém referências a tabelas/views/iTVF.

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

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

  • O UDF escalar contém qualquer um desses tipos de dados como parâmetro de entrada, variável local ou tipo de dado de retorno: varchar(max),nvarchar(max), varbinary(max), binary(max).
  • O corpo escalar das UDFs contém chamadas para outros UDFs escalares.
  • O corpo escalar do UDF contém referências a tabelas/views/iTVF.

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

Limitações

Você não pode usar funções definidas pelo usuário para realizar ações que modificam o estado do banco de dados.

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

Metadados

Esta seção lista as exibições do catálogo do sistema que podem ser usadas 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, bem como informações 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

Membros das funções Administrador, Membro e Colaborador do workspace do Fabric podem criar funções.

Embutimento de UDF escalar

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

O inlining do UDF escalar está ativado por padrão.

Alguma sintaxe T-SQL torna um UDF escalar não estálineável. Por exemplo, funções que contêm uma combinação de um WHILE loop e referenciam uma tabela dentro do corpo do UDF não podem ser inlineadas. Para obter mais informações, consulte requisitos de inlining da UDF escalar.

Verifique se uma UDF escalar pode ser embutida

A sys.sql_modules exibição do catálogo inclui a coluna is_inlineable, que indica se uma UDF é embutida. A is_inlineable propriedade vem da verificação da sintaxe dentro da definição do UDF. O UDF escalar não é inlinado antes do momento da compilação.

A inline_eligibility_mask propriedade explica qual 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 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 é inlineável, isso não garante que ele esteja sempre em linha quando a consulta for compilada.

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

Use a seguinte consulta de exemplo para verificar se uma UDF escalar é embutida:

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, você ainda pode executar a consulta como uma chamada independente, por exemplo, para definir uma variável. Mas a função escalar não pode fazer parte de uma SELECT ... FROM consulta em uma tabela de usuário. Por exemplo:

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

A função escalar definida pelo usuário da amostra dbo.custom_SYSUTCDATETIME não é inlineável devido ao uso de uma função do sistema não determinante, SYSUTCDATETIME(). Ele falha quando usado em uma SELECT ... FROM consulta em uma tabela de usuário, mas tem sucesso como uma chamada independente. Por exemplo:

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

Exemplos

R. Criar uma função com valor de tabela embutida

O exemplo a seguir cria uma função inline com valores em tabela que retorna informações-chave nos módulos, filtrando pelo objectType parâmetro. Ele inclui um valor padrão para retornar todos os módulos quando você chama 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 retornar todas as funções de tabela inline (IF):

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

Ou encontre 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 embutida

Este exemplo simples usa o TVF inline criado anteriormente para demonstrar como você pode combinar seus resultados com outras tabelas usando CROSS APPLY. Aqui, você seleciona todas as colunas tanto quanto sys.objects os resultados de ModulesByType para todas as linhas que correspondem na type coluna. Para mais informações sobre o uso APPLYde , veja 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 uma UDF escalar embutida 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 uma SELECT instrução:

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

Em uma WHERE 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'

Em uma JOIN 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);

Em uma ORDER BY cláusula:

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

Em instruções DML (linguagem de manipulação de dados), 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

• Sublinhado de UDF escalar
• Assistente de Migração do Fabric Data Warehouse

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

Cria uma UDF (função definida pelo usuário) no Azure Synapse Analytics ou PDW (Analytics Platform System). 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 TVFs (funções com valor de tabela) definidas pelo usuário retornam um tipo de dados de tabela.

• Em PDW (Analytics Platform System), o valor retornado deve ser um valor escalar (único).

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

• Em pools de 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 você possa usar das seguintes formas:

• Em instruções Transact-SQL, como SELECT

• Em aplicativos que chamam a função

• Na definição de outra função definida pelo usuário

• 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 política de segurança

Convenções de sintaxe de Transact-SQL

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 de função com valor de tabela embutida

-- 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 do banco de dados e seu esquema.

@ Parameter_name

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

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

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 para a função; Você pode usar os mesmos nomes de parâmetros em outras funções. Parâmetros só podem substituir constantes; Eles não podem ser usados no lugar de nomes de tabelas, nomes de colunas ou nomes de outros objetos de banco de dados.

parameter_data_type

O tipo de dados de parâmetro. Para funções Transact-SQL, todos os tipos de dados escalares compatíveis com o 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 você definir um valor padrão , pode executar a função sem especificar um valor para esse parâmetro.

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

return_data_type

O valor retornado de uma função escalar definida pelo usuário. Para funções Transact-SQL, todos os tipos de dados escalares compatíveis com o Azure Synapse Analytics são permitidos. O tipo dedado de 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 instruções Transact-SQL. O function_body não pode conter uma SELECT instrução nem referenciar dados do banco de dados. O 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 instruções Transact-SQL que juntas são avaliadas para um valor escalar.

scalar_expression

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

select_stmt

A única SELECT instrução que define o valor retornado de uma função embutida com valor de tabela. Para uma função de tabela em linha, não há corpo de função; a tabela é o conjunto de resultados de uma única SELECT afirmação.

TABLE

Especifica que o valor retornado da TVF (função com valor de tabela) é uma tabela. Você só pode passar constantes e @local_variables para TVFs.

Em TVFs inline (pré-visualização), você define o TABLE valor de retorno por meio 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 opções a seguir.

SCHEMABINDING

Especifica que a função está associada aos objetos de banco de dados referenciados por ela. Quando você especifica SCHEMABINDING, não pode modificar os objetos subjacentes (como uma vista ou uma tabela, por exemplo) de uma forma que afete a definição da função. Você deve primeiro modificar ou eliminar a definição da função para remover dependências do objeto que deseja modificar.

A associação da função aos objetos referenciados por ela será removida somente quando ocorrer uma das ações a seguir:

• Você deixa a função para fora.

• Você ALTER usa a instrução de função e remove a SCHEMABINDING opção.

Você só pode vincular uma função por schema se as seguintes condições forem verdadeiras:

• Quaisquer funções definidas pelo usuário que a função referenciam também são vinculadas ao esquema.

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

• Dentro do corpo dos UDFs, você só pode referenciar funções embutidas e outros UDFs no mesmo banco de dados.

• O usuário que executa a CREATE FUNCTION instrução tem permissão REFERENCES sobre os objetos de banco de dados que a função referencia.

Para remover SCHEMABINDING, use ALTER.

RETORNA NULO NA ENTRADA NULA | CHAMADO NA ENTRADA NULA

Especifica o OnNULLCall atributo de uma função com valor escalar. Se você não especificar esse atributo, CALLED ON NULL INPUT é implícito por padrão, e o corpo da função executa mesmo que NULL seja passado como argumento.

Práticas recomendadas

Se você não criar uma função definida pelo usuário com a cláusula SCHEMABIND, alterações nos objetos subjacentes podem afetar a definição da função e causar resultados inesperados ao invocá-la. Especifique a WITH SCHEMABINDING cláusula ao criar a função. Essa cláusula garante que você não possa modificar os objetos referenciados na definição da função, a menos que também modifique a função.

Interoperabilidade

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

• Instruções de atribuição.

• Instruções de controle do fluxo, exceto TRY... CATCH declarações.

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

Em uma função de valores de tabela inline (prévia), você só pode usar uma única instrução select.

Limitações

Você não pode usar funções definidas pelo usuário para realizar ações que modificam o estado do banco de dados.

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

Você não pode criar objetos, incluindo funções, no master banco 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 podem ser usadas 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 no banco de dados e permissão ALTER no esquema em que a função está sendo criada.

Exemplos

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

Essa função simples recebe um tipo de dado int como entrada e retorna 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 embutida

O exemplo a seguir cria uma função inline com valores em tabela que retorna informações-chave nos módulos, filtrando pelo objectType parâmetro. Ele inclui um valor padrão para retornar todos os módulos quando você chama 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

Você pode chamar a função para retornar todos os objetos da vista (V) com:

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

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

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

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

Próxima etapa